org.exolab.castor.jdo

Class JDO

public final class JDO extends Object implements DataObjects, Referenceable, ObjectFactory, Serializable

Deprecated: JDO has been replaced by JDOManager.

Implementation of the JDO engine used for obtaining database connection. A JDO object is constructed with the name of a database and other properties, and JDO is used to obtain a new database connection. Any number of database connections can be obtained from the same JDO object.

The database configuration can be loaded using one of the loadConfiguration methods. Alternatively, setConfiguration can be used to specify the URL of a database configuration file. The configuration will be loaded only once.

For example:

 // load the database configuration
 JDO.loadConfiguration( "database.xml" );

 ...

 JDO      jdo;
 Database db;

 // construct a new JDO for the database 'mydb'
 jdo = new JDO( "mydb" );
 // open a connection to the database
 db = jdo.getDatabase();
 
Or,
 JDO      jdo;
 Database db;

 // construct a new JDO for the database 'mydb'
 jdo = new JDO( "mydb" );
 // specify the database configuration
 jdo.setConfiguration( "database.xml" );
 // open a connection to the database
 db = jdo.getDatabase();
 

Version: $Revision: 6216 $ $Date: 2006-04-12 15:13:08 -0600 (Wed, 12 Apr 2006) $

Author: Assaf Arkin Bruce Snyder

Field Summary
static intDEFAULT_LOCK_TIMEOUT
The default lock timeout for this database is 10 seconds.
Constructor Summary
JDO()
Constructs a new JDO database factory.
JDO(String name)
Constructs a new JDO database factory for databases with the given name.
Method Summary
ClassLoadergetClassLoader()
Returns the application classloader.
StringgetConfiguration()
Return the URL of the database configuration file.
DatabasegetDatabase()
Opens and returns a connection to the database.
StringgetDatabaseName()
Returns the name of this database.
booleangetDatabasePooling()
Indicates if jdo database pooling is enable or not.
StringgetDescription()
Returns the description of this database.
EntityResolvergetEntityResolver()
Returns the entity resolver.
intgetLockTimeout()
Returns the lock timeout for this database.
LogInterceptorgetLogInterceptor()
Returns the log interceptor for this database source.
ObjectgetObjectInstance(Object refObj, Name name, Context nameCtx, Hashtable env)
{@inheritDoc } Creates an instance of JDO from a JNDI reference.
ReferencegetReference()
Creates a JNDI reference from the current JDO instance, to be bound to a JNDI tree.
booleanisAutoStore()
Return if the next database instance will be set to autoStore.
static voidloadConfiguration(String url)
Load database configuration from the specified URL.
static voidloadConfiguration(String url, ClassLoader loader)
Load database configuration from the specified URL.
static voidloadConfiguration(InputSource source, EntityResolver resolver, ClassLoader loader)
Load database configuration from the specified input source.
voidsetAutoStore(boolean autoStore)
Sets autoStore mode.
voidsetCallbackInterceptor(CallbackInterceptor callback)
Overrides the default callback interceptor by a custom interceptor for this database source.
voidsetClassLoader(ClassLoader classLoader)
Sets the application class loader.
voidsetConfiguration(String url)
Sets the URL of the database configuration file.
voidsetConfiguration(JdoConf jdoConfiguration)
Provides JDO with a JDO configuration file.
voidsetDatabaseName(String name)
Sets the name of this database.
voidsetDatabasePooling(boolean pool)
Enable/disable jdo Database pooling.
voidsetDescription(String description)
Sets the description of this database.
voidsetEntityResolver(EntityResolver entityResolver)
Sets the entity resolver.
voidsetInstanceFactory(InstanceFactory factory)
Overrides the default instance factory by a custom one to be used by Castor to obtaining an instance of data object when it is needed during loading.
voidsetLockTimeout(int seconds)
Sets the lock timeout for this database.
voidsetLogInterceptor(LogInterceptor logInterceptor)
Sets the log interceptor for this database source.
voidsetLogWriter(PrintWriter logWriter)
Returns the log writer for this database source.

Field Detail

DEFAULT_LOCK_TIMEOUT

public static final int DEFAULT_LOCK_TIMEOUT
The default lock timeout for this database is 10 seconds.

Constructor Detail

JDO

public JDO()
Constructs a new JDO database factory. Must call JDO before calling JDO.

JDO

public JDO(String name)
Constructs a new JDO database factory for databases with the given name.

Parameters: name The database name

Method Detail

getClassLoader

public ClassLoader getClassLoader()
Returns the application classloader.

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

getConfiguration

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

getDatabase

public Database getDatabase()
Opens and returns a connection to the database. Throws an DatabaseNotFoundException if the database named was not set in the constructor or with a call to JDO, or if no database configuration exists for the named database.

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 jdo database pooling is enable or not.

Experimental maybe removed in the further release

Returns: true if database pooling is enable.

See Also: JDO

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.

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

getLogInterceptor

public LogInterceptor getLogInterceptor()

Deprecated: There is no need for this method due to the implementation of Log4J which is controlled via the log4j.properties file.

Returns the log interceptor for this database source.

Returns: The log interceptor, null if disabled

getObjectInstance

public Object getObjectInstance(Object refObj, Name name, Context nameCtx, Hashtable env)
{@inheritDoc } Creates an instance of JDO from a JNDI reference.

See Also: javax.naming.spi.ObjectFactory

getReference

public Reference getReference()
Creates a JNDI reference from the current JDO instance, to be bound to a JNDI tree.

Returns: valid A JNDI Reference.

Throws: NamingException If the Reference cannot be created.

See Also: javax.naming.Referenceable#getReference()

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 url)
Load database configuration from the specified URL. url must point to a JDO configuration file describing the database name, connection factory and mappings.

Parameters: url The JDO configuration file

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 database configuration from the specified URL. url must point to a JDO configuration file describing the database name, connection factory and mappings. loader is optional, if null the default class loader is used.

Parameters: url The JDO configuration file 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(InputSource source, EntityResolver resolver, ClassLoader loader)
Load database configuration from the specified input source. source must point to a JDO configuration file describing the database* name, connection factory and mappings. resolver can be used to resolve cached entities, e.g. for external mapping documents. loader is optional, if null the default class loader is used.

Parameters: source The JDO configuration file resolver An optional entity resolver 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

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 to data object that implements the org.exolab.castor.jdo.Persistent interface.

Parameters: callback The callback interceptor, null if disabled

setClassLoader

public void setClassLoader(ClassLoader classLoader)
Sets the application class loader. This method should be used with application servers that use multiple class loaders. The default value is "null". It means that application classes are loaded through Class.forName(className).

Examples:

jdo.setClassLoader(getClass().getClassLoader());

jdo.setClassLoader(Thread.currentThread().getContextClassLoader());

Parameters: classLoader New ClassLoader to be used or null to use the default.

setConfiguration

public void setConfiguration(String url)
Sets the URL of the database configuration file. If the URL is specified, the first attempt to load a database of this type will use the specified configuration file. If the URL is not specified, use one of the loadConfiguration methods instead.

The standard name for this property is configuration.

Parameters: url The URL of the database configuration file

setConfiguration

public void setConfiguration(JdoConf jdoConfiguration)
Provides JDO with a JDO configuration file.

Parameters: jdoConfiguration A JDO configuration instance.

setDatabaseName

public void setDatabaseName(String name)
Sets the name of this database. This attribute is required in order to identify which database to open.

The standard name for this property is databaseName.

Parameters: name The name of this database

setDatabasePooling

public void setDatabasePooling(boolean pool)
Enable/disable jdo Database pooling. This option only affects JDO if _transactionManager is set and a transaction is associated with the thread that call JDO. If jdo Database pooling is enabled, JDO 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.

Method should be called before the invocation of JDO.

Experimental maybe removed in the future releases

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

setEntityResolver

public void setEntityResolver(EntityResolver entityResolver)
Sets the entity resolver. The resolver can be used to resolve cached entities, e.g. for external mapping documents. Note, that you cannot create two Database instances that differ only in a resolver.

Parameters: entityResolver New EntityResolver to be used.

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 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; if instance factory is not override, and class loader is set, loader.loadClass( className ).newInstance() will be used to create a new instance.

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

setLogInterceptor

public void setLogInterceptor(LogInterceptor logInterceptor)

Deprecated: There is no need for this method due to the implementation of Log4J which is controlled via the log4j.properties file.

Sets the log interceptor for this database source.

The interceptor is a callback to to which all logging and tracing messages are sent.

Parameters: logInterceptor The log interceptor, null if disabled

setLogWriter

public void setLogWriter(PrintWriter logWriter)

Deprecated: There is no need for this method due to the implementation of Log4J which is controlled via the log4j.properties file.

Returns the log writer for this database source.

The log writer is a character output stream to which all logging and tracing messages will be printed.

Parameters: logWriter A PrintWriter instance.

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