Section 4, “ Object Identity ” describes how to use datastore identity in JPA. OpenJPA requires a single numeric primary key column to hold datastore identity values. The org.apache.openjpa.persistence.jdbc.DataStoreIdColumn annotation customizes the datastore identity column. This annotation has the following properties:

All properties correspond exactly to the same-named properties on the standard Column annotation, described in Section 3, “ Column ”.

import org.apache.openjpa.persistence.*;
import org.apache.openjpa.persistence.jdbc.*;

@Entity
@Table(name="LOGS")
@DataStoreIdColumn(name="ENTRY")
public class LogEntry {

    @Lob
    private String content;

    ...
}

OpenJPA supports version fields as defined by the JPA specification, but allows you to use a surrogate version column in place of a version field if you like. You map the surrogate version column with the org.apache.openjpa.persistence.jdbc.VersionColumn annotation. You can also use the org.apache.openjpa.persistence.jdbc.VersionColumns annotation to declare an array of VersionColumn values. Each VersionColumn has the following properties:

All properties correspond exactly to the same-named properties on the standard Column annotation, described in Section 3, “ Column ”.

By default, OpenJPA assumes that surrogate versioning uses a version number strategy. You can choose a different strategy with the VersionStrategy annotation described in Section 9.1.4, “ Version Strategy ”.

If multiple columns are used for surrogate versioning, then each column, by default, uses a version number. But column definition for each version column can be set independently to other numeric types. The version values are compared to detect optimistic concurrent modification. Such comparison must determine whether a version value v1 represents an earlier, later or same with respect to another version value v2. While result of such comparison is obvious for a single numeric column that monotonically increases on each update, the same is not true when version value is an array of numbers. By default, OpenJPA compares a version v1 as later than another version v2, if any array element of v1 is later than the corresponding element of v2. v1 is equal to v2 if every array element is equal and v1 is earlier to v1 if some elements of v1 are earlier and rest are equal to corresponding element of v2.

Multiple surrogate version columns can be spread across primary and secondary tables. For example, following example shows 3 version columns v01, v11, v12, v21 defined across the primary and secondary tables of a persistent entity

@Entity
@Table(name="PRIMARY")
@SecondaryTables({ 
    @SecondaryTable(name = "SECONDARY_1"),
    @SecondaryTable(name = "SECONDARY_2") 
})
@VersionStrategy("version-numbers")
@VersionColumns({ 
    @VersionColumn(name = "v01") // default is the PRIMARY table
    @VersionColumn(name = "v11", table="SECONDARY_1", columnDefinition="FLOAT", scale=3, precision=10), 
    @VersionColumn(name = "v12", table="SECONDARY_1"), 
    @VersionColumn(name = "v21", table="SECONDARY_2"),
})

OpenJPA makes it easy to create multi-column custom mappings. The JPA specification includes a Column annotation, but is missing a way to declare multiple columns for a single field. OpenJPA remedies this with the org.apache.openjpa.persistence.jdbc.Columns annotation, which contains an array of Column values.

Remember to annotate custom field types with Persistent, as described in Section 3.3, “ Persistent Field Values ”.

Section 8.4, “ Direct Relations ” in the JPA Overview introduced you to the JoinColumn annotation. A JoinColumn's referencedColumnName property declares which column in the table of the related type this join column links to. Suppose, however, that the related type is unmapped, or that it is part of a table-per-class inheritance hierarchy. Each subclass that might be assigned to the field could reside in a different table, and could use entirely different names for its primary key columns. It becomes impossible to supply a single referencedColumnName that works for all subclasses.

OpenJPA rectifies this by allowing you to declare which attribute in the related type each join column links to, rather than which column. If the attribute is mapped differently in various subclass tables, OpenJPA automatically forms the proper join for the subclass record at hand. The org.apache.openjpa.persistence.jdbc.XJoinColumn annotation has all the same properties as the standard JoinColumn annotation, but adds an additional referencedAttributeName property for this purpose. Simply use a XJoinColumn in place of a JoinColumn whenever you need to access this added functionality.

For compound keys, use the org.apache.openjpa.persistence.jdbc.XJoinColumns annotation. The value of this annotation is an array of individual XJoinColumns.

JPA uses the AttributeOverride annotation to override the default mappings of an embeddable class. The JPA Overview details this process in Section 8.3, “ Embedded Mapping ”. AttributeOverrides suffice for simple mappings, but do not allow you to override complex mappings. Also, JPA has no way to differentiate between a null embedded object and one with default values for all of its fields.

OpenJPA overcomes these shortcomings with the org.apache.openjpa.persistence.jdbc.EmbeddedMapping annotation. This annotation has the following properties:

The EmbeddedMapping's overrides array serves the same purpose as standard JPA's AttributeOverride s and AssociationOverride s. In fact, you can also use the MappingOverride annotation on an entity class to override a complex mapping of its mapped superclass, just as you can with AttributeOverride and AssociationOverride s. The MappingOverrides annotation, whose value is an array of MappingOverride s, allows you to override multiple mapped superclass mappings.

Each org.apache.openjpa.persistence.jdbc.MappingOverride annotation has the following properties:

The following example defines an embeddable PathCoordinate class with a custom mapping of a java.awt.Point field to two columns. It then defines an entity which embeds a PointCoordinate and overrides the default mapping for the point field. The entity also declares that if the PathCoordinate 's siteName field column is null, it means that no PathCoordinate is stored in the embedded record; the owning field will load as null.

import org.apache.openjpa.persistence.jdbc.*;

@Embeddable
public class PathCoordinate {

    private String siteName;

    @Persistent
    @Strategy("com.xyz.openjpa.PointValueHandler")
    private Point point;

    ...
}

@Entity
public class Path {

    @Embedded
    @EmbeddedMapping(nullIndicatorFieldName="siteName", overrides={
        @MappingOverride(name="siteName", columns=@Column(name="START_SITE")),
        @MappingOverride(name="point", columns={
            @Column(name="START_X"),
            @Column(name="START_Y")
        })
    })
    private PathCoordinate start;

    ...
}

In Section 3.4, “Persistent Collection Fields”, we explored the PersistentCollection annotation for persistent collection fields that aren't a standard OneToMany or ManyToMany relation. To map these non-standard collections, combine OpenJPA's ContainerTable annotation with ElementJoinColumns. We explore the annotations below.

The previous section covered the use of ElementJoinColumn annotations in conjunction with a ContainerTable for mapping collections to dedicate tables. ElementJoinColumn s, however, have one additional use: to create a one-sided one-many mapping. Standard JPA supports OneToMany fields without a mappedBy inverse, but only by mapping these fields to a JoinTable (see Section 8.5, “ Join Table ” in the JPA Overview for details). Often, you'd like to create a one-many association based on an inverse foreign key (logical or actual) in the table of the related type.

Consider the model above. Subscription has a collection of LineItem s, but LineItem has no inverse relation to Subscription. To retrieve all of the LineItem records for a Subscription , we join the SUB_ID inverse foreign key column in the LINE_ITEM table to the primary key column of the SUB table. The example below shows how to represent this model in mapping annotations. Note that OpenJPA automatically assumes an inverse foreign key mapping when element join columns are given, but no container or join table is given.

package org.mag.subscribe;

import org.apache.openjpa.persistence.jdbc.*;

@Entity
@Table(name="LINE_ITEM", schema="CNTRCT")
public class LineItem {
    ...
}

@Entity
@Table(name="SUB", schema="CNTRCT")
public class Subscription {

    @Id private long id;

    @OneToMany
    @ElementJoinColumn(name="SUB_ID", referencedColumnName="ID")
    private Collection<LineItem> items;

    ...
}

We detailed the ContainerTable annotation in Section 7.6.1, “ Container Table ”. Custom map mappings may also use this annotation to represent a map table.

7.8.4. Examples

Map mapping in OpenJPA uses the same principles you saw in collection mapping. The example below maps the Article.authors map according to the diagram above.

Example 7.17. String Key, Entity Value Map Mapping

package org.mag.pub;

import org.apache.openjpa.persistence.*;
import org.apache.openjpa.persistence.jdbc.*;

@Entity
@Table(name="AUTH")
@DataStoreIdColumn(name="AID", columnDefinition="INTEGER64")
public class Author {
    ...
}

package org.mag;

@Entity
@Table(name="ART")
public class Article {
    @Id private long id;

    @PersistentMap
    @ContainerTable(name="ART_AUTHS", joinColumns=@XJoinColumn(name="ART_ID"))
    @KeyColumn(name="LNAME")
    @ElementJoinColumn(name="AUTH_ID")
    private Map<String,Author> authors;

    ...
}

OpenJPA uses index information during schema generation to index the proper columns. OpenJPA uses foreign key and unique constraint information during schema creation to generate the proper database constraints, and also at runtime to order SQL statements to avoid constraint violations while maximizing SQL batch size.

OpenJPA assumes certain columns have indexes or constraints based on your mapping defaults, as detailed in Section 4, “ Mapping Defaults ”. You can override the configured defaults on individual joins, field values, collection elements, map keys, or map values using the annotations presented in the following sections.

Some databases support XML column types and XPath queries and indexes over these columns. OpenJPA supports mapping of an entity property mapped to an XML column on the following databases and their minimum versions.

Annotate the entity property using the XMLValueHandler strategy:

@Persistent
@Strategy("org.apache.openjpa.jdbc.meta.strats.XMLValueHandler")

The default fetch type is EAGER but can be changed to LAZY by using:

@Persistence(fetch=FetchType.LAZY)

The entity property class is required to have JAXB binding annotations. You can generate property class from an XML schema by using the xjc generator from the JAXB reference implementation. The xjc will generate the class along with the required annotations. Ensure that @XmlRootElement appears in the root class. In some cases this annotation needs to be added manually.

The entity property class is required to have getter and setter methods for all its fields. By default, the xjc will not generate setter methods for collections but you can force it to do so by using the collection setter injector plugin.

The JAXB jar files must be on the application classpath (jaxb-api.jar, jaxb-impl.jar, jsr173_1.0_api.jar or equivalent).

JPQL path expressions can navigate into the mapped class and its subfields to any level.

The path expression is rewritten into an equivalent XPath expression using SQL XML functions.

The path expression must be single-valued. Path expressions over XML mapped classes can only be used in the WHERE clause as an operand to a simple predicate (= <> < > >= <=).

Path expressions over XML mapped fields can not be:

XML schema must not contain namespace declarations. The JPQL path expressions can not refer to Java fields generated from XML ANY type or XML mixed element types.

The data type generated by JAXB must be a valid type to use the property in a JPQL predicate.

Shown below is a sample XML schema myaddress.xsd, in which the JPA entity Order has shipAddress persistent field that maps to an XML column.

<?xml version="1.0" ?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" >

<xs:complexType name="Address">
 <xs:sequence>
  <xs:element name="Name" type="xs:string" />
  <xs:element name="Street" type="xs:string"
  	minOccurs="1" maxOccurs="3" />
  <xs:element name="City" type="xs:string" />
</xs:sequence>
</xs:complexType>

<xs:complexType name="CAN_Address">
 <xs:complexContent>
  <xs:extension base="Address">
   <xs:sequence>
    <xs:element name="Province" type="xs:string" />
    <xs:element name="PostalCode" type="xs:string" />
   </xs:sequence>
  </xs:extension>
</xs:complexContent>
</xs:complexType>

<xs:simpleType name="USPS_ZIP">
 <xs:restriction base="xs:integer">
  <xs:minInclusive value="01000" />
  <xs:maxInclusive value="99999" />
 </xs:restriction>
</xs:simpleType>

<xs:complexType name="USA_Address">
 <xs:complexContent>
  <xs:extension base="Address">
   <xs:sequence>
    <xs:element name="State" type="xs:string" />
    <xs:element name="ZIP" type="USPS_ZIP" />
   </xs:sequence>
  </xs:extension>
 </xs:complexContent>
</xs:complexType>

<xs:element name="MailAddress" type="Address" />
<xs:element name="AddrCAN" type="CAN_Address"
   substitutionGroup="MailAddress" />
<xs:element name="AddrUSA" type="USA_Address"
   substitutionGroup="MailAddress" />
</xs:schema>

Java classes Address, USAAddress and CANAddress are produced from myaddress schema by using the xjc generator.

    ...
@XmlRootElement
@XmlAccessorType(XmlAccessType.FIELD)
@XmlType(name = "Address", propOrder = {
    "name",
    "street",
    "city"
})
public class Address {
    @XmlElement(name = "Name", required = true)
    protected String name;
    @XmlElement(name = "Street", required = true)
    protected List<String> street;
    @XmlElement(name = "City", required = true)
    protected String city;

   /**
     * Getter and Setter methods.
     *
     */
     ...
}

    ...
@XmlRootElement
@XmlAccessorType(XmlAccessType.FIELD)
@XmlType(name = "USA_Address", propOrder = {
    "state",
    "zip"
})
public class USAAddress
    extends Address
{

    @XmlElement(name = "State")
    protected String state;
    @XmlElement(name = "ZIP")
    protected int zip;

   /**
     * Getter and Setter methods.
     *
     */
     ...
}

     ...
@XmlRootElement
@XmlAccessorType(XmlAccessType.FIELD)
@XmlType(name = "CAN_Address", propOrder = {
    "province",
    "postalCode"
})
public class CANAddress
    extends Address
{

    @XmlElement(name = "Province")
    protected String province;
    @XmlElement(name = "PostalCode")
    protected String postalCode;

   /**
     * Getter and Setter methods.
     *
     */
     ...
}

@Entity
public class Order {
    @Id  private into id;
    @Persistent
    @Strategy ("org.apache.openjpa.jdbc.meta.strats.XMLValueHandler")
    private Address shipAddress;
    ...
}

...
myaddress.ObjectFactory addressFactory = new myaddress.ObjectFactory();
Customer c1 = new Customer();
c1.setCid( new Customer.CustomerKey("USA", 1) );
c1.setName("Harry's Auto");
Order o1 = new Order( 850, false, c1);
USAAddress addr1 = addressFactory.createUSAAddress();
addr1.setCity("San Jose");
addr1.setState("CA");
addr1.setZIP(new Integer("95141"));
addr1.getStreet().add("12500 Monterey");
addr1.setName( c1.getName());
o1.setShipAddress(addr1);
em.persist(o1);
...

. select o from Order o where o.shipAddress.city = "San Jose" or
			      o.shipAddress.city = "San Francisco"  (OK)

. select o.shipaAddress from Order o  (OK)

. select o.shipAddress.city from Order o  (INVALID)

. select o from Order o where o.shipAddress.street = "San Jose"  (INVALID multi-valued)

In addition to handling LOBs in a standard JPA manner (LOB annotation and lob XML element), OpenJPA supports LOB streaming. This feature makes it possible to stream large amounts of data into and out of persistent field without ever holding all the data in memory at the same time.

LOB streaming is supported on the following databases.

See Appendix 2, Supported Databases for possible database-specific restrictions.

To persist a stream, apply the org.apache.openjpa.persistence.Persistent annotation to either java.io.InputStream or java.io.Reader field.

@Entity
public class Employee {
    ...
    @Persistent
    private InputStream photoStream;

    @Persistent
    private Reader photoDescription;
    ...
}