Mailing-List: contact jdo-dev-help@db.apache.org; run by ezmlm
Precedence: bulk
Reply-To: jdo-dev@db.apache.org
Received-SPF: neutral (nike.apache.org: local policy)
From: "Matthew T. Adams" <matthew@matthewadams.org>
To: <Craig.Russell@sun.com>,
	<jdo-dev@db.apache.org>
Cc: "'JDO Expert Group'" <jdo-experts-ext@sun.com>
References: <9A889CEC-40CC-48F3-AC6F-9C018959CFD5@SUN.com>
 <C4EE0C27-BED2-4EEC-B0D2-CA7A2BF3920D@SUN.com>
In-Reply-To: <C4EE0C27-BED2-4EEC-B0D2-CA7A2BF3920D@SUN.com>
Subject: RE: Please review PMF bootstrap process for JDO specification
Date: Thu, 13 Sep 2007 16:16:19 -0700
Message-ID: <029c01c7f65c$1862c9e0$49285da0$@org>
MIME-Version: 1.0
Content-Type: text/plain;
	charset="US-ASCII"
Content-Transfer-Encoding: 7bit
Thread-Index: Acf2TgLooOgDeaddRHSXI4JeyuGpiwADMplg
Content-Language: en-us

I'd also like to see a section with some examples of the jdoconfig.xml,
especially WRT configuring listeners, since you couldn't do that outside of
code prior to 2.1...I'll put some together and send.

-----Original Message-----
From: Craig.Russell@sun.com [mailto:Craig.Russell@sun.com] 
Sent: Thursday, September 13, 2007 2:34 PM
To: jdo-dev@db.apache.org
Cc: JDO Expert Group
Subject: Re: Please review PMF bootstrap process for JDO specification

Updated per comments from Matthew and Michelle.

For review:

<proposed>
8.6 PersistenceManagerFactory methods
JDOHelper provides several methods to bootstrap an application by  
looking up a PersistenceManagerFactory for the application to use.  
Users have a choice of configuration techniques.
- The application provides a Map of properties that are used to  
construct a PersistenceManagerFactory
- The application provides the name of a resource in standard Java  
Properties format whose contents define the Properties for the  
PersistenceManagerFactory
- The application provides an InputStream in Properties.store(Writer)  
format whose contents define the Properties for the  
PersistenceManagerFactory
- The application provides a File whose contents are in  
Properties.store(Writer) format which define the Properties for the  
PersistenceManagerFactory
- The application provides a JNDI name and context in which the name  
is defined
- The application provides a resource named META-INF/jdoconfig.xml  
and optionally META-INF/services/javax.jdo.PersistenceManagerFactory  
which contain configuration information
- The application provides a resource named META-INF/persistence.xml  
and optionally META-INF/services/ 
javax.persistence.EntityManagerFactory which contain configuration  
information

For the cases of InputStream, File, and resource name, a Properties  
instance is constructed by JDOHelper and passed to one of the  
getPersistenceManagerFactory(Map) methods. When using these  
techniques, each configuration of PersistenceManagerFactory is  
contained in a separate resource.

When using jdoconfig.xml or persistence.xml, multiple  
PersistenceManagerFactory configurations can be contained in the  
file. The specific PersistenceManagerFactory configuration to be used  
is selected by the name provided by the caller of one of the  
getPersistenceManagerFactory(String name) methods.

The jdoconfig.xml file is used to construct a Properties instance  
which is then passed to one of the get PersistenceManagerFactory(Map  
props) methods.

public static PersistenceManagerFactory getPersistenceManagerFactory
(String name);

public static PersistenceManagerFactory getPersistenceManagerFactory
(String name, ClassLoader pmfLoader);

public static PersistenceManagerFactory getPersistenceManagerFactory
(String name, ClassLoader resourceLoader,
ClassLoader pmfLoader);

These methods look up and return the PersistenceManagerFactory based  
on the name parameter. The name parameter is first used to load a  
resource using the resource loader. The resource is assumed to be in  
the standard Java Properties format. The resource is then used to  
construct a Properties instance which is passed as a parameter to the  
corresponding getPersistenceManagerFactory(Map) method.

If there is no resource of that name, JDOHelper attempts to load the   
META-INF/jdoconfig.xml files. If loading of jdoconfig.xml is  
successful, JDOHelper attempts to find a persistence-manager-factory  
element with the name attribute corresponding to the name parameter.  
If successful, JDOHelper constructs a Properties instance from the  
persistence-manager-factory element and passes it to the  
getPersistenceManagerFactory(Map) method.

If either loading jdoconfig.xml or finding the persistence-manager- 
factory fails, JDOHelper calls JPA  
Persistence.createEntityManagerFactory(String PUName). If this is  
successful, and the returned EntityManagerFactory implements  
PersistenceManagerFactory, JDOHelper returns it to the application.

     public static PersistenceManagerFactory  
getPersistenceManagerFactory()

     public static PersistenceManagerFactory  
getPersistenceManagerFactory(ClassLoader cl)

     public static PersistenceManagerFactory  
getPersistenceManagerFactory(
             ClassLoader resourceLoader,
             ClassLoader pmfLoader)

These methods have the same behavior as the corresponding  
getPersistenceManagerFactory(String name) methods if null is passed  
as the name parameter. The methods return the anonymous (unnamed)  
PersistenceManagerFactory as configured in the configuration files  
(META-INF/jdoconfig.xml and META-INF/services/ 
javax.jdo.PersistenceManagerFactory).

public static
PersistenceManagerFactory getPersistenceManagerFactory
(Map props);

public static PersistenceManagerFactory getPersistenceManagerFactory
(Map props, ClassLoader loader);

public static PersistenceManagerFactory getPersistenceManagerFactory
(Map props, ClassLoader resourceLoader, ClassLoader pmfLoader);

These methods return a PersistenceManagerFactory based on properties  
contained in the Map parameter. If no class loader is specified, the  
current thread's context class loader is used to both access the  
configuration files and load the PersistenceManagerFactory class. If  
only one class loader is specified, the parameter is used to both  
access the configuration files and load the PersistenceManagerFactory  
class. If both class loaders are specified, the resource loader is  
used to access the configuration files, and the pmf loader is used to  
load the PersistenceManagerFactory class.

If there is no property named  
javax.jdo.PersistenceManagerFactoryClass in the Map, then the class  
is looked up via the services protocol. That is, a resource named  
META-INF/services/javax.jdo.PersistenceManagerFactory is looked up  
via the resource loader. If this resource cannot be accessed, a  
JDOFatalUserException is thrown. If the resource is loadable then it  
defines the name of a class that is loaded using the pmf loader. If  
multiple resources named META-INF/services/ 
javax.jdo.PersistenceManagerFactory are accessible via the resource  
loader, only the first resource is used.

8.6.1 The jdoconfig.xml descriptor
Document root element jdoconfig
The root element contains one or more persistence-manager-factory  
elements.

Element persistence-manager-factory contains zero or more property  
elements and zero or more instance-lifecycle-listener elements.

Attributes of persistence-manager-factory include the boolean  
attributes optimistic, retain-values, restore-values, ignore-cache,  
nontransactional-read, nontransactional-write, detach-all-on-commit,  
and multithreaded; and string attributes class, persistence-unit- 
name, connection-driver-name, connection-user-name, connection- 
password, connection-url, connection-factory-name, connection- 
factory2-name, mapping, and server-time-zone-id.

Element property contains attributes name and value.

Element instance-lifecycle-listener contains attributes listener  
which names the class of the listener; and classes which names the  
classes listened to. The semantics of instance-lifecycle-listener are  
that the listeners are registered with the persistence-manager- 
factory exactly as if  for each listener,  
addInstanceLifecycleListener (InstanceLifecycleListener listener,  
Class[] classes) were called on the pmf instance prior to returning  
it to the user.

</proposed>

Craig Russell
Architect, Sun Java Enterprise System http://java.sun.com/products/jdo
408 276-5638 mailto:Craig.Russell@sun.com
P.S. A good JDO? O, Gasp!


Craig Russell
Architect, Sun Java Enterprise System http://java.sun.com/products/jdo
408 276-5638 mailto:Craig.Russell@sun.com
P.S. A good JDO? O, Gasp!