OpenJPA (7)
10 Miscellaneous Features
10．1 Restoring State
JPA规范要求不应该使用rolled back objects，但是这些对象在OpenJPA中是有效的。可以通过配置openjpa.RestoreState 属性来控制是否将对象的状态回滚到事务前的状态。它有以下可选值：
- none: 不回滚对象状态，但是对象变成hollow，在下次访问的时候会重新加载。
- immutable: 回滚不可变的状态，可变的状态变成hollow，在下次访问的时候会重新加载。
- all: 回滚所有状态。
10．2 Typing and Ordering
当为对象的属性加载persistent state的时候，OpenJPA会检查这个属性在声明时或者无参构造函数中被赋值的类型。如果这个类型比声明的类型更精确，那么OpenJPA会用这个类型。如果你在初始化某个属性的时候使用了comparator，那么OpenJPA也会在每次加载persistent state的时候使用这个comparator。例如：
public class Company {
// OpenJPA 会在每次加载数据的时候使用SalaryComparator。
private Collection employeesBySal = new TreeSet(new SalaryComparator());
private Map departments;
public Company {
// OpenJPA会使用TreeMap来保存departments 相关的persistent state。
departments = new TreeMap();
}
}
10．3 Proxies
10．3．1 Smart Proxies
在运行时，OpenJPA可以通过代理跟踪entity 实例的属性是否被修改过，以便更有效地更新数据库。当设计persistent class的时候，应该尽可能将collection field映射成java.util.Set、java.util.TreeSet或java.util.HashSet。Smart proxy对这些类型可以进行更好的优化。
10．3．2 Large Result Set Proxies
当遍历persistent collection 或者map属性的时候，ORM的缺省行为是把所有persistent state载入到内存中。然而，如果载入的数据量过大，那么可能会降低性能。OpenJPA为这些large result set属性使用特殊的代理。它并不在内存中缓存任何数据，相反它会访问数据库来获得相关的结果。例如large result set collection的contains方法会导致在数据库中执行类似于SELECT COUNT(*) WHERE的查询。类似地，在每次试图获得iterator的时候，OpenJPA会使用当前的large result set配置来执行特定的query。在调用iterator.next方法的时候，OpenJPA会按需载入结果对象。此时需要通过OpenJPAPersistence.close方法来释放资源，例如：
import org.apache.openjpa.persistence.*;
@Entity
public class Company {
@ManyToMany
@LRS
private Collection<Employee> employees;
...
}
Collection employees = company.getEmployees(); // employees is a lrs collection
Iterator itr = employees.iterator();
while (itr.hasNext()) {
process((Employee) itr.next());
}
OpenJPAPersistence.close(itr);
Large result set 属性只能被声明成java.util.Collection 或者java.util.Map；它不能包含externalizer；Large result set proxy不能从一个entity 实例转移到另外一个entity 实例中，例如以下代码会导致提交时的一个错误：
Collection employees = company.getEmployees() // employees is a lrs collection company.setEmployees(null); anotherCompany.setEmployees(employees);
10．3．3 Custom Proxies
OpenJPA通过org.apache.openjpa.util.ProxyManager接口管理代理。其缺省的实现是org.apache.openjpa.util.ProxyManagerImpl。它有以下配置属性：
- TrackChanges: 是否使用smart proxy，缺省是true。
- AssertAllowedType: 在向collection或map中加入元素的时候，如果跟metadata 中声明的类型不符，是否抛出异常，缺省是false。
以下是个简单的例子：
<property name="openjpa.ProxyManager" value="TrackChanges=false"/>
缺省的proxy manager可以代理 Collection, List, Map, Queue, Date, or Calendar 等类上的标准方法，也可以代理定制类型，但是这些定制类型必须复合以下条件：
- Custom container types必须有一个公共的无参构造函数，或者一个公共的以Comparator为参数类型的构造函数。
- Custom date types必须有一个公共的无参构造函数，或者一个公共的以long为参数 类型（代表当前的时间）的构造函数。
- Other custom types必须有一个公共的无参构造函数，或者公共的拷贝构造函数。如果没有公共的拷贝构造函数，那么在进行拷贝的时候，首先会创建一个对象B，然后通过以A上getter方法的返回值为参数，调用B的setter方法。 因此你要确保通过这种方式，B是A的完整拷贝。
如果某个custom classes无法满足以上条件，那么OpenJPA允许你定义你自己的proxy class和proxy manager。
10．4 Externalization
OpenJPA 支持通过custom field mappings 来完全控制entity class的field在datastore中怎样被保存、查询和加载。然而一个更轻量级的方法是使用externalization 。Externalization 支持通过指定某些方法来控制保存和加载的方式。需要注意的是，不能在@EmbeddedId字段上使用externalization。
OpenJPA使用org.apache.openjpa.persistence.Externalizer annotation指定将某个属性转换为external value的方法名。如果指定一个non-static方法，那么OpenJPA会假定目标对象是被Externalizer标记的属性对象；如果指定一个static方法， 那么被OpenJPA会把被Externalizer标记的属性对象作为一个方法的参数。每个方法也可以接受一个StoreContext 型的参数。方法的返回值指定了缺省的external 类型。假设希望将某个CustomType类型的属性转换成String类型，那么可以采用以下的方法：
| Method | Extension |
| public String CustomType.toString() | @Externalizer("toString") |
| public String CustomType.toString(StoreContext ctx) | @Externalizer("toString") |
| public static String AnyClass.toString(CustomType ct) | @Externalizer("AnyClass.toString") |
| public static String AnyClass.toString(CustomType ct, StoreContext ctx) | @Externalizer("AnyClass.toString") |
OpenJPA使用org.apache.openjpa.persistence.Factory annotation指定根据external value初始化某个属性的方法名。 如果指定static方法，那么这个方法必须返回这个属性类型的一个实例。这个方法可以接受StoreContext 类型的一个参数。如果没有指定factory annotation，那么这个属性的class必须包含以external form为参数的构造函数，否则会抛出一个异常。假设希望将String类型转换成某个CustomType类型，那么可以采用以下的方法：
| Method | Extension |
| public CustomType(String str) | none |
| public static CustomType CustomType.fromString(String str) | @Factory("fromString") |
| public static CustomType CustomType.fromString(String str, StoreContext ctx) | @Factory("fromString") |
| public static CustomType AnyClass.fromString(String str) | @Factory("AnyClass.fromString") |
| public static CustomType AnyClass.fromString(String str, StoreContext ctx) | @Factory("AnyClass.fromString") |
OpenJPA使用org.apache.openjpa.persistence.ExternalValues annotation指定external value的转换。 其value pairs用于指定Java和datastore的类型。如果datastore的类型不同于Java类型，那么通过org.apache.openjpa.persistence.Type annotation 指定datastore类型。如果externalized属性不是标准的persistent type，那么必须用org.apache.openjpa.persistence.Persistent annotation显式地进行标记。如果externalized 属性是可变的，而且不是collection、map和date类型，那么OpenJPA无法进行脏检查。可以手动进行标记为dirty，或者使用custom field proxy。以下是个简单的例子：
@Entity
public class Externalization {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Integer id;
@Persistent
@Externalizer("getName")
@Factory("forName")
private Class clazz;
@Persistent
@Factory("Externalization.stringToURL")
@Externalizer("Externalization.urlToString")
private URL url;
@Basic
@ExternalValues({"SMALL=5", "MEDIUM=8", "LARGE=10"})
@Type(int.class)
private String size;
public static URL stringToURL(String s) {
try {
return new URL(s);
} catch (MalformedURLException e) {
throw new RuntimeException(e);
}
}
public static String urlToString(URL url) {
return url.toExternalForm();
}
public String toString() {
StringBuffer sb = new StringBuffer();
sb.append("id: ").append(id);
sb.append(", clazz: ").append(clazz);
sb.append(", url: ").append(url);
sb.append(", size: ").append(size);
return sb.toString();
}
}
EntityManager em = entityManagerFactory.createEntityManager();
em.getTransaction().begin();
Externalization e1 = new Externalization();
e1.setClazz(Externalization.class);
e1.setUrl(new URL("http://www.abc.com"));
e1.setSize("MEDIUM");
em.persist(e1);
em.getTransaction().commit();
em.close();
em = entityManagerFactory.createEntityManager();
Query q = em.createQuery("select m from Externalization m where m.url = 'http://www.abc.com'");
List<Externalization> r1 = (List<Externalization>)q.getResultList();
for(Iterator iter = r1.iterator(); iter.hasNext(); ) {
System.out.println(iter.next().toString());
}
em.close();
以上代码执行完毕后数据库中externalization表的数据如下：
mysql> select * from externalization; +----+-----------------+------+--------------------+ | id | clazz | size | url | +----+-----------------+------+--------------------+ | 1 | Externalization | 8 | http://www.abc.com | +----+-----------------+------+--------------------+
10．5 Fetch Groups
Fetch groups是一组同时被加载的属性。之前介绍的Fetch Type指定了如何通过annotations指定某个属性是eagerly还是 lazily 加载。Fetch groups 则是提供了动态指定加载方式的能力。.
10．5．1 Custom Fetch Groups
OpenJPA缺省fetch group中的属性都会被eagerly加载。此外可以通过org.apache.openjpa.persistence.FetchGroup annotation定义named fetch groups以便在运行时激活它。在加载的时候，OpenJPA会eagerly加载所有被激活的fetch groups中的属性。FetchGroup annotation有以下属性：
- String name: fetch group 的全局名。以下名字被OpenJPA保留：default 、values、 all、none以及任何以jdo、jpa或openjpa开头的名字。
- FetchAttribute[] attributes: fetch group中persistent fileds或者properties数组。
- String[] fetchGroups: 包含在次fetch group中的其它fetch groups名。
org.apache.openjpa.persistence.FetchAttribute annotation的属性如下：
- String name: persistent field 或者 property 名。
- recursionDepth: eager-fetch 的递归深度，缺省是1（-1无限制）。
Entity class的某个属性可以包含在任何的fetch group中，它也可以声明其load fetch group。缺省情况下，OpenJPA在第一次访问lazy-loaded属性的时候访问数据库。然而如果你直到当你访问某个lazy-loaded属性A的时候，你很可能也同时访问lazy-loaded 属性B和C，因此在一次数据库访问中同时加载A、B和C是更有效的。
通过org.apache.openjpa.persistence.LoadFetchGroup annotation为某个属性指定load fetch group。以下是个简单的例子：
import org.apache.openjpa.persistence.*;
@Entity
@FetchGroups({
@FetchGroup(name="detail", attributes={
@FetchAttribute(name="publisher"),
@FetchAttribute(name="articles")
})
})
public class Magazine {
@ManyToOne(fetch=FetchType.LAZY)
@LoadFetchGroup("detail")
private Publisher publisher;
}
10．5．2 Custom Fetch Group Configuration
OpenJPAEntityManager接口和OpenJPAQuery接口可以用于访问org.apache.openjpa.persistence.FetchPlan。FetchPlan通过以下方法维护当前活跃的fetch groups和maximum fetch depth：
public FetchPlan addFetchGroup(String group); public FetchPlan addFetchGroups(String... groups); public FetchPlan addFetchGroups(Collection groups); public FetchPlan removeFetchGrop(String group); public FetchPlan removeFetchGroups(String... groups); public FetchPlan removeFetchGroups(Collection groups); public FetchPlan resetFetchGroups(); public Collection<String> getFetchGroups(); public void clearFetchGroups(); public FetchPlan setMaxFetchDepth(int depth); public int getMaxFetchDepth();
Maximum fetch depth指定了加载时遍历对象的深度，缺省值是-1(无限制)。如果MaxFetchDepth是1，那么OpenJPA将会加载目标实例和它的直接relations； 如果MaxFetchDepth是2，那么OpenJPA会加载目标实例、直接relations和直接relations上的relations；如果MaxFetchDepth是-1，那么OpenJPA会加载目标实例以及所有的relatons直到到达对象图的边缘。当然以上的加载过程依赖于被加载属性是否是eagerly load，以及当前活跃的fetch group。以下是个简单的例子：
OpenJPAQuery kq = OpenJPAPersistence.cast(em.createQuery(...));
kq.getFetchPlan().setMaxFetchDepth(3).addFetchGroup("detail");
List results = kq.getResultList();
10．5．3 Per-field Fetch Configuration
除了基于per-fetch-group 的配置外，OpenJPA也支持基于per-field的配置。通过以下方法将特定的field包含到当前的fetch plan中。
public FetchPlan addField(String field); public FetchPlan addFields(String... fields); public FetchPlan addFields(Class cls, String... fields); public FetchPlan addFields(Collection fields); public FetchPlan addFields(Class cls, Collection fields); public FetchPlan removeField(String field); public FetchPlan removeFields(String... fields); public FetchPlan removeFields(Class cls, String... fields); public FetchPlan removeFields(Collection fields); public FetchPlan removeFields(Class cls, Collection fields); public Collection<String> getFields(); public void clearFields();
需要注意的是，以上方法中的field必须定义在指定的类中，而不是在其父类中。如果field publisher被定义在Publication中，而不是其子类Magazine中，那么必须用 addField (Publication.class, "publisher")，而不是addField (Magazine.class, "publisher")。出于性能上的考虑，OpenJPA并不对class name / field name 对进行验证。如果指定了不存在的class name / field name 对，那么会被OpenJPA忽略。以下是个简单的例子：
OpenJPAEntityManager kem = OpenJPAPersistence.cast(em); kem.getFetchPlan().addField(Magazine.class, "publisher"); Magazine mag = em.find(Magazine.class, magId);