Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: for the plan.

Jump to: navigation, search


Design Specification: Remote JPA

ER 390352


Document History

Date Author Version Description & Notes
2012-10-03 James 0.1 Draft

Project overview

Remote JPA would allow access to the JPA API from a remote Java client. This would allow fat Java clients to access the richness of the JPA API, and not require a data transfer layer. This can avoid the need for remote SessionBeans, merging, detaching, and data transfer objects. It provides querying, transactions, change tracking, and lazy relationship support on the Java client.

It could also be used in distributed architectures to perform database intensive work closer to the database, for more optimal interaction.


  • Java fat-client - client user interface is Java, (versus html), this could be a Java desktop or WebStart application, Java applet, or possibly an Android client.
  • RMI - Java communication framework, makes use of Java serialization to send objects.
  • CORBA - language independent communication framework
  • RemoteSession - existing EclipseLink feature that provides the EclipseLink native Session API to a remote Java client.


  • query execution
  • transaction/unit of work
  • change tracking, flushing
  • lazy relationships
  • load groups, eager relationships

Design Constraints

  • security - need to determine how security will be provided
  • communication protocol - what protocols should be supported
  • serialization - should provide alternative serialization options to Java serialization




Currently EclipseLink supports a RemoteSession feature which allows remote access through the Session API.

The following is required to enable this functionality through JPA:

  • JPA classes must accept any Session type (AbstractSession instead of DatabaseSession).
  • JPA uses attribute change tracking, which does not work with current RemoteSession.
  • JPA supports flush (RepeatableWriteUnitOfWork), which does not work with current RemoteSession.
  • JPA requires more meta-data than RemoteSession currently exposes through descriptor serialization.


The JPA API will be the same on client versus server. Remote connection properties will be specified through persistence unit properties.


JPA will deploy as normal on the client. A persistence.xml will be used in then same way, and weaving and meta-data processing will occur on the client the same way as on the server. Specific remote persistence unit properties will define the persistence unit to be remote, and configure how to connect to the server. The server will also contain specific remote persistence unit properties for making itself available to communicate with clients.

Currently RemoteSession serializes descriptors from the server. This function will not be used for JPA, the meta-data will be processed by the client. This is normally more efficient than serializing descriptors. For a large project, serializing descriptors may be more efficient, so this could be investigated in future phases.


RemoteSession supports sending DatabaseQuery objects, as well as calling queries remotely by name.

Currently JPA parses JPQL to create a DatabaseQuery, so this will need to occur on the client, or a new type of generic JPQL DatabaseQuery will need to be used. Named queries in JPA are not currently invoked as named queries in the Session, but just looked-up and executed normally. A different mechanism would be required to execute a query remotely by name.

The queries could be prepared on the client or on the server. Preparing on the client could mean more data is serialized as part of the query definition, but it could also mean less data as SQL is less data than serialized Criteria or Expression objects. Preparing the queries on the client is the simpler solution, so will be used in the first phase. Preparing queries on the server will be investigated for future phases.

Unit of work

Currently to process writes, the RemoteSession serializes a complete RemoteUnitOfWork to the server to be processed on the server. This has the advantage of a single server call, but the disadvantage of potentially be a very large call. The RemoteUnitOfWork does not currently support change tracking, or flushing.

The RemoteUnitOfWork will be changed to extend the RepeatableWriteUnitOfWork to allow flushing. The changes will be computed once, on the client, this is required to allow change tracking to work, and avoids any server calls if there are no changes (common on query flushes). The change sets, in addition to the objects will be serialized to the server. The server commit and merge will use the change set (and objects). This entire unit of work will be sent back, this is required to merges any changes back into the client unit of work (ids, version numbers, events). The server unit of work will be merged into the client unit of work, and the client unit of work will be merged into the parent remote session (unless isolated).

Serializing the objects (all objects, even ones that did not change), can be very expensive. Future phases could investigate only sending the change set, instead of the entire unit of work. This would be difficult, as the commit process requires the objects, and will have to be written to work will only change sets. There are also features that require the objects, such as events, field locking, cascaded locking, even deletion.


The work will be broken into the following phases:

Phase 1:

  • JPA will be made compatible with RemoteSession (or any AbstractSession).
  • JPA artifacts and meta-data will be ensured to be serializable.

Phase 2:

  • Basic querying (queries will be prepared on client, database call sent to server)
  • Basic units of work (no change tracking, no flushing).

Phase 3:

  • Complex units of work (change tracking, flushing, etc.)

Phase 4:

  • Optimized querying (named queries, jpql prepared on server)
  • Optimized units of work (only send change sets, no objects)


Will use JPA fieldaccess EntityManager test suite (JPA SRG).


  • @RemoteCache (type, size, isolation)

Persistence unit properties

  • "eclipselink.remote.protocol"="rmi","corba", "<class-name>"
  • "eclipselink.remote.client.url"
  • ""
  • "eclipselink.remote.naming-service"="rmi", "jndi", "corba"
  • "eclipselink.remote.jndi.user"
  • "eclipselink.remote.jndi.password"

Native API

No new native API, but the existing native RemoteSession API must continue to function the same.

Config files

New persistence.xml properties, and <remote-cache> element added to the EclipseLink orm.xml.


Should be documented under a new Remote JPA section.

Open Issues

Issue # Owner Description / Notes
1 Can unit of work commit only send changes, instead of objects? Currently sends both, commit currently requires objects.
2 What communication protocols should be supported? Currently RMI, maybe CORBA.


Issue Description / Notes Decision

Future Considerations

  • Remote query load groups, fetch groups
  • Serializing minimal changes for remote unit of work
  • Investigate other protocols and serializers (Kryo, POF, XML, JSON, REST)
  • Consolidate and improve persistence security options

Back to the top