@Embeddable (jpa)

The @jakarta.persistence.Embeddable is used by JPA to indicate that a class is persisted inline within a containing domain entity.

Mutability

If the embeddable class is mutable, then the semantics are a dependent entity in 1:1 relationship with its containing domain entity. In Apache Causeway, this should be modelled as a view model, and will be rendered in the UI as a reference (hyperlink) to the associated object.

If the embeddable class is immutable, then the semantics are closer to a composite value type. In most cases the framework won’t be able to render the object directly, but a representation of the object could be derived. An example is BlobJpaEmbeddable and ClobJpaEmbeddable, which persist the state for Blob and Clob respectively, and which provide convenient helpers to marshal between them. Other value types could be represented using AsciiDoc or similar.

Example

For example:

PostalAddress.java
import jakarta.persistence.*;

@Embeddable                                         (1)
@AllArgsConstructor
@Getter @Setter
public class PostalAddress {

    private String firstLine;
    private String secondLine;
    private String city;
    private String postalCode;
    private String country;

    public AsciiDoc toAsciiDoc() {                  (2)
       // ...
    }

}
1 Indicates that this is an embeddable object
2 Returns a renderable representation of this object

This could then be used as so:

Customer.java
import jakarta.persistence.*;

@Entity
public class Customer {

    @Embedded                                           (1)
    private PostalAddress homeAddress;

    public AsciiDoc getHomeAddress() {                  (2)
        return Optional.ofNullable(homeAddress)
                .map(CustomerAddress::toAsciiDoc)
                .orElse(null);
    }

    @Action(semantics = IDEMPOTENT)
    public Customer updateHomeAddress(                      (3)
                String firstLine,
                String secondLine,
                String city,
                String postalCode,
                String country) {
        this.homeAddress = new PostalAddress(/*...*/);
        return this;
     }
}
1 Indicates that the state of the referenced PostalAddress should be stored inline within the same table that stores the Customer's own data
2 Renders the address using AsciiDoc
3 Allows the state of the embedded object to be updated (or replaced).

See Also