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

TODO: not really sufficient to use @Lob; should provide a custom converter.

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 BlobJpaEmbedded 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 Isis.
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 ClobJpaEmbedded 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 Isis.
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.