Mapping Guide

There are plenty of resources for learning JPA annotations. Take a look at:

Custom Value Types

The framework provides a number of custom value types. Some of these are wrappers around a single value (eg AsciiDoc or Password) while others map onto multiple values (eg Blob).

This section shows how to map each (and can be adapted for your own custom types or @Embedded values).

Mapping AsciiDoc

The AsciiDoc value type is used for documentation written using the AsciiDoc syntax:

  • In the domain entity, map AsciiDoc type using @Lob:

    MyEntity.java
    public class MyEntity ... {

    @Column(nullable = false) @Lob @Basic(fetch=FetchType.LAZY)
    @Property
    @Getter @Setter
    private AsciiDoc documentation;

}

  • in the webapp module, register the JPA specific converter by:

    • adding a dependency to this module:

      pom.xml
      <dependency>
    <groupId>org.apache.causeway.valuetypes</groupId>
    <artifactId>causeway-valuetypes-asciidoc-persistence-jpa</artifactId>
</dependency>

    • and adding reference the corresponding module in the AppManifest:

      AppManifest.java
      @Configuration
@Import({
        ...
        CausewayModuleValAsciidocPersistenceJpa.java
        ...
})
public class AppManifest {
}

Mapping Markdown

The Markdown value type is used for documentation written using markdown:

  • In the domain entity, map Markdown type using @Lob:

    MyEntity.java
    public class MyEntity ... {

    @Column(nullable = false) @Lob @Basic(fetch=FetchType.LAZY)
    @Property
    @Getter @Setter
    private Markdown documentation;

}

  • in the webapp module, register the JPA specific converter by:

    • adding a dependency to this module:

      pom.xml
      <dependency>
    <groupId>org.apache.causeway.valuetypes</groupId>
    <artifactId>causeway-valuetypes-markdown-persistence-jpa</artifactId>
</dependency>

    • and adding reference the corresponding module in the AppManifest:

      AppManifest.java
      @Configuration
@Import({
        ...
        CausewayModuleValMarkdownPersistenceJpa.java
        ...
})
public class AppManifest {
}

Mapping Blobs and Clobs

While the JPA standard does provide a standardised mechanism to marshall single valued types, but does not (currently) provide a standardised mechanism to marshall multiple valued types.

There are two alternatives:

We think the second approach is less boilerplate overall, and is easier to understand what is going on. The framework provides an @Embeddable classes for each of Blob and Clob, explained in the sections below.

Blobs

To map a Blob, use the BlobJpaEmbeddable class:

MyEntity.java
public class MyEntity ... {

    @Embedded
    private BlobJpaEmbeddable pdf;              (1)

    @Property()
    @PropertyLayout()
    public Blob getPdf() {                      (2)
        return BlobJpaEmbeddable.toBlob(pdf);
    }
    public void setPdf(final Blob pdf) {
        this.pdf = BlobJpaEmbeddable.fromBlob(pdf);
    }
}
1 the field as it is persisted by the ORM
2 the property as it is understood by Apache Causeway.
if you have multiple instancs of an @Embedded type, the @javax.persistence.AttributeOverrides and @javax.persistence.AttributeOverride provide a standardised way of fine-tuning the column definitions.

Clobs

To map a Clob, use the ClobJpaEmbeddable class:

MyEntity.java
public class MyEntity ... {

    @Embedded
    private ClobJpaEmbeddable xml;              (1)

    @Property()
    @PropertyLayout()
    public Clob getXml() {                      (2)
        return ClobJpaEmbeddable.toClob(xml);
    }
    public void setXml(final Clob xml) {
        this.xml = ClobJpaEmbeddable.fromClob(xml);
    }
}
1 the field as it is persisted by the ORM
2 the property as it is understood by Apache Causeway.
if you have multiple instances of an @Embedded type, the @javax.persistence.AttributeOverrides and @javax.persistence.AttributeOverride provide a standardised way of fine-tuning the column definitions.