What does @Basic annotation really do?

Question

It seems that @Basic annotation on a java variable only declares that the variable must be saved as a column with NOT NULL constraint. Is that correct ?

This post says that:

@Basic(optional = false) @Column(nullable = false) The @Basic annotation marks the property as not optional on the Java object level. The second setting, nullable = false on the column mapping, is only responsible for the generation of a NOT NULL database constraint. The Hibernate JPA implementation treats both options the same way in any case, so you may as well use only one of the annotations for this purpose.

I am confused. What does this mean - The @Basic annotation marks the property as not optional on the Java object level. How is a property or variable "optional" at Java level ?

Answer 1

The Hibernate JPA implementation will treat both the same only in terms of schema generation, that is the column will be created with a not null constraint.

Using optional = false however also allows for Hibernate (and I suppose other implementations) to perform a check and throw an exception prior to flushing to the database if the non-optional field is null. Without this you would only get an Exception thrown after the attempt to insert.

From Pro JPA:

When the optional element is specified as false, it indicates to the provider that the field or property mapping may not be null. The API does not actually define what the behavior is in the case when the value is null, but the provider may choose to throw an exception or simply do something else. For basic mappings, it is only a hint and can be completely ignored. The optional element may also be used by the provider when doing schema generation, because, if optional is set to true, then the column in the database must also be nullable.

Having optional=false can also affect Entity loading in Hibernate. For example, single-ended associations are always eagerly loaded in Hibernate unless the association is marked as optional=false.

See: https://stackoverflow.com/a/17987718/1356423 for further explanation.

Answer 2

The authoritative answer to the meaning of an api element is of course the api documentation, i.e. the javadoc. For the @Basic annotation, this writes:

The simplest type of mapping to a database column. The Basic annotation can be applied to a persistent property or instance variable of any of the following types: Java primitive types, wrappers of the primitive types, String, java.math.BigInteger, java.math.BigDecimal, java.util.Date, java.util.Calendar, java.sql.Date, java.sql.Time, java.sql.Timestamp, byte[], Byte[], char[], Character[], enums, and any other type that implements java.io.Serializable.

The use of the Basic annotation is optional for persistent fields and properties of these types. If the Basic annotation is not specified for such a field or property, the default values of the Basic annotation will apply.

What are the values of the Basic annotation? The Javadoc explains them, too:

public abstract FetchType fetch

(Optional) Defines whether the value of the field or property should be lazily loaded or must be eagerly fetched. The EAGER strategy is a requirement on the persistence provider runtime that the value must be eagerly fetched. The LAZY strategy is a hint to the persistence provider runtime. If not specified, defaults to EAGER.

and

public abstract boolean optional

(Optional) Defines whether the value of the field or property may be null. This is a hint and is disregarded for primitive types; it may be used in schema generation. If not specified, defaults to true.

Therefore, if you set optional to false, the persistence provider may throw an exception when you try to persist or update an object where the property is null. This can be useful if your business rules say that null is not a legal value.

Note

At least when using hibernate, nullability is better expressed with the corresponding Bean Validation annotation (@NotNull), as this annotation is both understood by hibernate and can be used by other layers on an application (for instance when validating user input).