org.exolab.castor.jdo

Class JDOManager

public final class JDOManager extends Object implements DataObjects, Referenceable, ObjectFactory, 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:

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: 6216 $ $Date: 2006-04-25 15:08:23 -0600 (Tue, 25 Apr 2006) $

Author: Assaf Arkin Bruce Snyder Werner Guttmann Ralf Joachim

Field Summary
static StringDEFAULT_DESCRIPTION
Default description.
static intDEFAULT_LOCK_TIMEOUT
The default lock timeout (specified in seconds).
Method Summary
voidclose()
Lyfe-cycle methods to close JDOManager instance and initiate resource cleanup.
static JDOManagercreateInstance(String databaseName)
Factory method for creating a JDOManager instance for one of the databases configured in the JDOManager configuration file.
CallbackInterceptorgetCallbackInterceptor()
Returns the callback interceptor.
ClassLoadergetClassLoader()
Returns the application classloader.
InputSourcegetConfiguration()
Return the URL of the database configuration file.
ConnectionFactorygetConnectionFactory()
Returns the ConnectionFactory for this JDOManager instance.
DatabasegetDatabase()
Opens and returns a connection to the database.
StringgetDatabaseName()
Returns the name of this database.
booleangetDatabasePooling()
Indicates if database pooling is enable or not.
StringgetDescription()
Returns the description of this database.
EntityResolvergetEntityResolver()
Returns the entity resolver.
InstanceFactorygetInstanceFactory()
Returns the instance factory.
intgetLockTimeout()
Returns the lock timeout for this database.
ObjectgetObjectInstance(Object refObj, Name name, Context nameCtx, Hashtable env)
ReferencegetReference()
Constructs a new reference to JDOManager being its own factory.
booleanisAutoStore()
Return if the next database instance will be set to autoStore.
static voidloadConfiguration(String name, String engine, DataSource datasource, Mapping mapping, TransactionManager txManager)
Initialize the JDOManager configuration with given name, engine, datasource, transaction demarcation and mapping.
static voidloadConfiguration(JdoConf jdoConf, EntityResolver resolver, ClassLoader loader, String baseURI)
Load the JDOManager configuration from the specified in-memory JdoConf.
static voidloadConfiguration(JdoConf jdoConf, ClassLoader loader, String baseURI)
Load the JDOManager configuration from the specified in-memory JdoConf.
static voidloadConfiguration(JdoConf jdoConf, String baseURI)
Load the JDOManager configuration from the specified in-memory JdoConf.
static voidloadConfiguration(InputSource source, EntityResolver resolver, ClassLoader loader)
Load the JDOManager configuration from the specified input source using a custom class loader.
static voidloadConfiguration(String url, ClassLoader loader)
Load the JDOManager configuration from the specified location using a custom class loader.
static voidloadConfiguration(String url)
Load the JDOManager configuration from the specified location.
voidsetAutoStore(boolean autoStore)
Sets autoStore mode.
voidsetCallbackInterceptor(CallbackInterceptor callback)
Overrides the default callback interceptor by a custom interceptor for this database source.
voidsetDatabasePooling(boolean pool)
Enable/disable database pooling.
voidsetDescription(String description)
Sets the description of this database.
voidsetInstanceFactory(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.
voidsetLockTimeout(int seconds)
Sets the lock timeout for this database.

Field Detail

DEFAULT_DESCRIPTION

public static final String DEFAULT_DESCRIPTION
Default description.

DEFAULT_LOCK_TIMEOUT

public static final int DEFAULT_LOCK_TIMEOUT
The default lock timeout (specified in seconds).

Method Detail

close

public void close()
Lyfe-cycle methods to close JDOManager instance and initiate resource cleanup.

createInstance

public static JDOManager createInstance(String databaseName)
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 occured trying to load the mapping from JDOManager configuration file.

getCallbackInterceptor

public CallbackInterceptor getCallbackInterceptor()
Returns the callback interceptor.

Returns: The currently used CallbackInterceptor or null if not overriden.

getClassLoader

public ClassLoader getClassLoader()
Returns the application classloader.

Returns: The currently used ClassLoader or null if default is used.

getConfiguration

public 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.

getConnectionFactory

public ConnectionFactory getConnectionFactory()
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()
Opens and returns a connection to the database. If no configuration exists for the named database a DatabaseNotFoundException is thrown.

Returns: An open connection to the database.

Throws: PersistenceException Database access failed.

getDatabaseName

public String getDatabaseName()
Returns the name of this database.

The standard name for this property is databaseName.

Returns: The name of this database

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: JDOManager

getDescription

public String getDescription()
Returns the description of this database.

The standard name for this property is description.

Returns: The description of this database

getEntityResolver

public EntityResolver getEntityResolver()
Returns the entity resolver.

Returns: The EntityResolver currently in use.

getInstanceFactory

public InstanceFactory getInstanceFactory()
Returns the instance factory.

Returns: The currently used InstanceFactoryor null if not overriden.

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

getObjectInstance

public Object getObjectInstance(Object refObj, Name name, Context nameCtx, Hashtable env)
{@inheritDoc }

See Also: javax.naming.spi.ObjectFactory

getReference

public Reference getReference()
Constructs a new reference to JDOManager being its own factory.

Returns: A new Reference to JDOManager.

See Also: javax.naming.Reference javax.naming.spi.ObjectFactory

isAutoStore

public boolean isAutoStore()
Return if the next database instance will be set to autoStore.

Returns: True if autoStore is enabled.

loadConfiguration

public static void loadConfiguration(String name, String engine, DataSource datasource, Mapping mapping, TransactionManager txManager)
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, EntityResolver resolver, ClassLoader loader, String baseURI)
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, ClassLoader loader, String baseURI)
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, String baseURI)
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(InputSource source, EntityResolver resolver, ClassLoader loader)
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(String url, ClassLoader loader)
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(String url)
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.

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.

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

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 JDOManager. 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 JDOManager.

Parameters: pool true to enable database pooling

setDescription

public void setDescription(String description)
Sets the description of this database.

The standard name for this property is description.

Parameters: description The description of this database

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

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

Intalio Inc. (C) 1999-2006. All rights reserved http://www.intalio.com