This rule raises an issue on a private, non-final instance field whose value is assigned only during object
initialization and never reassigned afterwards. Such a field is already immutable in practice, and declaring it final states that
contract in the code instead of leaving it to be rediscovered.
A private instance field whose only assignments happen during object initialization, in its declaration, in an instance initializer block, or in a
constructor, never changes value once the constructor returns. As long as it is not declared final, nothing says so:
final, the same mistake does not
compile.final field is guaranteed to be visible, fully initialized, to any thread that reads
the object after construction, even if the reference was published without synchronization.Note that final is shallow: it freezes the reference, not the object behind it. A final List field can still have
elements added to it, and a final field holding a mutable object says nothing about that object’s state. Use final to
express "this field always points at the same value", not "this object cannot change".
No issue is raised in the following cases.
private. Proving that a package-private, protected or public field is never
reassigned would require analyzing every class that can see it, so the rule deliberately stops at private.final to those fields breaks the framework or
the build. This covers at least:
@Entity or @Embeddable, and fields
annotated with @Id, @Column, @ManyToOne or @OneToMany.@JsonProperty, @JsonCreator, @XmlElement
or @JsonbProperty.@Autowired, @Value, @Inject,
@Resource or @PersistenceContext.@Setter, @Data or @Builder.@Mock, @Spy, @InjectMocks or
@Captor.this(…). This covers fields assigned inside a conditional, a loop or a try block, and fields assigned in a
constructor that can return early. A final field must be definitely assigned by the end of each constructor, and the rule does not
follow the control flow to prove it in these cases.Add the final modifier to the field declaration. The change preserves behavior: if the code compiles afterwards, the field was
effectively final already, and final only documents it and locks it in.
If the compiler then rejects the field because it is "possibly already assigned" or "might not have been initialized", the field is not effectively final after all, and the issue should be reviewed instead of fixed. That happens when an assignment was missed on a constructor path or when the field is assigned more than once.
An issue on a field that a framework writes by reflection through an annotation this rule does not know about is a false positive and should be reported as such. An issue on a field that is effectively final today but is expected to become mutable as the class evolves is a genuine match, and leaving it as-is is a deliberate trade-off rather than a false positive.
Do not reach for final as a way to make a class immutable. A field pointing at a mutable object stays mutable through that object, so
also consider defensive copying or an unmodifiable view if immutability is the goal.
public class ShipmentTracker {
private String carrier; // Noncompliant: assigned only in the constructor
private int deliveredCount;
private final List<String> events = new ArrayList<>();
public ShipmentTracker(String carrier) {
this.carrier = carrier;
}
public void recordDelivery(String trackingNumber) {
deliveredCount++;
events.add(carrier + ":" + trackingNumber);
}
}
The deliveredCount field is incremented in recordDelivery, so it is genuinely mutable and no issue is raised on it.
public class ShipmentTracker {
private final String carrier;
private int deliveredCount;
private final List<String> events = new ArrayList<>();
public ShipmentTracker(String carrier) {
this.carrier = carrier;
}
public void recordDelivery(String trackingNumber) {
deliveredCount++;
events.add(carrier + ":" + trackingNumber);
}
}
final
Fieldsfinal Field
Semantics{rule:java:S1170} covers fields that are also constant and should become static final, whereas this rule covers per-instance values
that differ between objects. {rule:java:S1450} applies when a private field is used in a single method and should not be a field at all.
{rule:java:S6206} is the next step once every field of a data carrier is final, replacing the class with a record.