I am working on a glossary of EJB 3 terms that gives both the official definitions and explanations that Elvis can understand. (Elvis is the programmer persona who is neither Einstein nor the point-and-click/drag-and-drop "just give me a wizard" Mort.) What other definitions would you like? Do you spot errors or inaccuracies? Please let me know.

Readers of my blog know about Elvis, the Microsoft persona of the programmer who is neither Einstein nor the point-and-click/drag-and-drop "just give me a wizard" Mort. Elvis wants to use EJB 3 because the annotations make it easy, but he is a bit taken aback by the jargon.

I am working on a glossary that gives both the official definition of various terms (starting with Entity) and explanations that Elvis can understand. Elvis has worked through the basic tutorials, but he needs help deciphering the jargon in the GlassFish forum.

Whenever possible, the official definitions are from the JPA spec (AKA JSR 220: Enterprise JavaBeansTM,Version 3.0 Java Persistence API), a document that ranges from crystal clarity (if you happen to find the right sentence) to terminal obtuseness.

I'll keep updating this glossary over the next few weeks.

What other definitions would you like? Do you spot errors or inaccuracies? Please let me know.

Application Client

???Party line: Frequently mentioned in the spec without definition. Here is an explanation from the GlassFish FAQ: The Java EE platform defines a component that is specially designed to portably access Java EE services from a JVM running outside of the Application Server. It is called a Java EE Application Client and has been part of the platform since its first release (J2EE 1.2). Like all Java EE components it runs within a container provided by the vendor's implementation. The main advantages of the Application Client are that it's portable and that it allows the developer to use the same programming model for defining and accessing resources as is used within web components and EJBs. It follows the overall philosophy of the Java EE platform that as much of the "plumbing" or system-level work as possible should be performed by a container instead of being part of the Application code. That means a guarantee that the no-arg InitialContext constructor will work, that a private component naming context (java:comp/env) is available, and in Java EE 5 that platform annotations and injection are available.

???Elvis: That's the thing that I launch with the appclient tool. See also SE Environment.

Container-Managed Transaction-Scoped Persistence Context

???Party line: (JPA spec 5.6) A container-managed persistence context may be defined to have either a lifetime that is scoped to a single transaction or an extended lifetime that spans multiple transactions, depending on the PersistenceContextType that is specified when its EntityManager is created. This specification refers to such persistence contexts as transaction-scoped persistence contexts and extended persistence contexts respectively.

(JPA spec 5.6.1) The application may obtain a container-managed entity manager with transaction-scoped persistence context bound to the JTA transaction by injection or direct lookup in the JNDI namespace.

???Elvis: The thing that I get when I do

@Stateless
public class MySessionBean implements MySessionBeanInterface {
    @PersistenceContext
    private EntityManager em;
    . . .
}

Detached Entity Instance

???Party line: (JPA spec 3.2) A detached entity instance is an instance with a persistent identity that is not (or no longer) associated with a persistence context.

(JPA spec 3.2.4) A detached entity may result from transaction commit if a transaction-scoped container-managed entity manager is used (see section 3.3); from transaction rollback (see section 3.3.2); from clearing the persistence context; from closing an entity manager; and from serializing an entity or otherwise passing an entity by value—e.g., to a separate application tier, through a remote interface, etc.

???Elvis: Pretty straightforward. But why do they call it a transaction-scoped container-managed entity manager when Section 5.6.1 calls it a Container-Managed Transaction-Scoped Persistence Context? And why do they talk of clearing the persistence context when clear is an EntityManager method? No wonder I am confused about persistence contexts.

Entity / Entity Class / Entity Instance

???Party line: (JPA spec 2) An entity is a lightweight persistent domain object.

(JPA spec 2.1) The [sic] entity class must be annotated with the Entity annotation or denoted in the XML descriptor as an entity.

Throughout the spec, the term "entity" is used to refer either to an entity class or an instance of such a class, depending on the context.

???Elvis: An entity class is a class that I annotated with @Entity. (Let's not dwell on the XML alternative.) An entity instance is an object of such a class.

It's a good idea to put "class" or "instance" after any use of "entity".

Entity Manager

???Party line: (JPA spec 3.1) An EntityManager instance is associated with a persistence context. A persistence context is a set of entity instances in which for any persistent entity identity there is a unique entity instance. Within the persistence context, the entity instances and their lifecycle are managed. The EntityManager interface defines the methods that are used to interact with the persistence context. The EntityManager API is used to create and remove persistent entity instances, to find entities by their primary key, and to query over entities.

???Elvis: An EntityManager is the thing that lets me interact with the database by calling persist, find, createQuery.

Entity Manager Factory

???Party line: (JPA spec 5.4) The EntityManagerFactory interface is used by the application to obtain an application-managed entity manager. When the application has finished using the entity manager factory, and/or at application shutdown, the application should close the entity manager factory. Once an EntityManagerFactory has been closed, all its entity managers are considered to be in the closed state.

???Elvis: I need an EntityManagerFactory when I can't get my EntityManager injected, e.g. in a SE environment or a servlet.

Owning / Inverse Side

???Party line: (JPA spec 2.1.7) A bidirectional relationship has both an owning side and an inverse side. A unidirectional relationship has only an owning side. The owning side of a relationship determines the updates to the relationship in the database, as described in section 3.2.3.

???Elvis: The inverse side is the one with the mappedBy attribute. With a single-valued relationship, only the owning side has a foreign key column.

Persistence Context

???Party line: (JPA spec 5.1) A persistence context is a set of managed entity instances in which for any persistent entity identity there is a unique entity instance. Within the persistence context, the entity instances and their lifecycle are managed by the entity manager.

???Elvis: What's in it for me??? Isn't there exactly one persistence context per entity manager? Why do I need to know about two concepts?

Persistence Unit

???Party line: (JPA spec 6.1) A persistence unit is a logical grouping that includes:

???Elvis: That's the thing that I define with the META-INF/persistence.xml file. In an SE application, it contains database connection parameters. In an EE application, I need one even if it contains no information--that's the way it is.

SE Environment

???Party line: Frequently mentioned in the spec without definition. An application that runs outside any container.

This is sometimes called a "standalone client" (but not in the spec).

???Elvis: That's when I launch with -javaagent. I also need to add the JPA library (such as toplink-essentials.jar) and the database driver to the class path.