org.exolab.castor.jdo
Class JDO

java.lang.Object
  |
  +--org.exolab.castor.jdo.JDO

public class JDO
extends java.lang.Object
implements DataObjects, javax.naming.Referenceable, javax.naming.spi.ObjectFactory, java.io.Serializable

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 getDatabase() 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(java.lang.String) method. Alternatively, setConfiguration(java.lang.String) can be used to specify the URL of a database configuration file. The configuration will 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 and specify the configuration file
 jdo = new JDO( "mydb" );
 jdo.setConfiguration( "database.xml" );
 // Open a connection to the database
 db = jdo.getDatabase();
 

Version:
$Revision: 1.18 $ $Date: 2001/02/05 18:05:34 $
Author:
Assaf Arkin
See Also:
Serialized Form

Field Summary
static int DefaultLockTimeout
          The default lock timeout for this database is 10 seconds.
 
Constructor Summary
JDO()
          Constructs a new JDO database factory.
JDO(java.lang.String name)
          Constructs a new JDO database factory for databases with the given name.
 
Method Summary
 java.lang.ClassLoader getClassLoader()
          Returns the application classloader.
 java.lang.String getConfiguration()
          Return the URL of the database configuration file.
 Database getDatabase()
          Opens and returns a connection to the database.
 java.lang.String getDatabaseName()
          Returns the name of this database.
 java.lang.String getDescription()
          Returns the description of this database.
 org.xml.sax.EntityResolver getEntityResolver()
          Returns the entity resolver.
 int getLockTimeout()
          Returns the lock timeout for this database.
 org.exolab.castor.persist.spi.LogInterceptor getLogInterceptor()
          Returns the log interceptor for this database source.
 java.lang.Object getObjectInstance(java.lang.Object refObj, javax.naming.Name name, javax.naming.Context nameCtx, java.util.Hashtable env)
           
 javax.naming.Reference getReference()
           
 java.lang.String getTransactionManager()
          Returns the JNDI name of the transaction manager.
static void loadConfiguration(org.xml.sax.InputSource source, org.xml.sax.EntityResolver resolver, java.lang.ClassLoader loader)
          Load database configuration from the specified input source.
static void loadConfiguration(java.lang.String url)
          Load database configuration from the specified URL.
static void loadConfiguration(java.lang.String url, java.lang.ClassLoader loader)
          Load database configuration from the specified URL.
 void setClassLoader(java.lang.ClassLoader classLoader)
          Sets the application class loader.
 void setConfiguration(java.lang.String url)
          Sets the URL of the database configuration file.
 void setDatabaseName(java.lang.String name)
          Sets the name of this database.
 void setDescription(java.lang.String description)
          Sets the description of this database.
 void setEntityResolver(org.xml.sax.EntityResolver entityResolver)
          Sets the entity resolver.
 void setLockTimeout(int seconds)
          Sets the lock timeout for this database.
 void setLogInterceptor(org.exolab.castor.persist.spi.LogInterceptor logInterceptor)
          Sets the log interceptor for this database source.
 void setLogWriter(java.io.PrintWriter logWriter)
          Returns the log writer for this database source.
 void setTransactionManager(java.lang.String tmName)
          Sets the JNDI name of the transaction manager.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DefaultLockTimeout

public static final int DefaultLockTimeout
The default lock timeout for this database is 10 seconds.
Constructor Detail

JDO

public JDO()
Constructs a new JDO database factory. Must call setDatabaseName(java.lang.String) before calling getDatabase().

JDO

public JDO(java.lang.String name)
Constructs a new JDO database factory for databases with the given name.
Parameters:
name - The database name
Method Detail

setLogWriter

public void setLogWriter(java.io.PrintWriter logWriter)
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.

Returns:
The log writer, null if disabled

setLogInterceptor

public void setLogInterceptor(org.exolab.castor.persist.spi.LogInterceptor logInterceptor)
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

getLogInterceptor

public org.exolab.castor.persist.spi.LogInterceptor getLogInterceptor()
Returns the log interceptor for this database source.
Returns:
The log interceptor, null if disabled

setClassLoader

public void setClassLoader(java.lang.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());


getClassLoader

public java.lang.ClassLoader getClassLoader()
Returns the application classloader.

setEntityResolver

public void setEntityResolver(org.xml.sax.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.

getEntityResolver

public org.xml.sax.EntityResolver getEntityResolver()
Returns the entity resolver.

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

setDatabaseName

public void setDatabaseName(java.lang.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

getDatabaseName

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

The standard name for this property is databaseName.

Returns:
The name of this database

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

setConfiguration

public void setConfiguration(java.lang.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(java.lang.String) methods instead.

The standard name for this property is configuration.

Parameters:
url - The URL of the database configuration file

getConfiguration

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

setTransactionManager

public void setTransactionManager(java.lang.String tmName)
Sets the JNDI name of the transaction manager. If set, JDO will look up this name through JNDI and if available register itself for synchronization and take part in a distributed transaction.

The standard name for this property is transactionManager.

Parameters:
tmName - The JNDI name of the transaction manager

getTransactionManager

public java.lang.String getTransactionManager()
Returns the JNDI name of the transaction manager.

getDatabase

public Database getDatabase()
                     throws DatabaseNotFoundException,
                            PersistenceException
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 setDatabaseName(java.lang.String), or if no database configuration exists for the named database.
Specified by:
getDatabase in interface DataObjects
Returns:
An open connection to the database
Throws:
DatabaseNotFoundException - Attempted to open a database that does not exist
PersistenceException - Database access failed

loadConfiguration

public static void loadConfiguration(java.lang.String url)
                              throws MappingException
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

loadConfiguration

public static void loadConfiguration(java.lang.String url,
                                     java.lang.ClassLoader loader)
                              throws MappingException
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

loadConfiguration

public static void loadConfiguration(org.xml.sax.InputSource source,
                                     org.xml.sax.EntityResolver resolver,
                                     java.lang.ClassLoader loader)
                              throws MappingException
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
resolve - An optional entity resolver
loader - The class loader to use, null for the default

getReference

public javax.naming.Reference getReference()
Specified by:
getReference in interface javax.naming.Referenceable

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


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