Mailing-List: contact jdo-dev-help@db.apache.org; run by ezmlm
Precedence: bulk
Reply-To: jdo-dev@db.apache.org
Message-ID: <25999101.1172283185837.JavaMail.jira@brutus>
Date: Fri, 23 Feb 2007 18:13:05 -0800 (PST)
From: "Matthew T. Adams (JIRA)" <jira@apache.org>
To: jdo-dev@db.apache.org
Subject: [jira] Created: (JDO-467) Named PMF proposal / JDOHelper
 enhancements
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 7bit

Named PMF proposal / JDOHelper enhancements
-------------------------------------------

                 Key: JDO-467
                 URL: https://issues.apache.org/jira/browse/JDO-467
             Project: JDO
          Issue Type: New Feature
          Components: api2, api2-legacy
    Affects Versions: JDO 2 maintenance release 1
            Reporter: Matthew T. Adams


>From the email on the expert group & jdo-dev alias:

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 =
"javax.jdo.xml";

/** The name of the default persistence unit. */
public static final String DEFAULT_PMF_NAME = "default";

/** Gets the PMF named "default" in the resource "javax.jdo.xml" found
via the current ClassLoader. */
public static PersistenceManagerFactory getPersistenceFactoryManager() {
    return getPersistenceFactoryManagerByName(DEFAULT_PMF_NAME);
}
/** Gets the PMF named pmfName in the resource "javax.jdo.xml" found via
the current ClassLoader. */
public static PersistenceManagerFactory
getPersistenceManagerFactoryByName(String pmfName) {
    return getPersistenceFactoryManagerByName(DEFAULT_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(String pmfName, String resourceName)
{
    return getPersistenceFactoryManagerByName(DEFAULT_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(String 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]
    
    <!-- Can use attributes for standardized properties -->
    <!-- Can also support vendor-specific attributes and still validate
against schema -->
    <persistence-manager-factory
        [name="default"] <!-- no name implies only the default PMF,
named "default"; can only be one per file -->
        [resource="..."] <!-- convenient for backward compatibility -->
        
        [class="xcalia.ic.jdo.PersistenceManagerFactory"]
        [connection-driver="..."]
        [connection-url="..."]
        [connection-user-name="..."]
        [connection-password="..."]
        [...]
    >
        <!-- or XML-friendly <property> elements -->
        [<property name="javax.jdo...." value="..."/>]
        [<property name="javax.jdo...." value="..."/>]
        [<property name="xcalia.ic...." value="..."/>]
        [...]
        
        <!-- ...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....=...
            javax.jdo....=...
            xcalia.ic....=...
            ...
        ]]></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="my.jdo.InstanceListener"
            classes-observed="my.domain.Foo,my.domain.Bar,.."
            [static-factory-method="..."]
            [pre-attach="preAttach"]
            [post-attach="postAttach"]
            [pre-store="preStore"]
            [...]
        />]
        
        <!-- The <instance-lifecycle-listener> element is sufficient,
but we could provide elements for each of the listener types -->
        [<attach-lifecycle-listener
            class="..."
            [factory-method="..."]
            [pre-attach="preAttach"]
            [post-attach="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="META-INF/production-1;META-INF/production-2;..."/>
        
    </persistence-manager-factory>
</jdo-config> 


-- 
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.