db-jdo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Craig L Russell <Craig.Russ...@Sun.COM>
Subject JDOHelper.getPersistenceManagerFactory section
Date Mon, 01 Oct 2007 21:07:51 GMT
Javadogs,

I've completed the specification update for these methods. Please  
take a look and comment:

Note that this section doesn't exactly match what Matthew has already  
implemented, but really close...

<proposed>
PersistenceManagerFactory methods
The methods in this section provide for bootstrapping the  
PersistenceManagerFactory by configuration according to the  
properties documented in Section 11.1. Users have a choice of  
configuration techniques:
The application provides a Map of properties used to construct a  
PersistenceManagerFactory
The application provides a Map of override properties and the name of  
a resource 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 standard Java Properties  
format whose contents define the properties for the  
PersistenceManagerFactory
The application provides a File whose contents are in standard Java  
Properties 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, and the propsLoader parameter is  
used only to load the resource to construct the Map. Once the Map  
with configuration information is obtained, the loader is used for  
loading all other resourses, including the persistence.xml,  
jdoconfig.xml, services locators, and PersistenceManagerFactory class.
A8.6-22 [public static
	PersistenceManagerFactory getPersistenceManagerFactory
		(Map props, String name, ClassLoader loader);]
A8.6-23 [public static
	PersistenceManagerFactory getPersistenceManagerFactory
		(Map props, String name);]
These methods create a new copy of the Map parameter, add the  
property “javax.jdo.option.Name” with the value of the name parameter  
and delegate to the corresponding JDOHelper method taking a Map  
parameter.
A8.6-13 [public static
	PersistenceManagerFactory getPersistenceManagerFactory
		(File propsFile);]
A8.6-14 [public static
	PersistenceManagerFactory getPersistenceManagerFactory
		(File propsFile, ClassLoader loader);]
A8.6-17 [public static
	PersistenceManagerFactory getPersistenceManagerFactory
		(InputStream stream);]
A8.6-18 [public static
	PersistenceManagerFactory getPersistenceManagerFactory
		(InputStream stream, ClassLoader loader);]
These methods use the parameter(s) passed as arguments to construct a  
Properties instance, and then delegate to the JDOHelper method  
getPersistenceManagerFactory that takes a Map parameter.
A8.6-15 [public static
	PersistenceManagerFactory getPersistenceManagerFactory
		(String propsResourceName);]
A8.6-16 [public static
	PersistenceManagerFactory getPersistenceManagerFactory
		(String propsResourceName, ClassLoader loader);]
A8.6-21[public static
	PersistenceManagerFactory getPersistenceManagerFactory
		(String propsResourceName, ClassLoader propsLoader,
			ClassLoader pmfLoader);]
These methods use the propsLoader getResourceAsStream method with the  
propsResourceName as an argument to obtain an InputStream, construct  
a new Properties instance, then delegate to the corresponding  
JDOHelper method getPersistenceManagerFactory that takes a Map  
parameter.
If the named resource does not exist, JDOHelper constructs a new Map,  
adds a property named “javax.jdo.option.Name” with the value of the  
propsResourceName parameter, and then delegates to the corresponding  
JDOHelper method taking a Map parameter. The empty string (not a null  
string) identifies the default PersistenceManagerFactory name.
A8.6-2 [public static
	PersistenceManagerFactory getPersistenceManagerFactory
		(Map props);]
A8.6-3 [This method delegates to the corresponding method with a  
class loader parameter, using the calling thread’s current  
contextClassLoader as the class loader.]
A8.6-1 [public static
	PersistenceManagerFactory getPersistenceManagerFactory
		(Map props, ClassLoader loader);]
This method returns a PersistenceManagerFactory based on entries  
contained in the Map parameter. Three map entries are significant to  
the processing of this method:
javax.jdo.option.PersistenceUnitName: If not null, this identifies  
the name of the persistence unit to be accessed. The  
Persistence.createEntityManagerFactory method is called with the  
props and PersistenceUnitName as parameters. The result is cast to  
PersistenceManagerFactory and returned to the user.
javax.jdo.option.Name: If not null, this identifies the name of the  
PersistenceManagerFactory listed in jdoconfig. The class loader loads  
META-INF/jdoconfig.xml and finds the PersistenceManagerFactory by  
name. If the value of the entry javax.jdo.option.Name is the empty  
string, this identifies the unnamed PersistenceManagerFactory listed  
in jdoconfig. JDOHelper constructs a Map instance with the contents  
of the jdoconfig entry and overrides its contents with the props  
parameter. Processing continues with PersistenceManagerFactoryClass.
javax.jdo.PersistenceManagerFactoryClass:
If not null, this identifies the name of the  
PersistenceManagerFactory class. JDOHelper uses the loader to resolve  
the PersistenceManagerFactory class name.A8.6-6 [If the class named  
by the PersistenceManagerFactoryClass property cannot be found, or is  
not accessible to the user, then JDOFatalUserException is thrown.]  
JDOHelper invokes the static method getPersistenceManagerFactory in  
the named class, passing the props as the parameter. A8.6-7 [If there  
is no public static implementation of the getPersistenceManagerFactory 
(Map) method, ]A8.6-5 [or if there are any exceptions while trying to  
call the static method,] A8.6-8 [or if the implementation of the  
static getPersistenceManagerFactory(Map) method throws an exception,  
then JDOFatalInternalException is thrown]. The nested exception  
indicates the root cause of the exception.
If null, JDOHelper loads the PersistenceManagerFactory class using  
the services lookup pattern. That is, resources named META-INF/ 
services/PersistenceManagerFactory are loaded by the loader and each  
class in turn is used to call its static getPersistenceManagerFactory  
method, passing the props as the parameter. If one of the resources  
succeeds in returning a non-null PersistenceManagerFactory, it is  
returned to the user and any exceptions (thrown by other resources)  
are ignored. If no resource succeeds, JDOFatalUserException exception  
is thrown to the user, with a nested exception for each failure.
The standard key values for the properties are found in Section 11.1.
JDO implementations are permitted to define key values of their own.  
A8.6-9 [Any key values not recognized by the implementation must be  
ignored.] A8.6-10 [Key values that are recognized but not supported  
by an implementation must result in a JDOFatalUserException thrown by  
the method.]
A8.6-11 [The returned PersistenceManagerFactory is not configurable  
(the setXXX methods will throw an exception).] A8.6-12 [JDO  
implementations might manage a map of instantiated  
PersistenceManagerFactory instances based on specified property key  
values, and return a previously instantiated  
PersistenceManagerFactory instance. In this case, the properties of  
the returned instance must exactly match the requested properties.]
A8.6-19 [public static
	PersistenceManagerFactory getPersistenceManagerFactory
		(String jndiLocation, Context context);]
A8.6-20 [@deprecated public static
	PersistenceManagerFactory getPersistenceManagerFactory
		(String jndiLocation, Context context, ClassLoader loader);]
These methods look up the PersistenceManagerFactory using the naming  
context and name supplied. The implementation’s factory method is not  
called. The behavior of this method depends on the implementation of  
the context and its interaction with the saved  
PersistenceManagerFactory object. As with the other factory methods,  
the returned PersistenceManagerFactory is not configurable.
</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!


Mime
View raw message