|
Home > Archive > Apache JDO Project > March 2007 > [DISCUSS] Named PMF proposal (JDOHelper enhancements)
You are viewing an archived Text-only version of the thread.
To view this thread in it's original format and/or if you want to reply to
this thread please [click here]
| Author |
[DISCUSS] Named PMF proposal (JDOHelper enhancements)
|
|
| Matthew Adams 2007-02-23, 7:11 pm |
| This is a proposal we discussed on the Fri Feb 23 JDO conf call. Please
review and discuss.
Overview:
Currently, there is no way to bootstrap a JDO implementation completely
externally to the source code. The developer is required to provide at
least a resource name that identifies a java.util.Properties file on the
classpath that can configure a single PMF. This makes deployment in
different environments more challenging than necessary.
Motivation:
* Source code is required to be aware of external configuration:
* In all current JDOHelper.getPersistenceManagerFactory APIs and
* in order to configure listeners.
* Aligns JDO bootstrapping with JPA bootstrapping concepts.
Proposed Solution:
* Introduce new API methods and JDO equivalent of the JPA persistence
unit concepts, including a jdo.xml file that provides for the
configuration of one or more named PMFs.
Details:
* PersistenceManagerFactory additions
/** Returns the persistence unit name of this PMF. It's the JPA
persistence unit name if configured via persistence.xml or the JDO
persistence unit name if configured via javax.jdo.xml. */
public String getName();
* JDOHelper API additions
/** The default name of the JDO configuration file. */
public static final String DEFAULT_JDO_CONFIG_RESOURCE_NAME =3D
"javax.jdo.xml";
/** The name of the default persistence unit. */
public static final String DEFAULT_PMF_NAME =3D "default";
/** Gets the PMF named "default" in the resource "javax.jdo.xml" found
via the current ClassLoader. */
public static PersistenceManagerFactory getPersistenceFactoryManager() {
return getPersistenceFactoryManagerByName(DEFAU
LT_PMF_NAME);
}
/** Gets the PMF named pmfName in the resource "javax.jdo.xml" found via
the current ClassLoader. */
public static PersistenceManagerFactory
getPersistenceManagerFactoryByName(Strin
g pmfName) {
return getPersistenceFactoryManagerByName(DEFAU
LT_PMF_NAME,
DEFAULT_JDO_CONFIG_RESOURCE_NAME);
}
/** Gets the PMF named pmfName in the resource named resourceName found
via the current ClassLoader. */
public static PersistenceManagerFactory
getPersistenceManagerFactoryByName(Strin
g pmfName, String resourceName)
{
return getPersistenceFactoryManagerByName(DEFAU
LT_PMF_NAME,
DEFAULT_JDO_CONFIG_RESOURCE_NAME, getClass().getClassLoader());
}
/** Gets the PMF named pmfName in the resource named resourceName found
via the current ClassLoader. */
public static PersistenceManagerFactory
getPersistenceManagerFactoryByName(Strin
g pmfName, String resourceName,
ClassLoader loader) {
// reads resource resourceName via given loader
// configures & returns PMF with the given name
}
* Possibilities for DEFAULT_JDO_CONFIG_RESOURCE_NAME value:
need to determine file name (similar to persistence.xml)
javax.jdo.xml
jdo.xml
...
* Proposal for JDO persistence unit configuration XML file
* Could be more like Spring beans.xml (supporting references, etc.)
* Note: Square brackets indicate optional elements/attributes
<jdo-config>
[<extension> elements wherever appropriate]
=20
<!-- Can use attributes for standardized properties -->
<!-- Can also support vendor-specific attributes and still validate
against schema -->
<persistence-manager-factory
[name=3D"default"] <!-- no name implies only the default PMF,
named "default"; can only be one per file -->
[resource=3D"..."] <!-- convenient for backward compatibility =
-->
=20
[class=3D"xcalia.ic.jdo.PersistenceManagerFactory"]
[connection-driver=3D"..."]
[connection-url=3D"..."]
[connection-user-name=3D"..."]
[connection-password=3D"..."]
[...]
>
<!-- or XML-friendly <property> elements -->
[<property name=3D"javax.jdo...." value=3D"..."/>]
[<property name=3D"javax.jdo...." value=3D"..."/>]
[<property name=3D"xcalia.ic...." value=3D"..."/>]
[...]
=20
<!-- ...and/or properties in java.util.Properties file format?
overrides <property> elements? -->
<!-- This allows people to continue to use good, old
java.util.Properties format if they want -->
<properties><![CDATA[
javax.jdo....=3D...
javax.jdo....=3D...
xcalia.ic....=3D...
...
]]></properties>
<!-- This provides a way (currently, the only way) to configure
listeners outside of the code -->
<!-- We'd have to address any class loading issues, since we're
only given a class name -->
<!-- These should have javax.jdo.listener.... property &
property value equivalents in order to keep old-fashioned
java.util.Property-formatted values consistent with these values -->
<!-- Method names default to names of corresponding interfaces;
if not present on listener-class, they're a no-op or not even called -->
[<instance-lifecycle-listener
listener-class=3D"my.jdo.InstanceListener"
classes-observed=3D"my.domain.Foo,my.domain.Bar,.."
[static-factory-method=3D"..."]
[pre-attach=3D"preAttach"]
[post-attach=3D"postAttach"]
[pre-store=3D"preStore"]
[...]
/>]
=20
<!-- The <instance-lifecycle-listener> element is sufficient,
but we could provide elements for each of the listener types -->
[<attach-lifecycle-listener
class=3D"..."
[factory-method=3D"..."]
[pre-attach=3D"preAttach"]
[post-attach=3D"postAttach"]
/>]
[...]
<!-- Can optionally include <jdo>, <orm> and <jdoquery> elements
here in order to override annotations, or developer-provided .jdo, .orm,
and/or .jdoquery files (from Erik Bengston) -->
<!-- Can add attribute to <jdo>, <orm>, and <jdoquery> to allow
for the specifiation of another resource or set of resources on the
classpath (from Craig Russell), for example: -->
<jdo
resources=3D"META-INF/production-1;META-INF/production-2;..."/>
=20
</persistence-manager-factory>
</jdo-config>=20
=20
Matthew T. Adams
Senior Consultant & Product Marketing Director
Xcalia, Inc.
matthew.adams@xcalia.com
+1 206 331 3833 Office
+1 253 732 1051 Mobile
+1 815 331 0952 Fax
http://www.xcalia.com <http://www.xcalia.com/>=20
745 Emerson St.
Palo Alto, CA 94301
=20
Xcalia provides dynamic integration software for agile enterprises to
easily create transactional composite applications. Our unique
intermediation approach enables unified, real-time access to
heterogenous data and services. Intermediation is adaptive and
configurable so application changes can be made quickly and cost
effectively without impacting the underlying systems or infrastructure.
| |
| Matthew Adams 2007-02-23, 7:11 pm |
| Here is the XSD as a work in progress, in a pre-alpha state. Should we
create a JIRA issue for this? Email seems nonideal for file management,
especially when they're not attached.
<?xml version=3D"1.0" encoding=3D"UTF-8"?>
<xs:schema targetNamespace=3D"http://java.sun.com/xml/ns/jdo/jdo-config"
xmlns=3D"http://java.sun.com/xml/ns/jdo/jdo-config"
xmlns:xs=3D"http://www.w3.org/2001/XMLSchema"
version=3D"1.0">
<!-- TODO: Decide if these should be imported, included, or
copy/pasted
<xs:import namespace=3D"http://java.sun.com/xml/ns/jdo/jdo"
schemaLocation=3D"jdo.xsd"/>
<xs:import namespace=3D"http://java.sun.com/xml/ns/jdo/orm"
schemaLocation=3D"orm.xsd"/>
<xs:import namespace=3D"http://java.sun.com/xml/ns/jdo/jdoquery"
schemaLocation=3D"jdoquery.xsd"/>
-->
<xs:element name=3D"jdo-config">
<xs:complexType>
<xs:sequence>
<xs:element minOccurs=3D"0" maxOccurs=3D"unbounded"
ref=3D"extension"/>
<xs:sequence minOccurs=3D"1" maxOccurs=3D"unbounded">
<xs:element name=3D"persistence-manager-factory">
<xs:complexType>
<xs:choice>
<xs:sequence minOccurs=3D"0" maxOccurs=3D"unbounded">
<xs:element name=3D"property">
<xs:complexType>
<xs:attributeGroup ref=3D"attlist.property"/>
</xs:complexType>
</xs:element>
</xs:sequence>
<xs:element name=3D"properties" type=3D"xs:string"/>
</xs:choice>
<xs:attributeGroup
ref=3D"attlist.persistence-manager-factory"/>
</xs:complexType>
</xs:element>
<xs:sequence minOccurs=3D"0" maxOccurs=3D"unbounded">
<xs:element name=3D"instance-lifecycle-listener">
<xs:complexType>
<xs:attributeGroup
ref=3D"attlist.instance-lifecycle-listener"/>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:sequence>
<xs:element minOccurs=3D"0" maxOccurs=3D"unbounded"
ref=3D"extension"/>
<!-- TODO: include sequences of <jdo [resources=3D""]>, <orm
[resources=3D""]>, and <jdoquery [resources=3D""]> elements here -->
</xs:sequence>
<xs:attributeGroup ref=3D"attlist.jdo-config"/>
</xs:complexType>
</xs:element>
<xs:attributeGroup name=3D"attlist.jdo-config"/>
<xs:attributeGroup name=3D"attlist.persistence-manager-factory">
<xs:attribute name=3D"name"/>
<xs:attribute name=3D"resource"/>
<xs:attribute name=3D"persistence-manager-factory-class"/>
<xs:attribute name=3D"optimistic"/>
<xs:attribute name=3D"retain-values"/>
<xs:attribute name=3D"restore-values"/>
<xs:attribute name=3D"ignore-cache"/>
<xs:attribute name=3D"nontransactional-read"/>
<xs:attribute name=3D"nontransactional-write"/>
<xs:attribute name=3D"multithreaded"/>
<xs:attribute name=3D"connection-driver-name"/>
<xs:attribute name=3D"connection-user-name"/>
<xs:attribute name=3D"connection-password"/>
<xs:attribute name=3D"connection-url"/>
<xs:attribute name=3D"connection-factory-name"/>
<xs:attribute name=3D"connection-factory2-name"/>
<xs:attribute name=3D"mapping"/>
</xs:attributeGroup>
<xs:attributeGroup name=3D"attlist.property">
<xs:attribute name=3D"name"/>
<xs:attribute name=3D"value"/>
</xs:attributeGroup>
<xs:attributeGroup name=3D"attlist.instance-lifecycle-listener">
<xs:attribute name=3D"post-attach"/>
<xs:attribute name=3D"pre-attach"/>
<xs:attribute name=3D"post-clear"/>
<xs:attribute name=3D"pre-clear"/>
<xs:attribute name=3D"post-create"/>
<xs:attribute name=3D"post-delete"/>
<xs:attribute name=3D"pre-delete"/>
<xs:attribute name=3D"post-detach"/>
<xs:attribute name=3D"pre-detach"/>
<xs:attribute name=3D"post-dirty"/>
<xs:attribute name=3D"pre-dirty"/>
<xs:attribute name=3D"post-load"/>
<xs:attribute name=3D"post-store"/>
<xs:attribute name=3D"pre-store"/>
</xs:attributeGroup>
<xs:element name=3D"extension">
<xs:complexType>
<xs:complexContent>
<xs:extension base=3D"any">
<xs:attributeGroup ref=3D"attlist.extension"/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
</xs:element>
<xs:attributeGroup name=3D"attlist.extension">
<xs:attribute name=3D"vendor-name" use=3D"required"/>
<xs:attribute name=3D"key"/>
<xs:attribute name=3D"value"/>
</xs:attributeGroup>
<xs:complexType name=3D"any" mixed=3D"true">
<xs:sequence>
<xs:any minOccurs=3D"0" maxOccurs=3D"unbounded"
processContents=3D"skip"/>
</xs:sequence>
</xs:complexType>
</xs:schema>
| |
| Craig L Russell 2007-02-24, 1:11 am |
| | |
| Andy Jefferson 2007-02-27, 7:11 pm |
| Hi Matthew,
Some comments, or rather questions :-
1. Why call this file javax.jdo.xml ?, why not jdo.xml ?, or even why not
persistence.xml ?
2. Why not just use same definition of "persistence.xml" from aforementioned
JPA spec ? When JDO2.1 has annotations not everything is always defined in a
jdo(/orm/jdoquery) file, so would be nice to have the ability to specify
classes, or jars.
3. We could certainly extend the "persistence.xml" concept to add on the
listeners, etc as proposed.
4. Why do we need "persistence-manager-factory" class="..." ? We could use the
same boot idea as JPA and have a META-INF/services/javax.jdo.XXX file
defining the PMF(s) available, and it takes the one that claims it supports
the required "persistence-unit" (or PMF)
--
Andy
| |
| Matthew Adams 2007-02-28, 1:11 am |
| >1. Why call this file javax.jdo.xml ?, why not jdo.xml ?, or=20
>even why not=20
>persistence.xml ?
>
Call it what you want -- I only proposed these names. I wouldn't call
it persistence.xml, as the contents are not the same as the
JPA-specified content. If the persistence.xml is found, its contents
are of course interpretable by the JDO implementation according to our
JPA alignment verbage defined in JDO 2.1.
>2. Why not just use same definition of "persistence.xml" from=20
>aforementioned=20
>JPA spec ?
> When JDO2.1 has annotations not everything is=20
>always defined in a=20
>jdo(/orm/jdoquery) file, so would be nice to have the ability=20
>to specify=20
>classes, or jars.
>
Because it's not the same as the persistence.xml. If we're missing the
ability to specify classes or jars, let's add it!
>3. We could certainly extend the "persistence.xml" concept to=20
>add on the=20
>listeners, etc as proposed.
>
Cool, but I'd still like to keep a JDO affinity
("InstanceLifecycleListeners") plus support for the JPA concepts
according to our intended alignment.
>4. Why do we need "persistence-manager-factory" class=3D"..." ?=20
>=20
Basically, for backward similarity only, not necessarily backward
compatibility. It was only a suggestion as well, since we could just go
with a <property name=3D"javax.jdo.PersistenceManagerFactoryClass"
value=3D"..."/> element. It's just that this property is almost always
present, so I thought a convenient shortcut would be nice.
>We could use the=20
>same boot idea as JPA and have a META-INF/services/javax.jdo.XXX file=20
>defining the PMF(s) available, and it takes the one that=20
>claims it supports=20
>the required "persistence-unit" (or PMF)
>
I like this suggestion! I assume the following would be true -- please
correct where I've got it wrong.
* The name of this file is
"META-INF/services/javax.jdo.PersistenceManagerFactory"
* This is a text file
* The contents of the file would be the name of the provider's
implementation class of javax.jdo.PersistenceManagerFactory
* There is a file with the same name as the contents of the file
"META-INF/services/javax.jdo.PersistenceManagerFactory"
* The contents of this file are the same as the proposed content
of javax.jdo.xml (or jdo.xml, or ...) containing the named PMFs.
Thoughts?
-matthew
| |
| Andy Jefferson 2007-02-28, 1:11 am |
| > Call it what you want -- I only proposed these names. I wouldn't call
> it persistence.xml, as the contents are not the same as the
> JPA-specified content. If the persistence.xml is found, its contents
> are of course interpretable by the JDO implementation according to our
> JPA alignment verbage defined in JDO 2.1.
ok. So a JDO2.1 impl has to understand both "persistence.xml" (JPA format) and
this "jdo.xml" ? No problem if that is the case but just want to understand
what we're specifying here since not everyone was on this conf call.
>
> Because it's not the same as the persistence.xml. If we're missing the
> ability to specify classes or jars, let's add it!
ok.
>
> Basically, for backward similarity only, not necessarily backward
> compatibility. It was only a suggestion as well, since we could just go
> with a <property name="javax.jdo.PersistenceManagerFactoryClass"
> value="..."/> element. It's just that this property is almost always
> present, so I thought a convenient shortcut would be nice.
ok.
>
> I like this suggestion! I assume the following would be true -- please
> correct where I've got it wrong.
>
> * The name of this file is
> "META-INF/services/javax.jdo.PersistenceManagerFactory"
> * This is a text file
> * The contents of the file would be the name of the provider's
> implementation class of javax.jdo.PersistenceManagerFactory
Yes. See a mail by Erik to the lists on 19/01/2007 called "Proposal for
Service Discovery". JDOHelper would then have the job of finding all services
files of this name ("javax.jdo.PersistenceManagerFactory"), and from the
contents finding the relevant PMF to instantiate for a particular PMF name.
Since this appears to be an extension to JDO and not the simple mapping across
of terminology JDO-JPA (being able to read a "persistence.xml"), I'd ask are
we just confusing users by having "persistenceUnitName" and "transactionType"
for when a JDO impl reads a "persistence.xml", yet here we also have a PMF
name (which is the same as a persistence-unit name) for when we use this
file.
--
Andy
| |
| Matthew Adams 2007-02-28, 1:11 pm |
| Inline...
>wouldn't call
>according to our
>
>ok. So a JDO2.1 impl has to understand both "persistence.xml"=20
>(JPA format) and=20
>this "jdo.xml" ? No problem if that is the case but just want=20
>to understand=20
>what we're specifying here since not everyone was on this conf call.
>
Yes, this is correct. I guess since JPA, which uses the base namespace
"javax.persistence" and calls the file "persistence.xml", then we should
probably call JDO bootstrap file "jdo.xml". Done.
>META-INF/services/javax.jdo.XXX file
>true -- please
>
>Yes. See a mail by Erik to the lists on 19/01/2007 called=20
>"Proposal for=20
>Service Discovery". JDOHelper would then have the job of=20
>finding all services=20
>files of this name ("javax.jdo.PersistenceManagerFactory"),=20
>and from the=20
>contents finding the relevant PMF to instantiate for a=20
>particular PMF name.
>
>
>Since this appears to be an extension to JDO and not the=20
>simple mapping across=20
>of terminology JDO-JPA (being able to read a=20
>"persistence.xml"), I'd ask are=20
>we just confusing users by having "persistenceUnitName" and=20
>"transactionType"=20
>for when a JDO impl reads a "persistence.xml", yet here we=20
>also have a PMF=20
>name (which is the same as a persistence-unit name) for when=20
>we use this=20
>file.
>
This was brought up on the conference call. A "persistence unit" is the
same thing as a "named PMF". We decided that we won't use the term
"named PMF" in the specification -- we'll just go with "persistence
unit". There will be a JPA flavor (already specified) and a
corresponding JDO flavor (adding a name to a PMF, the getName() method).
As far as transaction type, I think they're the same. Craig, can you
please comment on transaction type?
-matthew
| |
| Craig L Russell 2007-03-01, 1:11 am |
| |
|
|
|
|