3.6.6.5. Externalization
OpenJPA offers the ability to write custom field mappings in order to have complete control over the mechanism with which fields are stored, queried, and loaded from the datastore. Often, however, a custom mapping is overkill. There is often a simple transformation from a Java field value to its database representation. Thus, OpenJPA provides the externalization service. Externalization allows you to specify methods that will externalize a field value to its database equivalent on store and then rebuild the value from its externalized form on load.
|
|
Fields of embeddable classes used for |
The OpenJPA
org.apache.openjpa.persistence.Externalizer annotation sets the name of a method that will be invoked to convert the field into its external form for database storage.
You can specify either the name of a non-static method, which will be invoked on the field value, or a static method, which will be invoked with the field value as a parameter.
Each method can also take an optional
StoreContext parameter for access to a persistence context.
The return value of the method is the field’s external form.
By default, OpenJPA assumes that all named methods belong to the field value’s class (or its superclasses). You can, however, specify static methods of other classes using the format <class-name>.<method-name>.
Given a field of type CustomType that externalizes to a string, the table below demonstrates several possible externalizer methods and their corresponding metadata extensions.
| Method | Extension |
|---|---|
|
|
|
|
|
|
|
|
The OpenJPA org.apache.openjpa.persistence.Factory annotation contains the name of a method that will be invoked to instantiate the field from the external form stored in the database. Specify a static method name. The method will be invoked with the externalized value and must return an instance of the field type. The method can also take an optional StoreContext parameter for access to a persistence context. If a factory is not specified, OpenJPA will use the constructor of the field type that takes a single argument of the external type, or will throw an exception if no constructor with that signature exists.
Given a field of type CustomType that externalizes to a string, the table below demonstrates several possible factory methods and their corresponding metadata extensions.
| Method | Extension |
|---|---|
|
none |
|
|
|
|
|
|
|
|
If your externalized field is not a standard persistent type, you must explicitly mark it persistent.
In OpenJPA, you can force a persistent field by annotating it with org.apache.openjpa.persistence.Persistent annotation.
|
|
If your custom field type is mutable and is not a standard collection, map, or date class, OpenJPA will not be able to detect changes to the field. You must mark the field dirty manually, or create a custom field proxy. See OpenJPAEntityManager.dirty for how to mark a field dirty manually in JPA. See Proxies for a discussion of proxies. |
You can externalize a field to virtually any value that is supported by OpenJPA’s field mappings (embedded relations are the exception; you must declare your field to be a persistence-capable type in order to embed it). This means that a field can externalize to something as simple as a primitive, something as complex as a collection or map of entities, or anything in between. If you do choose to externalize to a collection or map, OpenJPA recognizes a family of metadata extensions for specifying type information for the externalized form of your fields - see Type. If the external form of your field is an entity object or contains entities, OpenJPA will correctly include the objects in its persistence-by-reachability algorithms and its delete-dependent algorithms.
The example below demonstrates a few forms of externalization.
import org.apache.openjpa.persistence.*;
@Entity
public class Magazine {
// use Class.getName and Class.forName to go to/from strings
@Persistent
@Externalizer("getName")
@Factory("forName")
private Class cls;
// use URL.getExternalForm for externalization. no factory;
// we can rely on the URL string constructor
@Persistent
@Externalizer("toExternalForm")
private URL url;
// use our custom methods
@Persistent
@Externalizer("Magazine.authorsFromCustomType")
@Factory("Magazine.authorsToCustomType")
@ElementType(Author.class)
private CustomType customType;
public static Collection authorsFromCustomType(CustomType customType) {
... logic to pack custom type into a list of authors ...
}
public static CustomType authorsToCustomType(Collection authors) {
... logic to create custom type from a collection of authors ...
}
...
}
You can query externalized fields using parameters. Pass in a value of the field type when executing the query. OpenJPA will externalize the parameter using the externalizer method named in your metadata, and compare the externalized parameter with the value stored in the database. As a shortcut, OpenJPA also allows you to use parameters or literals of the field’s externalized type in queries, as demonstrated in the example below.
|
|
Currently, queries are limited to fields that externalize to a primitive, primitive wrapper, string, or date types, due to constraints on query syntax. |
Assume the Magazine class has the same fields as in the previous example.
// you can query using parameters
Query q = em.createQuery("select m from Magazine m where m.url = :u");
q.setParameter("u", new URL("http://www.solarmetric.com"));
List results = q.getResultList();
// or as a shortcut, you can use the externalized form directly
q = em.createQuery("select m from Magazine m where m.url = 'http://www.solarmetric.com'");
results = q.getResultList();