Persistence

This page will document how the JPA implementation of  EclipseLink can be used to transparently persist teams and roles.

Use these examples for a jump-start:

This is work in progress.

The main goal of the OT/JPA integration is transparence, i.e., persisting teams and roles follows -as much as possible- just the standard rules of JPA and EclipseLink. Thus, the main documentation for using OT/JPA is the official [ EclipseLink User Guide (JPA)].

A. Persistence Declarations

A.1. Entities

Teams (OTJLD §1.1) and roles (OTJLD §1.2) can be declared to be persistent entities (@Entity).

A.1.1 Role-team dependence

A Role can only be declared as @Entity if its enclosing team is an @Entity, too.

A.1.2 Persistence Units

File persistence.xml must declare all persistent team and role classes. Note that roles are specified using the "binary name", i.e., using a '$' to separate the role name from its enclosing team (some.pack.age.MyTeam$MyRole).

Although internally role classes are renamed by prepending __OT__, this prefix is not used in any user-specified declaration.

A.2. Inheritance

A.2.1 Implicit Inheritance

In order to support implicit inheritance (OTJLD §1.3.1), roles have to use the TABLE_PER_CLASS inheritance strategy: @Inheritance(strategy=InheritanceType.TABLE_PER_CLASS).

B. Integrating OT/JPA into Your Application

B.1 Dependencies

When using Maven to configure an application for OT/JPA, the following dependencies have to be specified (all in group org.objectteams):

  • objectteams-otre --- the Object Teams Runtime Environment
  • objectteams-bcel --- dependency of the above
  • objectteams-otre-agent --- installs the OTRE into the JVM on startup
  • objectteams-eclipselink --- main module of OT/JPA
  • objectteams-jpa-utils --- supporting utilities for OT/JPA
  • objectteams-jpa-lazyloading --- optional OT/JPA module

B.2 Linking

The following teams have to be instantiated and activated:

  • org.objectteams.eclipselink.adaptation.ObjectTeamsStructureAdapter
  • org.objectteams.eclipselink.adaptation.ObjectTeamsSemanticsAdapter

This can be done either programmatically (preferrably from main) or declaratively (see OTJLD §5.5).

If lazy loading shall be used the following code snippet helps do integrate that: 

    private void configureLazyLoading(EntityManager em, String persistentUnitName) {
        RoleCreationInterceptorHolder holder = new RoleCreationInterceptorHolder();
        final RoleQueryingRoleCreationInterceptor roleQueryingIterceptor = new RoleQueryingRoleCreationInterceptor();
        roleQueryingIterceptor.setEntityManager(em);
        roleQueryingIterceptor.setPersistenceUnitInfoSource(new PersistenceUnitInfoSource() {
            public PersistenceUnitInfo getPersistenceUnitInfo() {
                return EntityManagerFactoryProvider.getPersistenceUnitInfo(persistentUnitName);
            }
        });
        holder.setRoleCreationInterceptorFactory(new RoleCreationInterceptorFactory() {
            public RoleCreationInterceptor create() {
                 return roleQueryingIterceptor;
            }
        });
    }

For simple applications this should be all that's needed. Please remember that this documentation is work in progress, so further rules and hints will be added as needed.

C. Other Dos and Donts

Here we will list patterns that are not (yet) working and solutions (if known):

  • currently none

D. Detailed Documentation

The OT/JPA integration is bundled and documented as a set of Maven modules:

objectteams-plexus-compiler-eclipse Maven plugin for compiling OT/J code
otre-agent installs the OTRE into the JVM on startup
objectteams-eclipselink main module of OT/JPA
objectteams-eclipselink-spring integrates OT/JPA with the Spring container
objectteams-jpa-utils supporting utilities for OT/JPA
objectteams-jpa-lazyloading optional OT/JPA module
objectteams-bmp-demo a demo for using bean managed persistence for OT/J

OT/J runtime support (no Maven documentation):

objectteams-otre the Object Teams Runtime Environment
objectteams-bcel dependency of the above