Skip to main content

An EJB 3 Glossary for Elvis

Posted by cayhorstmann on June 25, 2006 at 5:32 PM PDT

Readers of my blog know about href="http://www.nikhilk.net/Personas.aspx">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 href="http://www.horstmann.com/elvis/elvis-meets-glassfish.html">basic
tutorials, but he needs help deciphering the jargon in the href="http://forums.java.net/jive/forum.jspa?forumID=56&start=0">GlassFish
forum.

Whenever possible, the official definitions are from the href="http://jcp.org/aboutJava/communityprocess/final/jsr220/index.html">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

??? style="float:left; padding-right: 1em;" />Party line: Frequently
mentioned in the spec without definition. Here is an explanation from the
href="https://glassfish.dev.java.net/javaee5/ejb/EJB_FAQ.html#AppClientDef">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.

??? style="float:left; padding-right: 1em;" />Elvis: That's the thing
that I launch with the href="https://glassfish.dev.java.net/javaee5/persistence/persistence-example.html#Using_in_Java_EE">appclient
tool. See also SE Environment.

Container-Managed Transaction-Scoped Persistence Context

??? style="float:left; padding-right: 1em;" />Party line: ( href="http://jcp.org/aboutJava/communityprocess/final/jsr220/index.html">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.

( href="http://jcp.org/aboutJava/communityprocess/final/jsr220/index.html">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.

??? style="float:left; padding-right: 1em;" />Elvis: The thing that I
get when I do

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

Detached Entity Instance

??? style="float:left; padding-right: 1em;" />Party line: ( href="http://jcp.org/aboutJava/communityprocess/final/jsr220/index.html">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.

( href="http://jcp.org/aboutJava/communityprocess/final/jsr220/index.html">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.

??? style="float:left; padding-right: 1em;" />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 href="#persistence_context">persistence contexts.

Entity / Entity Class / Entity Instance

??? style="float:left; padding-right: 1em;" />Party line: ( href="http://jcp.org/aboutJava/communityprocess/final/jsr220/index.html">JPA
spec 2) An entity is a lightweight persistent domain object.

( href="http://jcp.org/aboutJava/communityprocess/final/jsr220/index.html">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.

??? style="float:left; padding-right: 1em;" />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

??? style="float:left; padding-right: 1em;" />Party line: ( href="http://jcp.org/aboutJava/communityprocess/final/jsr220/index.html">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.

??? style="float:left; padding-right: 1em;" />Elvis: An
EntityManager is the thing that lets me interact with the
database by calling persist, find,
createQuery.

Entity Manager Factory

??? style="float:left; padding-right: 1em;" />Party line: ( href="http://jcp.org/aboutJava/communityprocess/final/jsr220/index.html">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.

??? style="float:left; padding-right: 1em;" />Elvis: I need an style="clear:left;">EntityManagerFactory when I can't get my
EntityManager injected, e.g. in a SE
environment
or a servlet.

Owning / Inverse Side

??? style="float:left; padding-right: 1em;" />Party line: ( href="http://jcp.org/aboutJava/communityprocess/final/jsr220/index.html">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.

??? style="float:left; padding-right: 1em;" />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

??? style="float:left; padding-right: 1em;" />Party line: ( href="http://jcp.org/aboutJava/communityprocess/final/jsr220/index.html">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.

??? style="float:left; padding-right: 1em;" />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

??? style="float:left; padding-right: 1em;" />Party line: ( href="http://jcp.org/aboutJava/communityprocess/final/jsr220/index.html">JPA
spec 6.1) A persistence unit is a logical grouping that includes:

  • An entity manager factory and its entity managers, together with
    their configuration information.
  • The set of managed classes included in the persistence unit and
    managed by the entity managers of the entity manager factory.
  • Mapping metadata (in the form of metadata annotations and/or XML
    metadata) that specifies the mapping of the classes to the
    database.

??? style="float:left; padding-right: 1em;" />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

??? style="float:left; padding-right: 1em;" />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).

??? style="float:left; padding-right: 1em;" />Elvis: That's when I
launch with href="https://glassfish.dev.java.net/javaee5/persistence/persistence-example.html#Using_in_Java_SE">-javaagent.
I also need to add the JPA library (such as toplink-essentials.jar) and
the database driver to the class path.

Related Topics >>