001/*
002 * Copyright 2015 The Error Prone Authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package com.google.errorprone.annotations;
017
018import static java.lang.annotation.ElementType.TYPE;
019import static java.lang.annotation.RetentionPolicy.SOURCE;
020
021import java.lang.annotation.Documented;
022import java.lang.annotation.Inherited;
023import java.lang.annotation.Retention;
024import java.lang.annotation.Target;
025
026/**
027 * The class to which this annotation is applied is immutable.
028 *
029 * <p>An object is immutable if its state cannot be observed to change after construction. Immutable
030 * objects are inherently thread-safe.
031 *
032 * <p>A class is immutable if all instances of that class are immutable. The immutability of a class
033 * can only be fully guaranteed if the class is final, otherwise one must ensure all subclasses are
034 * also immutable.
035 *
036 * <p>A conservative definition of object immutability is:
037 *
038 * <ul>
039 *   <li>All fields are final;
040 *   <li>All reference fields are of immutable type, or null;
041 *   <li>It is <em>properly constructed</em> (the {@code this} reference does not escape the
042 *       constructor).
043 * </ul>
044 *
045 * <p>The requirement that all reference fields be immutable ensures <em>deep</em> immutability,
046 * meaning all contained state is also immutable. A weaker property, common with container classes,
047 * is <em>shallow</em> immutability, which allows some of the object's fields to point to mutable
048 * objects. One example of shallow immutability is guava's ImmutableList, which may contain mutable
049 * elements.
050 *
051 * <p>It is possible to implement immutable classes with some internal mutable state, as long as
052 * callers can never observe changes to that state. For example, some state may be lazily
053 * initialized to improve performance.
054 *
055 * <p>It is also technically possible to have an immutable object with non-final fields (see the
056 * implementation of {@link String#hashCode()} for an example), but doing this correctly requires
057 * subtle reasoning about safe data races and deep knowledge of the Java Memory Model.
058 *
059 * <p>Use of this annotation is validated by <a
060 * href="https://errorprone.info/bugpattern/Immutable">Error Prone's immutability analysis</a>, which
061 * ensures that all {@code @Immutable}-annotated classes are deeply immutable according to the
062 * conservative definition above. Non-final classes may be annotated with {@code @Immutable}, and
063 * any code compiled by Error Prone will be checked to ensure that no mutable subtypes of
064 * {@code @Immutable}-annotated classes exist.
065 *
066 * <p>For more information about immutability, see:
067 *
068 * <ul>
069 *   <li>Java Concurrency in Practice §3.4
070 *   <li>Effective Java 3rd Edition §17
071 * </ul>
072 */
073@Documented
074@Target(TYPE)
075@Retention(SOURCE)
076@Inherited
077public @interface Immutable {
078
079  /**
080   * When annotating a generic type as immutable, {@code containerOf} specifies which type
081   * parameters must be instantiated with immutable types for the container to be deeply immutable.
082   */
083  String[] containerOf() default {};
084}