JDOManager (Castor JavaDoc)

java.lang.Object
- org.exolab.castor.jdo.JDOManager

All Implemented Interfaces:

java.io.Serializable, javax.naming.Referenceable, javax.naming.spi.ObjectFactory, DataObjects
```
public final class JDOManager
extends java.lang.Object
implements DataObjects, javax.naming.Referenceable, javax.naming.spi.ObjectFactory, java.io.Serializable
```
Implementation of the JDOManager engine used for obtaining database connections. After successful instantiation, getDatabase() is used to obtain a new database connection. Any number of database connections can be obtained from the same JDOManager object.
An instance of this class is contructed with a two-step approach:
- load the JDOManager configuration file through one of the static loadConfiguration() methods
- create an instance of the JDOManager engine using the factory method createInstance(String) where you supply one of the database names defined in the configuration file loaded in step 1.
Example:
```
 
 ...

 JDOManager jdo;
 Database db;
 
 try {
    // load the JDOManager configuration file
    JDOManager.loadConfiguration("jdo-config.xml");
 
    // construct a new JDOManager for 'mydb'
    jdo = JDOManager.createInstance("mydb");
 
    // open a connection to the database
    db = jdo.getDatabase();
 } catch (MappingException ex) {
    ...
 } catch (DatabaseNotFoundException ex) {
    ...
 }
 
 
```
Version:

$Revision: 8129 $ $Date: 2006-04-25 15:08:23 -0600 (Tue, 25 Apr 2006) $

Author:

Assaf Arkin, Bruce Snyder, Werner Guttmann, Ralf Joachim

See Also:

Serialized Form

Field Summary

Fields
Modifier and Type	Field	Description
`static java.lang.String`	`DEFAULT_DESCRIPTION`	Default description.
`static int`	`DEFAULT_LOCK_TIMEOUT`	The default lock timeout (specified in seconds).

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`void`	`close()`	Lyfe-cycle methods to close JDOManager instance and initiate resource cleanup.
`static JDOManager`	`createInstance(java.lang.String databaseName)`	Factory method for creating a JDOManager instance for one of the databases configured in the JDOManager configuration file.
`static void`	`disposeInstance(java.lang.String databaseName)`	Method to dispose a JDOManager instance.
`CallbackInterceptor`	`getCallbackInterceptor()`	Returns the callback interceptor.
`java.lang.ClassLoader`	`getClassLoader()`	Returns the application classloader.
`org.xml.sax.InputSource`	`getConfiguration()`	Return the URL of the database configuration file.
`ConnectionFactory`	`getConnectionFactory()`	Returns the ConnectionFactory for this JDOManager instance.
`Database`	`getDatabase()`	Opens and returns a connection to the database.
`java.lang.String`	`getDatabaseName()`	Returns the name of this database.
`boolean`	`getDatabasePooling()`	Indicates if database pooling is enable or not.
`java.lang.String`	`getDescription()`	Returns the description of this database.
`org.xml.sax.EntityResolver`	`getEntityResolver()`	Returns the entity resolver.
`InstanceFactory`	`getInstanceFactory()`	Returns the instance factory.
`int`	`getLockTimeout()`	Returns the lock timeout for this database.
`java.lang.Object`	`getObjectInstance(java.lang.Object refObj, javax.naming.Name name, javax.naming.Context nameCtx, java.util.Hashtable<?,?> env)`
`javax.naming.Reference`	`getReference()`	Constructs a new reference to JDOManager being its own factory.
`boolean`	`isAutoStore()`	Return if the next database instance will be set to `autoStore`.
`static void`	`loadConfiguration(java.lang.String url)`	Load the JDOManager configuration from the specified location.
`static void`	`loadConfiguration(java.lang.String url, java.lang.ClassLoader loader)`	Load the JDOManager configuration from the specified location using a custom class loader.
`static void`	`loadConfiguration(java.lang.String url, java.lang.ClassLoader loader, JDOClassDescriptorResolver classDescriptorResolver)`	Load the JDOManager configuration from the specified location using a custom class loader.
`static void`	`loadConfiguration(java.lang.String name, java.lang.String engine, javax.sql.DataSource datasource, Mapping mapping, javax.transaction.TransactionManager txManager)`	Initialize the JDOManager configuration with given name, engine, datasource, transaction demarcation and mapping.
`static void`	`loadConfiguration(JdoConf jdoConf, java.lang.ClassLoader loader, java.lang.String baseURI)`	Load the JDOManager configuration from the specified in-memory JdoConf.
`static void`	`loadConfiguration(JdoConf jdoConf, java.lang.String baseURI)`	Load the JDOManager configuration from the specified in-memory JdoConf.
`static void`	`loadConfiguration(JdoConf jdoConf, org.xml.sax.EntityResolver resolver, java.lang.ClassLoader loader, java.lang.String baseURI)`	Load the JDOManager configuration from the specified in-memory JdoConf.
`static void`	`loadConfiguration(org.xml.sax.InputSource source, org.xml.sax.EntityResolver resolver, java.lang.ClassLoader loader)`	Load the JDOManager configuration from the specified input source using a custom class loader.
`static void`	`loadConfiguration(org.xml.sax.InputSource source, org.xml.sax.EntityResolver resolver, java.lang.ClassLoader loader, JDOClassDescriptorResolver classDescriptorResolver)`	Load the JDOManager configuration from the specified input source using a custom class loader.
`void`	`setAutoStore(boolean autoStore)`	Sets `autoStore` mode.
`void`	`setCallbackInterceptor(CallbackInterceptor callback)`	Overrides the default callback interceptor by a custom interceptor for this database source.
`void`	`setDatabasePooling(boolean pool)`	Enable/disable database pooling.
`void`	`setDescription(java.lang.String description)`	Sets the description of this database.
`void`	`setInstanceFactory(InstanceFactory factory)`	Overrides the default instance factory by a custom one to be used by Castor to obtaining an instance of a data object when it is needed during loading.
`void`	`setLockTimeout(int seconds)`	Sets the lock timeout for this database.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - DEFAULT_LOCK_TIMEOUT
```
public static final int DEFAULT_LOCK_TIMEOUT
```
    The default lock timeout (specified in seconds).
    
    See Also:
    
    Constant Field Values
  - DEFAULT_DESCRIPTION
```
public static final java.lang.String DEFAULT_DESCRIPTION
```
    Default description.
    
    See Also:
    
    Constant Field Values
- Method Detail
  - createInstance
```
public static JDOManager createInstance(java.lang.String databaseName)
                                 throws MappingException
```
    Factory method for creating a JDOManager instance for one of the databases configured in the JDOManager configuration file. Please make sure that you call loadConfiguration() first.
    
    Parameters:
    
    databaseName - Database name as configured in the JDOManager configuration file.
    
    Returns:
    
    A JDOManager instance.
    
    Throws:
    
    MappingException - The mapping file is invalid, or any error occurred trying to load the mapping from JDOManager configuration file.
  - disposeInstance
```
public static void disposeInstance(java.lang.String databaseName)
```
    Method to dispose a JDOManager instance.
    Experimental: Only intended to test loading of configurations at JDOManager and DatabaseRegistry at the moment. Will not cleanup all internal object structures that get initialized with a call to JDOManager.createInstance().
    
    Parameters:
    
    databaseName - Database name as configured in the JDOManager configuration file.
  - loadConfiguration
```
public static void loadConfiguration(java.lang.String name,
                                     java.lang.String engine,
                                     javax.sql.DataSource datasource,
                                     Mapping mapping,
                                     javax.transaction.TransactionManager txManager)
                              throws MappingException
```
    Initialize the JDOManager configuration with given name, engine, datasource, transaction demarcation and mapping.
    
    Parameters:
    
    name - The Name of the database configuration.
    
    engine - The Name of the persistence factory to use.
    
    datasource - The preconfigured datasource to use for creating connections.
    
    mapping - The previously loaded mapping.
    
    txManager - The transaction manager to use.
    
    Throws:
    
    MappingException - If LockEngine could not be initialized.
  - loadConfiguration
```
public static void loadConfiguration(JdoConf jdoConf,
                                     org.xml.sax.EntityResolver resolver,
                                     java.lang.ClassLoader loader,
                                     java.lang.String baseURI)
                              throws MappingException
```
    Load the JDOManager configuration from the specified in-memory JdoConf. In addition, custom entity resolver and class loader for the mappings can be provided.
    
    Parameters:
    
    jdoConf - the in-memory JdoConf.
    
    resolver - An (optional) entity resolver to resolve cached entities, e.g. for external mapping documents.
    
    loader - The class loader to use, null for the default
    
    baseURI - The base URL for the mapping
    
    Throws:
    
    MappingException - The mapping file is invalid, or any error occured trying to load the JDO configuration/mapping
  - loadConfiguration
```
public static void loadConfiguration(JdoConf jdoConf,
                                     java.lang.ClassLoader loader,
                                     java.lang.String baseURI)
                              throws MappingException
```
    Load the JDOManager configuration from the specified in-memory JdoConf. In addition, a custom class loader for the mappings can be provided.
    
    Parameters:
    
    jdoConf - the in-memory JdoConf.
    
    loader - The class loader to use, null for the default
    
    baseURI - The base URL for the mapping
    
    Throws:
    
    MappingException - The mapping file is invalid, or any error occured trying to load the JDO configuration/mapping
  - loadConfiguration
```
public static void loadConfiguration(JdoConf jdoConf,
                                     java.lang.String baseURI)
                              throws MappingException
```
    Load the JDOManager configuration from the specified in-memory JdoConf.
    
    Parameters:
    
    jdoConf - the in-memory JdoConf.
    
    baseURI - The base URL for the mapping
    
    Throws:
    
    MappingException - The mapping file is invalid, or any error occured trying to load the JDO configuration/mapping
  - loadConfiguration
```
public static void loadConfiguration(org.xml.sax.InputSource source,
                                     org.xml.sax.EntityResolver resolver,
                                     java.lang.ClassLoader loader)
                              throws MappingException
```
    Load the JDOManager configuration from the specified input source using a custom class loader. In addition, a custom entity resolver can be provided.
    
    Parameters:
    
    source - The JDOManager configuration file describing the databases, connection factory and mappings.
    
    resolver - An (optional) entity resolver to resolve cached entities, e.g. for external mapping documents.
    
    loader - The class loader to use, null for the default
    
    Throws:
    
    MappingException - The mapping file is invalid, or any error occured trying to load the JDO configuration/mapping
  - loadConfiguration
```
public static void loadConfiguration(org.xml.sax.InputSource source,
                                     org.xml.sax.EntityResolver resolver,
                                     java.lang.ClassLoader loader,
                                     JDOClassDescriptorResolver classDescriptorResolver)
                              throws MappingException
```
    Load the JDOManager configuration from the specified input source using a custom class loader. In addition, a custom entity resolver can be provided.
    
    Parameters:
    
    source - The JDOManager configuration file describing the databases, connection factory and mappings.
    
    resolver - An (optional) entity resolver to resolve cached entities, e.g. for external mapping documents.
    
    loader - The class loader to use, null for the default
    
    classDescriptorResolver - ClassDescriptorResolver used for class to class descriptor resolution.
    
    Throws:
    
    MappingException - The mapping file is invalid, or any error occurred trying to load the JDO configuration/mapping
  - loadConfiguration
```
public static void loadConfiguration(java.lang.String url,
                                     java.lang.ClassLoader loader)
                              throws MappingException
```
    Load the JDOManager configuration from the specified location using a custom class loader.
    
    Parameters:
    
    url - The location from which to load the configuration file.
    
    loader - The custom class loader to use, null for the default.
    
    Throws:
    
    MappingException - The mapping file is invalid, or any error occured trying to load the JDOManager configuration/mapping.
  - loadConfiguration
```
public static void loadConfiguration(java.lang.String url,
                                     java.lang.ClassLoader loader,
                                     JDOClassDescriptorResolver classDescriptorResolver)
                              throws MappingException
```
    Load the JDOManager configuration from the specified location using a custom class loader.
    
    Parameters:
    
    url - The location from which to load the configuration file.
    
    loader - The custom class loader to use, null for the default. *
    
    classDescriptorResolver - ClassDescriptorResolver used for class to class descriptor resolution.
    
    Throws:
    
    MappingException - The mapping file is invalid, or any error occurred trying to load the JDOManager configuration/mapping.
  - loadConfiguration
```
public static void loadConfiguration(java.lang.String url)
                              throws MappingException
```
    Load the JDOManager configuration from the specified location.
    
    Parameters:
    
    url - The location from which to load the configuration file.
    
    Throws:
    
    MappingException - The mapping file is invalid, or any error occured trying to load the JDOManager configuration/mapping.
  - getClassLoader
```
public java.lang.ClassLoader getClassLoader()
```
    Returns the application classloader.
    
    Returns:
    
    The currently used ClassLoader or null if default is used.
  - getEntityResolver
```
public org.xml.sax.EntityResolver getEntityResolver()
```
    Returns the entity resolver.
    
    Returns:
    
    The EntityResolver currently in use.
  - getConfiguration
```
public org.xml.sax.InputSource getConfiguration()
```
    Return the URL of the database configuration file.
    The standard name for this property is configuration.
    
    Returns:
    
    The URL of the database configuration file as InputSource.
  - setCallbackInterceptor
```
public void setCallbackInterceptor(CallbackInterceptor callback)
```
    Overrides the default callback interceptor by a custom interceptor for this database source.
    The interceptor is a callback that notifies data objects on persistent state events.
    If callback interceptor is not overrided, events will be sent only to that data objects that implement the org.exolab.castor.jdo.Persistent interface.
    
    Parameters:
    
    callback - The callback interceptor, null if disabled
  - getCallbackInterceptor
```
public CallbackInterceptor getCallbackInterceptor()
```
    Returns the callback interceptor.
    
    Returns:
    
    The currently used CallbackInterceptor or null if not overriden.
  - setInstanceFactory
```
public void setInstanceFactory(InstanceFactory factory)
```
    Overrides the default instance factory by a custom one to be used by Castor to obtaining an instance of a data object when it is needed during loading.
    If instance factory is not overrided, and if class loader is not set, Class.forName(className).newInstance() will be used to create a new instance. If instance factory is not override, and class loader is set, loader.loadClass(className).newInstance() will be used instead.
    
    Parameters:
    
    factory - The instance factory, null to use the default
  - getInstanceFactory
```
public InstanceFactory getInstanceFactory()
```
    Returns the instance factory.
    
    Returns:
    
    The currently used InstanceFactoryor null if not overriden.
  - setLockTimeout
```
public void setLockTimeout(int seconds)
```
    Sets the lock timeout for this database. Use zero for immediate timeout, an infinite value for no timeout. The timeout is specified in seconds.
    The standard name for this property is lockTimeout.
    
    Parameters:
    
    seconds - The lock timeout, specified in seconds
  - getLockTimeout
```
public int getLockTimeout()
```
    Returns the lock timeout for this database.
    The standard name for this property is lockTimeout.
    
    Returns:
    
    The lock timeout, specified in seconds
  - setDescription
```
public void setDescription(java.lang.String description)
```
    Sets the description of this database.
    The standard name for this property is description.
    
    Specified by:
    
    setDescription in interface DataObjects
    
    Parameters:
    
    description - The description of this database
  - getDescription
```
public java.lang.String getDescription()
```
    Returns the description of this database.
    The standard name for this property is description.
    
    Specified by:
    
    getDescription in interface DataObjects
    
    Returns:
    
    The description of this database
  - setDatabasePooling
```
public void setDatabasePooling(boolean pool)
```
    Enable/disable database pooling. This option only affects JDOManager if J2EE transactions and a transaction is associated with the thread that call getDatabase(). If database pooling is enabled, JDOManager will first search in the pool to see if there is already a database for the current transaction. If found, it returns the database; if not, it create a new one, associates it will the transaction and return the newly created database.
    This method should be called before getDatabase().
    
    Parameters:
    
    pool - true to enable database pooling
  - getDatabasePooling
```
public boolean getDatabasePooling()
```
    Indicates if database pooling is enable or not. The use of this method only makes sense in a J2EE container environment with global transaction coordinated by a J2EE transaction manager.
    
    Returns:
    
    True if pooling is enabled for this Database instance.
    
    See Also:
    
    setDatabasePooling(boolean)
  - setAutoStore
```
public void setAutoStore(boolean autoStore)
```
    Sets autoStore mode.
    
    Parameters:
    
    autoStore - True if user prefer all reachable object to be stored automatically; False if user want only dependent object to be stored.
  - isAutoStore
```
public boolean isAutoStore()
```
    Return if the next database instance will be set to autoStore.
    
    Returns:
    
    True if autoStore is enabled.
  - getDatabaseName
```
public java.lang.String getDatabaseName()
```
    Returns the name of this database.
    The standard name for this property is databaseName.
    
    Specified by:
    
    getDatabaseName in interface DataObjects
    
    Returns:
    
    The name of this database
  - getConnectionFactory
```
public ConnectionFactory getConnectionFactory()
                                       throws MappingException
```
    Returns the ConnectionFactory for this JDOManager instance.
    
    Returns:
    
    The connection factory used by this JDOManager instance.
    
    Throws:
    
    MappingException - If database can not be instantiated or is not configured.
  - getDatabase
```
public Database getDatabase()
                     throws PersistenceException
```
    Opens and returns a connection to the database. If no configuration exists for the named database a DatabaseNotFoundException is thrown.
    
    Specified by:
    
    getDatabase in interface DataObjects
    
    Returns:
    
    An open connection to the database.
    
    Throws:
    
    PersistenceException - Database access failed.
  - getReference
```
public javax.naming.Reference getReference()
```
    Constructs a new reference to JDOManager being its own factory.
    
    Specified by:
    
    getReference in interface javax.naming.Referenceable
    
    Returns:
    
    A new Reference to JDOManager.
    
    See Also:
    
    Reference, ObjectFactory
  - getObjectInstance
```
public java.lang.Object getObjectInstance(java.lang.Object refObj,
                                          javax.naming.Name name,
                                          javax.naming.Context nameCtx,
                                          java.util.Hashtable<?,?> env)
                                   throws javax.naming.NamingException
```
    Specified by:
    
    getObjectInstance in interface javax.naming.spi.ObjectFactory
    
    Throws:
    
    javax.naming.NamingException
  - close
```
public void close()
```
    Lyfe-cycle methods to close JDOManager instance and initiate resource cleanup.

Class JDOManager

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_LOCK_TIMEOUT

DEFAULT_DESCRIPTION

Method Detail

createInstance

disposeInstance

loadConfiguration

loadConfiguration

loadConfiguration

loadConfiguration

loadConfiguration

loadConfiguration

loadConfiguration

loadConfiguration

loadConfiguration

getClassLoader

getEntityResolver

getConfiguration

setCallbackInterceptor

getCallbackInterceptor

setInstanceFactory

getInstanceFactory

setLockTimeout

getLockTimeout

setDescription

getDescription

setDatabasePooling

getDatabasePooling

setAutoStore

isAutoStore

getDatabaseName

getConnectionFactory

getDatabase

getReference

getObjectInstance

close