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) {
...
}
close
public void close()
Lyfe-cycle methods to close JDOManager instance and initiate resource cleanup.
createInstance
public static JDOManager createInstance(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.
databaseName
- Database name as configured in the JDOManager
configuration file.
MappingException
- The mapping file is invalid, or any error
occured trying to load the mapping from JDOManager configuration
file.
disposeInstance
public static void disposeInstance(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().
databaseName
- Database name as configured in the JDOManager
configuration file.
getCallbackInterceptor
public CallbackInterceptor getCallbackInterceptor()
Returns the callback interceptor.
- The currently used CallbackInterceptor or null if not overriden.
getClassLoader
public ClassLoader getClassLoader()
Returns the application classloader.
- 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.
- The URL of the database configuration file as InputSource.
getConnectionFactory
public ConnectionFactory getConnectionFactory()
throws MappingException
Returns the ConnectionFactory for this JDOManager instance.
- The connection factory used by this JDOManager instance.
getDatabaseName
public String getDatabaseName()
Returns the name of this database.
The standard name for this property is
databaseName.
- getDatabaseName in interface DataObjects
- 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.
- True if pooling is enabled for this Database instance.
getDescription
public String getDescription()
Returns the description of this database.
The standard name for this property is
description.
- getDescription in interface DataObjects
- The description of this database
getEntityResolver
public EntityResolver getEntityResolver()
Returns the entity resolver.
- The EntityResolver currently in use.
getInstanceFactory
public InstanceFactory getInstanceFactory()
Returns the instance factory.
- 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.
- The lock timeout, specified in seconds
getObjectInstance
public Object getObjectInstance(Object refObj,
Name name,
Context nameCtx,
Hashtable env)
throws NamingException
javax.naming.spi.ObjectFactory
getReference
public Reference getReference()
Constructs a new reference to JDOManager being its own factory.
- A new Reference to JDOManager.
javax.naming.Reference
, javax.naming.spi.ObjectFactory
isAutoStore
public boolean isAutoStore()
Return if the next database instance will be set to autoStore.
- True if autoStore is enabled.
loadConfiguration
public static void loadConfiguration(InputSource source,
EntityResolver resolver,
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.
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
MappingException
- The mapping file is invalid, or any error
occured trying to load the JDO configuration/mapping
loadConfiguration
public static void loadConfiguration(String url)
throws MappingException
Load the JDOManager configuration from the specified location.
url
- The location from which to load the configuration file.
MappingException
- The mapping file is invalid, or any error
occured trying to load the JDOManager configuration/mapping.
loadConfiguration
public static void loadConfiguration(String url,
ClassLoader loader)
throws MappingException
Load the JDOManager configuration from the specified location using a
custom class loader.
url
- The location from which to load the configuration file.loader
- The custom class loader to use, null for the default.
MappingException
- The mapping file is invalid, or any error
occured trying to load the JDOManager configuration/mapping.
loadConfiguration
public static void loadConfiguration(String name,
String engine,
DataSource datasource,
Mapping mapping,
TransactionManager txManager)
throws MappingException
Initialize the JDOManager configuration with given name, engine, datasource,
transaction demarcation and mapping.
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.
loadConfiguration
public static void loadConfiguration(JdoConf jdoConf,
ClassLoader loader,
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.
jdoConf
- the in-memory JdoConf.loader
- The class loader to use, null for the defaultbaseURI
- The base URL for the mapping
MappingException
- The mapping file is invalid, or any error
occured trying to load the JDO configuration/mapping
loadConfiguration
public static void loadConfiguration(JdoConf jdoConf,
EntityResolver resolver,
ClassLoader loader,
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.
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 defaultbaseURI
- The base URL for the mapping
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)
throws MappingException
Load the JDOManager configuration from the specified in-memory JdoConf.
jdoConf
- the in-memory JdoConf.baseURI
- The base URL for the mapping
MappingException
- The mapping file is invalid, or any error
occured trying to load the JDO configuration/mapping
setAutoStore
public void setAutoStore(boolean autoStore)
Sets autoStore mode.
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.
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
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()
.
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.
- setDescription in interface DataObjects
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.
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.
seconds
- The lock timeout, specified in seconds