The Road to Immutability

First, what do we want intuitively? A useful form of immutability, less strong than deeply immutable, but stronger than final fields for many situations. We propose the following description:

Technically, immutability is much harder to define than final fields. We identify three rules, on top of the obvious final fields requirement. The first one prevents the type from making changes to its own fields:

Our friend the Pair satisfies this first rule:

Note that since K and V are unbound generic types, it is not even possible to modify their content from inside ` Pair`, since there are no modifying methods one can call on unbound types. The types K and V are hidden in Pair; it does not have any accessible content.

How does it fit the intuitive rule for immutability? The type Pair holds two objects. The type does not change their content, nor will it exchange these two objects for others, or allow others to do so. It is clear the users of Pair may be able to change the content of the objects they put in the Pair. Summarizing: Pair fits the intuitive definition nicely.

Here is an example which shows the necessity of the first rule more explicitly:

The fields point1 and point2 are effectively final. Without the translation method, the fields would be @NotModified as well. The translation method modifies the fields' content, preventing the type from becoming immutable.

From the restriction of rule 1, that all its fields should remain unmodified, it follows that, excluding external changes, every method call on a immutable container object with the same arguments will render the same result. We note that this statement cannot be bypassed by using static state, i.e., state specific to the type rather than the object. The definitions make no distinction between static and instance fields.

To obtain a useful definition of immutability, one which is not too strict yet follows our intuitive requirements, we should allow modifiable fields, if they are properly shielded from the modifications they intrinsically allow. We will introduce two additional rules to constrain the modifications of this modifiable data. Together with the first rule, and building on final fields, we define:

Rule 2 is there to ensure that the modifiable fields of the object cannot be modified externally by means of direct field access to the non-private fields. Rule 3 ensures that the modifiable fields of the object cannot be modified externally by obtaining or sharing references to the fields via a parameter or return value.

Types which are immutable will be marked @Immutable . When they are containers too, which should be the large majority, we use @ImmutableContainer as a shorthand for the combination of the two annotations.

Note that:

Let us go to examples immediately.

After creation, external changes to the source array ts are effectively modifications to the field data. This construct fails rule 3, as the parameter ts is dependent. The field is a modifiable data structure, and must be shielded from external modifications.

Note the use of @Independent(hc=true) annotation on the return value of stream(), to indicate that modifications to the hidden content are possible on objects obtained from the stream.

Users of this type can modify the content of the array using direct field access! This construct fails rule 2, which applies for the same reasons as in the previous example.

The independence rule enforces the type to have its own modifiable structure, rather than someone else’s. Here is the same group of examples, now with JDK Collections:

The lack of independence of the constructor violates rule 3 in the first example.

Here, the data field is public, which allows for external modification.

Finally, we have an immutable type. The next one is immutable as well:

The section on Dynamic type annotations will explain how the @Immutable annotation travels to the field data.

The independence rule, rule 3, is there to ensure that the type does not expose its modifiable data through parameters and return types:

Note that by decomposing rules 0 and 1, we observe that requiring all fields to be @Final and @NotModified is equivalent to requiring that all non-private fields have the final modifier, and that methods that are not part of the construction phase, are @NotModified. The final example shows a type which violates this rule 1, because a modifying method has been added:

Deriving from an immutable class is the most normal situation: since java.lang.Object is an immutable container, every class will do so. Clearly, the property is not inherited.

Most importantly, in terms of inheritance, is that the analyser prohibits changing the modification status of methods from non-modifying to modifying in a derived type. This means, for example, that the analyser will block a modifying equals() or toString() method, in any class. Similarly, no implementation of java.util.Collection.size() will be allowed to be modifying.

The guiding principle here is that of consistency of expectation: software developers are expecting that equals is non-modifying. They know that a setter will make an assignment, but they’ll expect a getter to simply return a value. No getter should ever be modifying.

The other direction is more interesting, while equally simple to explain: deriving from a parent class cannot increase the immutability level. A method overriding one marked @Modified does not have to be modifying, but it is not allowed to be explicitly marked @NotModified:

Following the same principles, we observe that types deriving from a @Container super-type need not be a container themselves. So while we may state that Collection is a container, it is perfectly possible to implement a collection which has public methods which modify their parameters, as long as the methods inherited from Collection do not modify their parameters, and the implementation does not modify the objects linked to the parameters of the Collection methods.

Note that sealed types (since JDK 17) reject the 'you can always extend' assumptions of Java types. In this case, all subtypes are known, and visible. The single practical consequence is that if the parent type is abstract, its annotations need not be contracted: they can be computed because all implementations are available to the analyser.

Type parameters are either unbound, in which case they can represent any type, or they explicitly extend a given type. Because the unbound case is simply a way of saying that the type parameter extends java.lang.Object, we can say that all type parameters extend a certain type, say T extends E.

The analyser simply treats the parameterized type T as if it were the type E. In the case of an unbound parameter type, only the public methods of java.lang.Object are accessible. By definition, the type belongs to the hidden content, as defined in Accessible and hidden content.

The analyser recognises types that can be replaced by an unbound parameter type, when they are used transparently, and therefore belong to the hidden content: no methods are called on it, save the ones from java.lang.Object; none of its fields are accessed, and it is not used as an argument to parameters where anything more specific than java.lang.Object is required. It will issue a warning, and internally treat the type as an unbound parameter type, and hence @ImmutableContainer , even if the type is obviously modifiable.

The following trivial example should clarify:

Nowhere in OddPair do we make actual use of the fact that set is of type Set, or sb is of type StringBuilder. The analyser encourages you to replace Set by some unbound parameter type, say K, and StringBuilder by some other, say V. The result is, of course, the type Pair as defined earlier.

Making a concrete choices for a type parameter may have an effect on the immutability status, as will be explained in More on hidden content. Some examples are easy to see: any @FinalFields type whose fields consist only of types of unbound type parameter, will become immutable when the unbound type parameters are substituted for immutable types. Any immutable type whose hidden content consists only of types of unbound type parameter, will become deeply immutable (i.e., devoid of hidden content) when the unbound type parameters are substituted for deeply immutable types. The Pair mentioned before is a case in point, and an example for both rules: Pair<Integer, Long> is deeply immutable.

Because java.lang.Object is an immutable container, trivial extensions are, too:

Things only become interesting when methods enter the picture. Annotation-wise, we stipulate that

Furthermore, we will also impose special variants of the rules for immutability of an abstract type T, to be obeyed by the abstract methods:

The consequence of these choices is that implementations and extensions of abstract and non-abstract types will have the opportunity to have the same immutability properties. This allows us, e.g., to treat any implementation of Comparable, defined as:

as an immutable type when the only method we can access is compareTo.

As for as the modification status of the parameters of abstract methods is concerned, we start off with @Modified rather than with @NotModified:

While it is possible to compute the immutability and container status of interface types, using the rules presented above, it often makes more practical sense to use the annotations as contracts: they may save a lot of annotation work on the abstract methods in the interface. We repeat that no implementation of a immutable interface is guaranteed to be immutable itself; nor does this guarantee hold for the container property unless no new non-private methods have been added.

We continue this section with some examples which will form the backbone of the examples in More on hidden content.

If semantically used correctly, types implementing the HasSize interface expose a single numeric aspect of their content:

We extend to:

The Consumer interface is defined and annotated as:

Implementations of the accept method are allowed to be modifying (even though in NonEmptyImmutableList.visit we decide to ignore this modification!). They are also allowed to modify their parameter, as we will demonstrate shortly.

Let’s downgrade from @ImmutableContainer to @FinalFields @Container by adding a modifying method:

The method setFirst goes against the default annotations twice: because it is modifying, and because it promises to keep its parameter unmodified thanks to the @Container annotation on the type. The @Independent(hc=true) annotation states that arguments to setFirst will end up in the hidden content of the NonEmptyList. Implementations can even lose @FinalFields :

Here is a (slightly more convoluted) implementation that remains @FinalFields and @Container :

Obviously, an @ImmutableContainer implementation is not possible: the immutability status of an extension (OneWithOne, One) cannot be better than that of the type it is extending from (NonEmptyList).

We end the section by showing how concrete implementations of the accept method in Consumer can make modifications. First, modifications to the parameter:

The last statement is maybe more easily seen as:

Second, modifications to the fields of the type:

Up to now, we have made no distinction between static fields and instance fields: modifications are modifications. Inside a primary type, we will stick to this rule. In the following example, each call to getK increments a counter, which is a modifying operation because the type owns the counter:

We can explicitly ignore modifications with the contracted @IgnoreModifications annotation, which may make sense from a semantic point of view:

Note that when the modification takes place inside the constructor, it is still not ignored, because for static fields, static code blocks act as the constructor:

Only modifications in a static code block are ignored:

Nevertheless, we introduce the following rule which does distinguish between modifications on static and instance types:

This is still consistent with the rules of immutable types, which only look at the fields and assume that when methods do not modify the fields, they are actually non-modifying. Without an @IgnoreModifications annotation on the field System.out (which we would typically add), printing to the console results in

We leave it up to the programmer or designer to determine whether static calls deserve a @StaticSideEffects warning, or not. In almost all instances, we prefer a singleton instance (see Singleton classes) over a class with modifying static methods. In singletons the normal modification rules apply, unless @IgnoreModifications decorates the static field giving access to the singleton.

Quoting from the JDK 8 documentation, value-based classes are

Item 1 requires final fields but does not specify any of the restrictions we require for immutability. Item 2 implies that should equals, hashCode or toString make a modification to the object, its state changes, which would then change the object with respect to other objects. We could conclude that these three methods cannot be modifying.

Loosely speaking, objects of a value-based class can be identified by the values of their fields. Immutability is not a requirement to be a value-based class. However, we expect many immutable types will become value-classes. Revisiting the example from the previous section, we can construct a counter-example:

The equals method violates item 2 of the value-class definition, maybe not to the letter but at least in its spirit: the field k is arguably the most important field, and its value is not taken into account when computing equality.

When it is clear a method returns an immutable set, but the formal type is java.util.Set, the @Immutable annotation can 'travel':

Whilst Set in general is not @Immutable , the data field itself is.

The computations that the analyser needs to track dynamic type annotations, are similar to those it needs to compute eventual immutability. We introduce them in the next chapter.

We start with the well-established builder paradigm.

If your code can live with two different types (Polygon.Builder, Polygon) to represent polygons in their different stages (mutable, immutable), the builder paradigm is great. If, on the other hand, you want to hold polygons in a type that spans both stages of the polygon lifecycle, it becomes difficult to do this with an eye on immutability. One solution is the use of an interface that is implemented both by the builder and the immutable type.

The FirstThen type can also assist in this situation: it holds an initial object (the first) until a state change occurs, and it is forced to hold a second object (the then). Once it is in the final state, it cannot change anymore. It is eventually immutable:

We propose a system of eventual immutability based on a single transition of state inside an object.

The analyser has no problem detecting the presence of preconditions, and observing that one method changes its own precondition. The rules, however, are sufficiently general to support arbitrary preconditions, as shown in the following variant. This example does not require an additional field, but relies on the empty/not-empty state change:

Let us summarize the annotations:

In each of these annotations, the actual value of the …​ in the after= or before= parameters is the name of the field.

In case there are multiple fields involved, their names are represented in a comma-separated fashion.

The @Mark and @Only annotations can also be assigned to parameters, in the event that marked methods are called on a parameter of eventually immutable type. Consider the following utility method for EventuallyFinal, frequently used in the analyser’s own code:

Here, the setFinal method’s @Mark annotation travels to the parameter, where it is applied to the argument each time the static method is applied.

The support types detailed in Support classes can be used as building blocks to make ever more complex eventually immutable classes. Effectively final fields of eventually immutable type will at some point hold objects that are in their final or after state, in which case they act as immutable fields.

The analyser itself consists of many eventually immutable classes; we show some examples in Support classes in the analyser.

A method can return an eventually immutable object, guaranteed to be in its initial or before state. This can be annotated with @BeforeMark . Employing SimpleImmutableSet1 from the example above,

Similarly, the analyser can compute a parameter to be @BeforeMark , when in the method, at least one before-mark methods is called on the parameter.

Finally, a field can even be @BeforeMark , when it is created or arrives in the type as @BeforeMark , and stays in this state. This situation must occur in a type with a @Finalizer , as explained in Finalizers.

When a type is eventually @FinalFields , should the field(s) of the state transition be marked @Final ? Similarly, when a type is eventually immutable, should the analyser mark the initially mutable or assignable fields @Modified or @NotModified?

Basically, we propose to mark the end state, qualifying with the parameter after:

Since in an IDE it is not too easy to have multiple visual markers, it seems best to use the same visuals as the end state.

When a type is effectively @FinalFields (not eventually), all fields are effectively final. The analyser wants to emphasise the rules needed to obtain (eventual) immutability, by clearly indicating which fields break the immutability rules.

Eventual finality simply adds a @Final(after="mark") annotation to each of these situations.

A fair number of Java frameworks introduce dependency injection and initializer methods. This concept is, in many cases, compatible with the idea of eventual immutability: once dependency injection has taken place, and an initializing method has been called, the framework stops intervening in the value of the fields.

It is therefore not difficult to imagine, and implement in the analyser, a before state (initialization still ongoing) and an after state (initialization done) associated with the particular framework. The example below shows how this could be done for the Verticle interface of the vertx.io framework.

Currently, contracted eventual immutability has not been implemented yet in the analyser.

We need to study the situation of seemingly non-modifying methods with modifying parameters. Up to now, a method is only modifying when it assigns to a field, calls a modifying method on one of the fields, or directly calls a modifying method on this. However, there could be indirect modifications, as in:

This observation forces us to tighten the definition of a non-modifying method: on top of the definition given above, we have to ensure that none of the modifying methods called on a parameter which is @Modified , call one of 'our' modifying methods. These rules are mostly, but not easily, enforceable when all code is visible.

An additional interface can help to remove the circular dependency between the types. This has the advantage of simplicity, both for the programmer and the analyser, which at this point doesn’t handle circular dependencies very well. It imposes more annotation work on the programmer, however, because the interface’s methods need contracts.

To compute linking, the analyser tries to track actual objects, with the aim of knowing if a field links to another field or a parameter. It computes a dependency graph of variables depending on other variables, with the following four basic rules:

Note that saying v links to a is the same as saying that the return value of method links to some field inside A, the type of a. This is especially clear when a == this.

We discern a number of special cases:

Recall that primitives, java.lang.Object, java.lang.String, and unbound parameter types, are @Immutable .

This situation is similar to that of the constructor (rule 3), with a taking the role of v.

Most of the other linking computations are consequences of the basic rules above. For example,

Note: in a method call v = a.method(b, c, d), links between b, c, and d are possible. They are covered by the @Modified annotation: when a parameter is @NotModified, no modifications at all are possible, not even indirectly. We do not compute individual linking, because we advocate the use of containers: all parameters should be @NotModified.

Abstract methods are present in interfaces, and abstract classes. Their very definition is that no implementation is present at the place of definition: only the ins (parameters) and outs (return type) are pre-defined.

Functional interfaces are interfaces with a single abstract method; any other methods in the interface are required to have a default implementation. The following table lists some frequently used ones:

It is important not to forget that any interface defining a single abstract method can be seen as a functional interface. While the examples above all employ generics (more specifically, unbound type parameters), generics are not a requirement for functional interfaces. The Java language offers syntactic sugar for functional programming, but the types remain normal Java types.

We will not make any distinction between a functional interface and an abstract type. If one were forced to make one, the intention to hold data would be the dividing line between a functional interface, which conveys no such intention, and an abstract type, which does.

In this section we want to discuss a limited application of functional interfaces: the one where the SAMs have a local implementation. The general case, where objects of abstract types come in via a parameter, will be addressed in More on hidden content. Consider the following example:

The fields getAndIncrement and explicitGetAndIncrement hold instances of anonymous inner classes of ApplyLocalFunctions: these inner classes hold data, they have access to the myCounter field. Their concrete implementations of get each modify myCounter. A straightforward application of the rules of modification of fields makes getAndIncrement and explicitGetAndIncrement @Modified : in myIncrementer, a modifying method is applied to getAndIncrement, and in myExplicitIncrementer, a modifying method is applied to explicitGetAndIncrement.

Given that ApplyLocalFunctions is clearly @FinalFields , and the inner classes hold no other data, the inner classes are @FinalFields as well.

Now, if we move away from suppliers, but use consumers, we can discuss:

Using the @Container annotation in a dynamic way allows us to control which abstract types can use the method: when only containers are allowed, then the abstract types must not have implementations which change their parameters.

Let’s go back to NonEmptyImmutableList, first defined in Abstract methods:

We start the discussion with the following immutable implementation of this interface:

According to the interface contract, we need the visit method to be non-modifying, and also not to modify its parameter consumer. However, following the normal definitions of modification, the following two statements hold:

The result of the first statement would violate the @Container property on ImmutableOne, and we’d be very reluctant to do that: according to the intuitive definition in Containers, ImmutableOne is a type that holds data, but does not change the data it has been given. This statement still holds in the presence of a visit method, which is nothing but a way of exposing the object in a way similar to the method first. The second statement would make visit modifying, which again goes against our intuition: looping over elements is, in itself, not modifying.

Luckily, there are two observations that come to the rescue.

First, we believe it is correct to assume that concrete implementations of Consumer are semantically unrelated to ImmutableOne. As a consequence, we could say that the only modifications that concern us in this visit method, are the potential modifications to accept 's parameter t. Other modifications, for example those to the fields of the type in which the implementation is present, may be considered to be outside our scope.

However, if we replace Consumer by Set and accept by add, we encounter a modification that we really do not want to ignore, in an otherwise equal setting. Therefore, it does not look like we can reason away potential modifications by accept. We will have to revert to a contracted @IgnoreModifications annotation on the parameter consumer, if we want to avoid ImmutableOne losing the @Container property.

While we will ignore this second source of modification in the ImmutableOne type, we will defer or propagate it to the place where a concrete implementation of the consumer is presented. We can ignore it here, because t is part of the hidden content of the type; what happens to its content happens outside the zone of control of ImmutableOne. The fact that it is passed as an argument to a method of consumer is reflected by the @Independent annotation. It will take care of the propagation of modifications from the concrete implementation into the hidden content.

This results in the following annotations for visit in ImmutableOne:

Note that we assume that we will need @IgnoreModifications for almost every use of a functional interface from the package java.util.function occurring as a parameter. These types are for generic use; one should never use them to represent some specific data type where modifications are of concern to the current type. Therefore, we make this annotation implicit in exactly this context.

Looking at the more general case of a forEach implementation iterating over a list or array, we therefore end up with:

Modifications to the parameter, made by the concrete implementation, are propagated into the hidden content of list, as shown in the next section. The @Independent annotation appears because hidden content in list is exposed to the consumer parameter. This annotation does not appear for the accessible content of the immutable type.

Recall that parameters of modifiable type can already be shielded from external modification by the @Independent annotation.

Let us apply the visit method of NonEmptyImmutableList to StringBuilder:

It is the second method, addNewLine, that is of importance here. Thanks to the @Modified annotation, we know of a modification to list. It may help to see the for-loop written out, if we temporarily assume that we have added an implementation of Iterable to NonEmptyImmutableList, functionally identical to visit:

Note that while NonEmptyImmutableList is immutable, its concrete instantiation gives access to a modifying method in its hidden content.

We really need the link between sb and list for the modification on sb to propagate to list. Without this propagation, we would not be able to implement the full definition of modification of parameters, as stipulated in Modification, in this relatively straightforward and probably frequently occurring situation.

Moving from NonEmptyImmutableList to NonEmptyList, defined here, which has a modifying method, allows us to contrast two different modifications:

Without storing additional information (e.g., using an as yet undefined parameter like @Modified(hc=true) on list in addNewLine), however, we cannot make the distinction between a modification to the string builders inside list, or a modification to list itself. In other words, applying the two methods further on, we cannot compute

Finally, we mention again the modification to a field from a concrete lambda:

Going back to ImmutableOne, we see that the constructor links the parameter t to the instance’s field by means of assignment. Let us call this binding of parameters of hidden content to the field content linking, and mark it using @Independent(hc=true) , content dependence:

Returning a part of the hidden content of the type, or exposing it as argument, both warrants a @Independent(hc=true) annotation:

Observe that content dependence implies absence of dependence, as described in Linking, dependence and How to compute linking, exactly because we are dealing with type parameters of an immutable type.

Another place where the hidden content linking can be seen, is the for-each statement:

Because the Collection API contains an add method annotated as:

indicating that after calling add, the argument will become part of the hidden content of the collection, we conclude that the local loop variable sb gets content linked to the builders list. Similarly, this loop variable contains hidden content from the list object.

Let us look at a possible implementation of Collection.addAll:

The call to add content links e to this. Because e is also content linked to c, the parameter collection holds content linked to the hidden content of the instance.

We are now properly armed to see how a for-each loop can be implemented using an iterator whose hidden content links to that of a container.

Let us start with the simplest definition of an iterator, without remove method:

Either the next method, or the hasNext method, must make a change to the iterator, because it has to keep track of the next element. As such, we make both @Modified . Following the discussion in the previous section, next is @Independent(hc=true) , because it returns part of the hidden content held by the iterator.

The interface Iterable is a supplier of iterators:

First, creating an iterator should never be a modifying operation on a type. Typically, as we explore in the next section, it implies creating a subtype, static or not, of the type implementing Iterable. Second, the iterator itself is independent of the fields of the implementing type, but has the ability to return its hidden content.

The loop, on a variable list of type implementing Iterable<T>, is expressed as for(T t: list) { …​ }, and can be interpreted as

The iterator it content-links to list; via the next method, it content-links the hidden content of the list to t.

A concrete implementation of an iterator is often a nested type, static or not (inner class), of the iterable type:

For ImmutableArray to be immutable, the iterator() method must be independent of the field elements, in other words, the IteratorImpl object must not expose the ImmutableArray 's fields to the outside world. It cannot be immutable itself, because it needs to hold the state of the iterator. However, it should protect the fields owned by its enclosing type, up to the same standard as required for immutability.

We propose to add a definition for the independence of a type, identical to the "shielding off" part of the definition of immutability. Let’s first go there in a roundabout way:

Clearly, such external modifications are only possible when the constructor, method or field is non-private.

Armed with this definition, we can define the independence of types:

This definition is entirely equivalent to the definition of immutability without rules 0 and 1, and rules 2 and 3 restricted to those fields that are 'exposed' to the outside world via linking or content linking.

Consider the static variant of IteratorImpl, which makes it more obvious that IteratorImpl maintains a reference to the element array of its enclosing type:

The type T is part of the hidden content, the T[] and the counter i are part of the accessible content. No external modification can impact the array or the counter; indeed, only T and a boolean are exposed. The latter is immutable, so does not allow modifications. The former allows modifications on the hidden content, whence the @Independent(hc=true) annotation for IteratorImpl.

Immutable types are independent as a type, but a type does not even have to be immutable to be independent. In fact, any type communicating via immutable types to the outside world is independent:

The following table summarizes the relationship between immutability and independence by means of example types:

Unless a class is marked final, sealed, or private, it can be extended in a different source file. In the context of immutability, this means that any extendable class is like an interface: it must allow for hidden content.

The analyser, however, can be pragmatic about this. Just as in the case of effectively final fields, it can compute types to be effectively final, or effectively sealed, when presented with the complete code base. Indeed, if there is a guarantee of being able to see all code, the analyser can easily compute if a type has effectively been extended, or not.

This observation shows that the distinction between immutability with and without hidden content, is rather small.

How does the whole story of eventually final fields and eventual immutability mix with hidden content? At some point, once a necessary precondition has been met, the hidden content will be well-defined, and modifying methods become unavailable. Before that, fields that will eventually contain the hidden content may still be null, or may be re-assigned. This should not have any effect, however, on the computation of hidden content linking, @Independent annotations, and the propagation of modifications, since the actual types do not change. The two concepts are sufficiently perpendicular to each other, and can easily co-exist.

A constant type can be defined as an immutable type whose fields are of constant type themselves. The basis of this recursion are the primitives, possibly boxed, java.lang.String, and java.lang.Class, i.e., all the types that can have a Java literal as a value.

The analyser marks a constant type by the string representation of its value, e.g., @ImmutableContainer("3.14"), but obviously only in case of fields and method return types. This seems to be the only practical use of this definition.

So while not really relevant, observe that types can be constant but not @Container ; they can be eventually constant, and they can be constant with hidden content.

Let us end this section with a note on the non-private requirement for field and method access. The definitions of immutability and independence insist on the properties holding for all non-private fields, methods and constructors.

First, consider nested types. Any nested type (a class defined either statically or nested inside another class, an interface defined inside another type) has access to the private methods of the primary type and other nested types inside the primary type. We first need to investigate whether this additional access plays havoc with the immutability and independence rules.

Because all nested types of a primary type are fully known at analysis time, as they must reside in the same .java file, it is possible to ensure that a field, accessible beyond its own class even though it is private to the nested type, remains @NotModified. Consider:

The solution here, clearly, is to extend the rules to all non-private methods and constructors of the primary type and all its nested types.

The second question to answer is whether we can or should relax the requirement of private access, e.g., for a restriction of 'private and same package', or even 'non-public'. Remember that the protected access modifier allows access to classes that inherit from the type, and to members of the same package.

First, consider allowing 'package-private'. If we were to assume that all types in the same package are fully visible to the analyser at the time of analysis, we could consider extending the rules to analyse all types in the package at the same time, as we did for nested types inside a primary type. However, firstly, it is perfectly possible, even if it is bad practice, to spread a package over multiple jars. This denies the analyser complete visibility over the types in a package. Secondly, the complications that arise computationally are too much for efficient analysis.

So there’s no point in considering protected access. Even if inheritance where the only criterion used to define this access level, we would not allow it, because the child class can be invisible to the analyser at the time of analysis of the parent.

When annotating APIs (see e2immu manual), we do use the public vs non-public criterion instead of the non-private vs private one, mostly as a matter of convenience. We assume (hope?) that library designers and implementers shield off internal types sufficiently, and rely on the project implementer to stick to their package prefix.

Simpler than FlipSwitch is not possible for an eventually immutable type: it consists solely of a single boolean, which is at the same time the data and the guard:

The obvious use case for this helper class is to indicate whether a certain job has been done, or not. Once it has been done, it can never be 'undone' again.

One step up from FlipSwitch is SetOnce: a place-holder for one object which can be filled exactly once:

The analyser relies heavily on this type, with additional support to allow setting multiple times, with exactly the same value. This can be ascertained with a helper method, which, as noted in the previous section, also gets the @Mark annotation.

Slightly more flexible than SetOnce is EventuallyFinal: the type allows you to keep writing objects using the setVariable method, until you write using setFinal. Then, the state changes and the type becomes immutable:

Note the occurrence of a negated @TestMark annotation: isVariable returns the negation of the normal iFinal mark test.

The previous support class, EventuallyFinal, forms the template for a more general approach to eventual immutability: allow free modifications, until the type is frozen and no modifications can be allowed anymore.

Note that as discussed in Inheritance, it is important for Freezable, as an abstract class, to be immutable: derived classes can never be immutable when their parents are not immutable.

We discuss one example that makes use of (derives from) Freezable: a freezable map where no objects can be overwritten:

The code analyser makes frequent use of this type, often with an additional guard that allows repeatedly putting the same value to a key.

Lazy implements a lazily-initialized immutable field, of unbound generic type T. Properly implemented, it is an eventually immutable type:

After calling the marker method get(), t cannot be assigned anymore, and it becomes @Final . The constructor parameter supplier is @Independent(hc=true), as its hidden content (the result of get()) links to that of Lazy, namely the field t.

But why is supplier as a field not linked to the constructor parameter? Clearly, supplier is part of the accessible content of Lazy, as its get() method gets called. The criterion is: a modification on one may cause a modification on the other. Modifications can only be made by calling the get() method, as there are no other methods, and no fields. Consequently, the constructor should link to the field, and supplier cannot be @Independent.

The answer lies in the eventual nature of Lazy: before the first call to get, the supplier field is of relevance to the type, and t is not. After the call to get(), the converse is true, because supplier has been emptied. We should extend rule 2 of effective immutability by slightly augmenting rule 2:

A null field cannot be modified, and cannot be but @Independent , so no changes are necessary to rules 1 and 3. One can argue that they do not belong to the accessible content, nor to the hidden content, since they cannot be accessed, and are content-less: rule 4 should not be affected. In combination with effective finality, this allows the eventually "blanking out" of modifiable fields in immutable types.

A variant on SetOnce is FirstThen, an eventually immutable container which starts off with one value, and transitions to another:

Note that if we were to annotate the methods as contracts, rather than relying on the analyser to detect them, we could have a slightly more efficient implementation.

Practice what you preach, and all that. The e2immu analyser relies heavily on support classes such as SetOnce, and on the builder pattern described in the previous section. Almost all public types are containers. Because we intend to use the analyser’s code as a showcase for this project, one important class (ExpressionContext) was intentionally kept as a non-container.

A good example of our aim for eventual immutability is TypeInfo, the primary container holding a type. Initially, a type is nothing but a reference, with a fully qualified name. Source code or byte code inspection augments it with information about its methods and fields. Whilst during inspection information is writable, after inspection this information becomes immutable. We use the builder pattern for TypeInspection, using TypeInspectionImpl.Builder first and TypeInspectionImpl later. The inspection information is stored using SetOnce:

Once inspection is over, the code analyser takes over. Results are temporarily stored in TypeAnalysisImpl.Builder, then copied into the immutable TypeAnalysisImpl class. Both classes implement the TypeAnalysis interface to shield off the build phase. Once the immutable type is ready, it is stored in TypeInfo:

In this way, if we keep playing by the book recursively downward, TypeInfo will become an eventually immutable type. Software engineers writing applications which use the e2immu analyser as a library, can feel secure that once the analysis phase is over, all the inspected and analysed information remains stable.

Nullability is a standard static code analyser topic, which we approach from a computational side: the analyser infers where possible, the user adds annotations to abstract methods. The complement of not-null (marked @NotNull ) is nullable (marked @Nullable ).

To be able to compute the not-null of parameters, we must specify some sort of flow or direction to break chicken-and-egg situations. We compute in the following order:

The analyser marks methods which returns their first parameter with @Identity, and methods which return this with @Fluent. The former are convenient to introduce preconditions, the latter occur frequently when chaining methods in builders. Here is an integrated example:

Up to now, we have focused on the distinction between the building phase of an object’s life-cycle, and its subsequent immutable phase. We have ignored the destruction of objects: critically important for some applications, but often completely ignored by Java programmers because of the silent background presence of the garbage collector. In this section we introduce an annotation, @Finalizer , with the goal of being able to mark that calling a certain method means that the object has reached the end of its life-cycle:

Why is this useful? The most obvious use-case for immutability is the meaning of the build() method in a builder: can you call it once, or is the builder somehow incremental? Secondly, consider "terminal" operations such as findAny or collect on a stream. They close the stream, after which you are not allowed to use it anymore.

How can the analyser enforce the sequence of method calling on an object?

The simplest way is by some severe restrictions:

Interestingly, these restrictions are such that they help you control the life-cycle of objects with a @Finalizer , by not letting them out of sight.

Note that the @Finalizer annotation is always contracted; it cannot be computed.

Let us start from the following example, using EventuallyFinal:

Using @Fluent methods to go from construction to finalizer is definitely allowed according to the rules:

Passing on these objects as arguments is permitted, but the recipient should not call the finalizer. Actually, given our strong preference for containers, the recipient should not even modify the object! Consider:

Rules 1 and 2 allow you to store a finalizer type inside a field, but only when finalization is attached to the destruction of the holding type. Examples follow immediately, in the context of the @BeforeMark annotation.

We use the simple and common definition:

These definitions imply

In Java, many classes cannot be extended easily. Implementations of extensions typically use a utility class with the convention that the first parameter of the static method is the object of the extended method call:

We use the following criteria to designate a class as an extension:

Static classes can be used to 'extend' closed types, as promoted by the Xtend project. Immutable classes can also play the role of extension facilitators, with the additional benefit of having some immutable data to be used as a context.

Note that extension classes will often not be @Container , since the first parameter will be @Modified in many cases.

A singleton class is a class which has a mechanism to limit the creation of instances to a maximum of one. The term 'singleton' then refers to this unique instance.

The e2immu analyser currently recognizes two systems for limiting the number of instances: the creation of an instance in a single static field with a static constructor, and a precondition on a constructor using a private static boolean field.

An example of the first strategy is:

An example of the second strategy is:

When annotating abstract types and methods, or types in the Annotated APIs, observe the following rules.

A method is @NotModified unless otherwise specified, its parameters are assumed to be @Modified , unless they are of immutable type.

Due to the large amount of circular type dependencies in the JDK, combined with the current limitations of the analyser, the implementation of the Annotated API analyser requires contracted annotations about independence, immutability, and container on the type. The following combinations are possible with respect ot independence and immutability:

Recall that abstract types always have hidden content, so the hc=true is always implicitly present on @Independent and @Immutable , @ImmutableContainer on the type. We generally do not write hc=false, as that is the default value in the annotation. The analyser will complain when hc=false is present on the @Immutable annotation of an abstract type.

To support the user, a warning will be raised when the independence value on the type is incompatible with that on its methods, parameters and fields.

In a @Container type, all @Fluent methods and all void methods are assumed to be @Modified . Change this by explicitly marking the method @NotModified or @StaticSideEffects .

Parameters of a non-modifying method are @Independent by default, regardless of an independence annotation on the type. This can be overwritten by @Independent(absent=true) or @Independent(hc=true) when the method exposes parts of the fields' object graph via its parameters. Parameters of a modifying method are assumed to be dependent when the type is not immutable, and independent when the type is immutable, the hidden content carrying over from immutable to independent.

Dependence is only explicitly written as @Independent(absent=true) on a type after analysis, when this type has (eventually) final fields and no modifying methods, as a marker to the user to indicate that it is the independence property that is missing to reach immutability. Marking a non-immutable type with @Independent specifies that no parameter or return value can be dependent. The hidden content parameter given by the user is ignored: you will still have to mark any method or parameter which communicates hidden content with @Independent(hc=true) .

When a type is immutable, @Independent becomes the default independence annotation for methods and parameters. You must still use @Independent(hc=true) to indicate communication of hidden content.

Methods marked @Fluent are always @Independent , because returning the type itself does not expose any additional information.

Following its definition, @UtilityClass on a type implies @Immutable .

In application mode, the analyser will regard every class that is never extended as effectively final. This property is only relevant when the type is immutable; the absence of hc=true is a marker.

Parameters of "official" functional interface type (i.e., the type is a functional interface type in the package java.util.function) have the @IgnoreModifications annotation, unless explicitly overwritten by @Modified .

The default nullable annotation for parameters and return values of non-primitive type is @Nullable .

A factory method is a static method returning an object of the type of the class. Independence of a factory method is always with respect to the method’s parameters, rather than to the type. Independence of a factory method’s parameters corresponds to the immutability of the parameter type. These two rules also applies to any static method in an immutable type. Note that utility classes are classes that are deeply immutable and cannot be instantiated, so it applies to their static methods.

In general, annotations are inherited on types, methods and parameters. The properties can deviate,

When a method has a single statement, returning a constant value, the @ImmutableContainer("value") is implicit. Similarly, when a field is explicitly final (it has the final modifier) and it has an initialiser, then both @Final and, if relevant, @ImmutableContainer("value"), is implicit.