Oracle's TopLink Essentials is the bundled persistence-layer provider in GlassFish v2. Unfortunately TopLink Essentials is totally inadequate for anything except small toy examples. I found after a few months of development that read and write operations cost O(N²) in the number of objects involved. This of course makes TopLink Essentials useless for real work.

I noticed that GlassFish v3 has switched to EclipseLink, which is based on TopLink but presumably more mature. Upgrading to GlassFish v3 is not an option at the moment, since that would entail either upgrading to ICEfaces 2.0 or bundling JSF 1.2 with the application. ICEfaces 2.0 is on my roadmap, but migration is not scheduled until later. And bundling JSF 1.2 with the application would be too messy. However, thanks to this helpful link, I found that adding EclipseLink to GlassFish v2.1.1 is very easy. Here is what I did:

• Download EclipseLink from http://www.eclipse.org/eclipselink/downloads/
• Copy jlib/eclipselink.jar to $GLASSFISH_HOME/domains/domain1/lib/
• Add the following to the <persistence-unit> element in META-INF/persistence.xml in all application jars that contain JPA-persisted classes, and rename all properties from "toplink" to "eclipselink":
  
      <provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>
  
  
• Finally, I had to change my JPA-persisted classes from using public fields to using annotated getter and setter methods instead. Otherwise nothing was committed to the database. This made my code a lot more verbose, but perhaps getters and setters allows EclipseLink to use some clever instrumentation techniques? Anyway, this was an unexpected snag, but manageable.

That's all! No bundling of extra jars with the application is needed, the eclipselink.jar file can be distributed separately.