Module jakarta.nosql.core
Package jakarta.nosql

Annotation Interface Embeddable

@Retention(RUNTIME) @Target(TYPE) public @interface Embeddable
Declares a type whose instances are stored as an intrinsic part of an owning entity, sharing the identity of the entity. A single embeddable type may be used as the type of multiple persistent fields or properties across several entities, even entities of unrelated types.

The annotated type must:

  • Be a non-abstract, non-final top-level class or static inner class.
  • Have at least one field annotated with Column.
  • Have a public or protected constructor with no parameters or a constructor parameter annotated with Column.
  • Annotations at the constructor will build the entity and read information from the database, while field annotations are required to write information to the database.
  • If both a non-args constructor and a constructor with annotated parameters exist, the constructor with annotations will be used to create the entity.
  • Constructor parameters without annotations will be ignored, utilizing a non-arg constructor instead.
  • An embeddable class should not have multiple constructors using Column annotations.
  • Enums or interfaces cannot be designated as embeddable types.
  • Record classes can also serve as embeddable types.

An embeddable class does not have its own database structure; instead, the state of an instance is stored in the structure mapped by the owning entity.

Persistent fields and properties of an embeddable class are mapped using the same mapping annotations used for entity classes and may hold instances of other embeddable types.

An embeddable class can have two types of strategies:

The behavior of the Embeddable.EmbeddableType.FLAT strategy is guaranteed to be supported by all Jakarta NoSQL implementations. However, the support and behavior of the Embeddable.EmbeddableType.GROUPING strategy may vary among NoSQL databases. If a NoSQL database does not support the Embeddable.EmbeddableType.GROUPING strategy, invoking operations that require it will result in an UnsupportedOperationException. Additionally, if a database requires specific configurations, such as Column.udt(), to support the Embeddable.EmbeddableType.GROUPING strategy, but those configurations are not met, a MappingException may be thrown.

For key-value NoSQL databases, the serialization mechanism may vary depending on the Jakarta NoSQL provider or the specific NoSQL database being used.

Example:


 @Embeddable
 public class PhoneNumber {
     @Column
     protected String areaCode;
     @Column
     protected String localNumber;
 }
The sample below demonstrates the use of records as embeddable types: 

 @Embeddable
 public record PhoneNumber(@Column String areaCode, @Column String localNumber) {
 }
Since:
1.0.0
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    Embeddable.EmbeddableType
    Defines the strategy for how fields of the embeddable class are stored.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    Embeddable.EmbeddableType
    value
    Specifies the embeddable type.

  • Element Details