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.
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.
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; . . . }
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.
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".
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.
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.
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.
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?
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.
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.