ozone API

org.ozoneDB
Class ExternalDatabase

java.lang.Object
  extended byorg.ozoneDB.AbstractDatabase
      extended byorg.ozoneDB.ExternalDatabase
All Implemented Interfaces:
OzoneInterface
Direct Known Subclasses:
ClientCacheDatabase, LocalDatabase, RemoteDatabase

public abstract class ExternalDatabase
extends org.ozoneDB.AbstractDatabase

Base class for implementations of the OzoneInterface which are used from a client application to access an ozone.

Each thread is associated with a server connection. This connection is used if the thread is not associated with a transaction. Otherwise the connection of the transaction is used. So in case the thread has *joined* a transaction it does not use its own connection but the connection of the transaction. The prepare/commit/abort methods don't need to be called from the thread that is joined to the transaction.

Impl. note: The OzoneInterface methods don't need to be synchronized any longer because each threads has its own connection.

Version:
$Revision: 1.21 $Date: 2003/11/07 21:34:21 $
Author:
SMB, Medium.net
See Also:
OzoneInterface

Field Summary
static int DefaultAccessRight
           
static java.lang.String PROP_DEBUG
           
static java.lang.String PROP_DIR
           
static java.lang.String PROP_HOST
           
static java.lang.String PROP_PASSWD
           
static java.lang.String PROP_PORT
           
static java.lang.String PROP_USER
           
 
Fields inherited from interface org.ozoneDB.OzoneInterface
AllLock, AllRead, GroupLock, GroupRead, Private, Public
 
Constructor Summary
ExternalDatabase()
           
 
Method Summary
 org.ozoneDB.core.admin.Admin admin()
          Return the administration object for this database.
 void beginTX(AbstractTransaction tx)
          This method is never directly called from the client code.
 void checkpointTX(AbstractTransaction tx)
          This method is never directly called from the client code.
 void close()
          Close this database.
 void commitTX(AbstractTransaction tx, boolean onePhase)
          This method is never directly called from the client code.
 OzoneProxy copyObject(OzoneRemote obj)
          Copy an object.
 OzoneProxy createObject(java.lang.Class type)
          Creates a database object of the specified class without a name and with default permissions.
 OzoneProxy createObject(java.lang.Class type, java.lang.Class[] sig, java.lang.Object[] args)
          Creates an object by calling the constructor with the specified signature with the specified parameters and default permissions.
 OzoneProxy createObject(java.lang.Class type, int access)
          Creates a database object of the specified class without a name and with the specified access rights.
 OzoneProxy createObject(java.lang.Class type, int access, java.lang.String objName)
          Creates a database object of the specified class with the specified name and the specified access rights.
 OzoneProxy createObject(java.lang.Class type, int access, java.lang.String objName, java.lang.Class[] sig, java.lang.Object[] args)
          Creates an object by calling the constructor with the specified signature with the specified parameters.
 OzoneProxy createObject(java.lang.String className)
          Creates a database object of the specified class without a name and with default permissions.
 OzoneProxy createObject(java.lang.String className, int access)
          Creates a database object of the specified class without a name and with the specified access rights.
 OzoneProxy createObject(java.lang.String className, int access, java.lang.String objName)
          Creates a database object of the specified class with the specified name and the specified access rights.
 OzoneProxy createObject(java.lang.String className, int access, java.lang.String name, java.lang.String sig, java.lang.Object[] args)
          Creates an object by calling the constructor with the specified signature with the specified parameters.
 OzoneProxy createObject(java.lang.String className, java.lang.String sig, java.lang.Object[] args)
          Creates an object by calling the constructor with the specified signature with the specified parameters and default permissions.
 ExternalTransaction currentExternalTransaction()
          Obtain the ExternalTransaction that is assocaited to the caller's thread or null, if there is no such transaction.
 AbstractTransaction currentTransaction()
          Obtain the transaction that is assocaited to the caller's thread or null, if there is no such transaction.
 void deleteObject(OzoneRemote obj)
          Deletes the specified database object.
 OzoneCompatible fetch(OzoneProxy rObj, int lockLevel)
          Returns the actual target of the given proxy if the actual implementation is able to do so.
static ExternalDatabase forThread(java.lang.Thread _thread)
          Static method to find a database connection that has an associated transaction that has been joined by the given thread.
 int getStatusTX(AbstractTransaction tx)
          Obtain the _internal_ server status of this transaction.
 javax.transaction.xa.XAResource getXAResource()
          Return a new XAResource for this database connection.
 java.lang.Object invoke(OzoneProxy rObj, int methodIndex, java.lang.Object[] args, int lockLevel)
           
 java.lang.Object invoke(OzoneProxy rObj, java.lang.String methodName, java.lang.String sig, java.lang.Object[] args, int lockLevel)
          Invokes a method on the specified object.
 boolean isOpen()
           
 void joinTX(AbstractTransaction tx)
          This method is never directly called from the client code.
 boolean leaveTX(AbstractTransaction tx)
          This method is never directly called from the client code.
 void nameObject(OzoneRemote obj, java.lang.String name)
          Assigns the specified object with the specified name.
 ExternalTransaction newTransaction()
          Create a new transaction.
 void notifyProxyDeath(OzoneProxy proxy)
          Internal method.
 OzoneProxy objectForHandle(java.lang.String handle)
          Returns the object for the specified handle or null if there is no such object.
 OzoneProxy objectForName(java.lang.String name)
          Returns the object for the specifies name or null if there is no such object.
 java.lang.String[] objectNames()
          fetch an array of all named objects
static ExternalDatabase openDatabase(java.lang.String _url)
           
static ExternalDatabase openDatabase(java.lang.String _url, java.lang.String _username, java.lang.String _passwd)
          Factory method that creates a new database object.
 void prepareTX(AbstractTransaction tx)
          This method is never directly called from the client code.
 void reloadClasses()
          Force the database server to reload all classes which extend OzoneObject.
 void rollbackTX(AbstractTransaction tx)
          This method is never directly called from the client code.
 void xmlForObject(OzoneRemote rObj, org.xml.sax.ContentHandler ch)
          Converts the specified object into XML.
 org.w3c.dom.Node xmlForObject(OzoneRemote rObj, org.w3c.dom.Document domFactory)
          Convert the specified object into XML.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

PROP_HOST

public static final java.lang.String PROP_HOST
See Also:
Constant Field Values

PROP_PORT

public static final java.lang.String PROP_PORT
See Also:
Constant Field Values

PROP_DIR

public static final java.lang.String PROP_DIR
See Also:
Constant Field Values

PROP_USER

public static final java.lang.String PROP_USER
See Also:
Constant Field Values

PROP_PASSWD

public static final java.lang.String PROP_PASSWD
See Also:
Constant Field Values

PROP_DEBUG

public static final java.lang.String PROP_DEBUG
See Also:
Constant Field Values

DefaultAccessRight

public static final int DefaultAccessRight
See Also:
Constant Field Values
Constructor Detail

ExternalDatabase

public ExternalDatabase()
Method Detail

forThread

public static ExternalDatabase forThread(java.lang.Thread _thread)
Static method to find a database connection that has an associated transaction that has been joined by the given thread. Used by proxy constructors to determine its database. This method returns the first database that was found.

Parameters:
_thread - The thread for which to find the corresponding database.
Returns:
The database for the given thread.

getXAResource

public final javax.transaction.xa.XAResource getXAResource()
Return a new XAResource for this database connection.

Returns:
new XAResource.

newTransaction

public ExternalTransaction newTransaction()
Create a new transaction. Before using this transaction it must be started.

Returns:
The newly created transaction.

currentExternalTransaction

public ExternalTransaction currentExternalTransaction()
Obtain the ExternalTransaction that is assocaited to the caller's thread or null, if there is no such transaction. This does not necessarily mean that there is no transaction associated to this thread at all. For example there might be an XA transaction.

Returns:
The transaction that is associated to the caller's thread.
See Also:
currentTransaction()

currentTransaction

public AbstractTransaction currentTransaction()
Obtain the transaction that is assocaited to the caller's thread or null, if there is no such transaction. The transaction might be an instance of any subclass of AbstractTransaction, which includes also non-user transactions like org.ozoneDB.xa.XATransaction.

Returns:
The transaction that is associated to the caller's thread.
See Also:
currentExternalTransaction()

beginTX

public void beginTX(AbstractTransaction tx)
             throws TransactionException,
                    java.io.IOException
This method is never directly called from the client code.

Throws:
TransactionException
java.io.IOException

joinTX

public void joinTX(AbstractTransaction tx)
            throws TransactionException
This method is never directly called from the client code.

Throws:
TransactionException

leaveTX

public boolean leaveTX(AbstractTransaction tx)
This method is never directly called from the client code.


checkpointTX

public void checkpointTX(AbstractTransaction tx)
                  throws TransactionException,
                         java.io.IOException
This method is never directly called from the client code.

Throws:
TransactionException
java.io.IOException

prepareTX

public void prepareTX(AbstractTransaction tx)
               throws TransactionException,
                      java.io.IOException
This method is never directly called from the client code.

Throws:
TransactionException
java.io.IOException

commitTX

public void commitTX(AbstractTransaction tx,
                     boolean onePhase)
              throws TransactionException,
                     java.io.IOException
This method is never directly called from the client code.

Throws:
TransactionException
java.io.IOException

rollbackTX

public void rollbackTX(AbstractTransaction tx)
                throws TransactionException,
                       java.io.IOException
This method is never directly called from the client code.

Throws:
TransactionException
java.io.IOException

getStatusTX

public final int getStatusTX(AbstractTransaction tx)
                      throws TransactionException,
                             java.io.IOException
Obtain the _internal_ server status of this transaction.

Returns:
Status of the transaction. Defined in Transaction.

This method is never directly called from the client code.

Throws:
TransactionException
java.io.IOException

isOpen

public boolean isOpen()
               throws java.lang.Exception
Throws:
java.lang.Exception

openDatabase

public static ExternalDatabase openDatabase(java.lang.String _url,
                                            java.lang.String _username,
                                            java.lang.String _passwd)
                                     throws java.lang.Exception
Factory method that creates a new database object. The actual type of the database object (ExternalDatabase or LocalDatabase) depends on the specified database URL. The returned database connection is already open.

Throws:
java.lang.Exception

openDatabase

public static ExternalDatabase openDatabase(java.lang.String _url)
                                     throws java.lang.Exception
Parameters:
_url - The URL of the database (ozonedb:remote://host:port?user=&password= or ozonedb:local:///datadir?user=&password=)
Throws:
java.lang.Exception

close

public void close()
           throws java.lang.Exception
Close this database.

Throws:
java.lang.Exception

reloadClasses

public void reloadClasses()
                   throws java.lang.Exception
Description copied from interface: OzoneInterface
Force the database server to reload all classes which extend OzoneObject. This is particularly useful while testing new classes.

Throws:
java.lang.Exception - To signal an implementation specific problem, such as IOException

createObject

public OzoneProxy createObject(java.lang.String className,
                               int access,
                               java.lang.String name,
                               java.lang.String sig,
                               java.lang.Object[] args)
                        throws java.lang.RuntimeException,
                               OzoneObjectException
Description copied from interface: OzoneInterface
Creates an object by calling the constructor with the specified signature with the specified parameters. Generated proxy objects use this method.

Parameters:
className - fully qualified name of the class
access - access right (ORed)
name - name of the object (optional
sig - The signature string of the constructor.
args - The parameter that are passed to the constructor.
Returns:
proxy A OzoneProxy object for the newly created object.
Throws:
java.lang.RuntimeException - To signal an implementation specific problem, such as IOException
OzoneObjectException

deleteObject

public void deleteObject(OzoneRemote obj)
                  throws java.lang.RuntimeException,
                         OzoneObjectException
Description copied from interface: OzoneInterface
Deletes the specified database object. The specified object is an instance of OzoneProxy which you may have created by createObject().

Parameters:
obj -
Throws:
java.lang.RuntimeException - To signal an implementation specific problem, such as IOException
OzoneObjectException

copyObject

public OzoneProxy copyObject(OzoneRemote obj)
                      throws java.lang.Exception
Description copied from interface: OzoneInterface
Copy an object. The new objects gets its own object ID. The specified object is an instance of OzoneProxy which you may have created by createObject().

Parameters:
obj -
Returns:
proxy for the newly created object
Throws:
java.lang.Exception - To signal an implementation specific problem, such as IOException

nameObject

public void nameObject(OzoneRemote obj,
                       java.lang.String name)
                throws java.lang.Exception
Description copied from interface: OzoneInterface
Assigns the specified object with the specified name. This can also be done at object creation time. The specified object is an instance of OzoneProxy which you may have created by createObject().

Parameters:
obj -
name -
Throws:
java.lang.Exception - To signal an implementation specific problem, such as IOException

objectForName

public OzoneProxy objectForName(java.lang.String name)
                         throws java.lang.Exception
Description copied from interface: OzoneInterface
Returns the object for the specifies name or null if there is no such object.

Parameters:
name - The name name of the object.
Returns:
A proxy object for the found object or null.
Throws:
java.lang.Exception - To signal an implementation specific problem, such as IOException

objectNames

public java.lang.String[] objectNames()
                               throws java.lang.Exception
Description copied from interface: OzoneInterface
fetch an array of all named objects

Returns:
a String array of all named objects
Throws:
java.lang.Exception - To signal an implementation specific problem, such as IOException

objectForHandle

public OzoneProxy objectForHandle(java.lang.String handle)
                           throws java.lang.Exception
Description copied from interface: OzoneInterface
Returns the object for the specified handle or null if there is no such object.

Parameters:
handle - The handle of the object.
Returns:
A proxy object for the found object or null.
Throws:
java.lang.Exception - To signal an implementation specific problem, such as IOException

invoke

public java.lang.Object invoke(OzoneProxy rObj,
                               java.lang.String methodName,
                               java.lang.String sig,
                               java.lang.Object[] args,
                               int lockLevel)
                        throws java.lang.Exception
Description copied from interface: OzoneInterface
Invokes a method on the specified object. This method is called by proxy objects to route the call to the corresponding database object. A client will never call this method explicitly.

Parameters:
rObj - OzoneProxy on which to call the method
methodName -
sig - signature of the method as String
args - array of arguments
lockLevel - specifies wether this method changes the state of the object
Returns:
regular object or proxy
Throws:
java.lang.Exception - To signal an implementation specific problem, such as IOException

invoke

public java.lang.Object invoke(OzoneProxy rObj,
                               int methodIndex,
                               java.lang.Object[] args,
                               int lockLevel)
                        throws java.lang.Exception
Throws:
java.lang.Exception

fetch

public OzoneCompatible fetch(OzoneProxy rObj,
                             int lockLevel)
                      throws java.lang.Exception,
                             ObjectNotFoundException,
                             java.io.IOException,
                             java.lang.ClassNotFoundException,
                             TransactionException,
                             org.ozoneDB.core.TransactionError
Description copied from interface: OzoneInterface
Returns the actual target of the given proxy if the actual implementation is able to do so. A client will never call this method explicitly.

Throws:
java.lang.Exception
ObjectNotFoundException
java.io.IOException
java.lang.ClassNotFoundException
TransactionException
org.ozoneDB.core.TransactionError

xmlForObject

public org.w3c.dom.Node xmlForObject(OzoneRemote rObj,
                                     org.w3c.dom.Document domFactory)
                              throws java.lang.Exception
Description copied from interface: OzoneInterface
Convert the specified object into XML. This method returns the generated XML data as DOM tree. For performance reasons you should try to use OzoneInterface.xmlForObject(OzoneRemote, ContentHandler), which returns SAX events, instead of DOM. See the doc directory of ozone for a detailed description (XML Schema) of the XML output of this method.

Parameters:
rObj - The database object to be converted.
domFactory - The factory for creating DOM nodes.
Returns:
The DOM node representing the converted object.
Throws:
java.lang.Exception

xmlForObject

public void xmlForObject(OzoneRemote rObj,
                         org.xml.sax.ContentHandler ch)
                  throws java.lang.Exception
Description copied from interface: OzoneInterface
Converts the specified object into XML. This method returns the generated XML data as SAX events. See the doc directory of ozone for a detailed description (XML Schema) of the XML output of this method.

Parameters:
rObj - The database object to be converted.
ch - The SAX ContentHandler to which the result is sent.
Throws:
java.lang.Exception

admin

public org.ozoneDB.core.admin.Admin admin()
                                   throws java.lang.Exception
Return the administration object for this database.

Returns:
The admin object for this database;
Throws:
java.lang.Exception

notifyProxyDeath

public void notifyProxyDeath(OzoneProxy proxy)
Internal method. This method is called by OzoneProxys when they are dying (during finalize()). This is required, as the database may track the references the database client has to objects within the database in order to properly support garbage collection. If this method is called from anyone else than from the OzoneProxy.finalize()-Method, data loss may occur!

Parameters:
proxy - the OzoneProxy object which is dying. It may call this method exaclty once.

createObject

public OzoneProxy createObject(java.lang.String className)
                        throws java.lang.RuntimeException,
                               OzoneRemoteException
Description copied from interface: OzoneInterface
Creates a database object of the specified class without a name and with default permissions.

Specified by:
createObject in interface OzoneInterface
Parameters:
className - The fully qualified name of the class.
Returns:
A proxy object for the newly created object.
Throws:
java.lang.RuntimeException - To signal an implementation specific problem, such as IOException
OzoneRemoteException - (or one of its sub-classes) to signal a ozone related problem.

createObject

public OzoneProxy createObject(java.lang.String className,
                               int access)
                        throws java.lang.RuntimeException,
                               OzoneRemoteException
Description copied from interface: OzoneInterface
Creates a database object of the specified class without a name and with the specified access rights.

Specified by:
createObject in interface OzoneInterface
Parameters:
className - The fully qualified name of the class.
access - The access rights (ORed).
Returns:
proxy A proxy object for the newly created database object.
Throws:
OzoneRemoteException - (or one of its sub-classes) to signal a ozone related problem.
java.lang.RuntimeException - To signal an implementation specific problem, such as IOException

createObject

public OzoneProxy createObject(java.lang.String className,
                               int access,
                               java.lang.String objName)
                        throws java.lang.RuntimeException,
                               OzoneRemoteException
Description copied from interface: OzoneInterface
Creates a database object of the specified class with the specified name and the specified access rights.

Specified by:
createObject in interface OzoneInterface
Parameters:
className - The fully qualified name of the class.
access - The access right. (ORed)
objName - The name of the object. (optional)
Returns:
A proxy object for the newly created object.
Throws:
OzoneRemoteException - (or one of its sub-classes) to signal a ozone related problem.
java.lang.RuntimeException - To signal an implementation specific problem, such as IOException

createObject

public OzoneProxy createObject(java.lang.String className,
                               java.lang.String sig,
                               java.lang.Object[] args)
                        throws java.lang.RuntimeException,
                               OzoneRemoteException
Description copied from interface: OzoneInterface
Creates an object by calling the constructor with the specified signature with the specified parameters and default permissions.

Specified by:
createObject in interface OzoneInterface
Parameters:
className - fully qualified name of the class
sig - The signature string of the constructor.
args - The parameter that are passed to the constructor.
Returns:
proxy A OzoneProxy object for the newly created object.
Throws:
java.lang.RuntimeException - To signal an implementation specific problem, such as IOException
OzoneRemoteException - (or one of its sub-classes) to signal a ozone related problem.

createObject

public OzoneProxy createObject(java.lang.Class type)
                        throws java.lang.RuntimeException,
                               OzoneRemoteException
Description copied from interface: OzoneInterface
Creates a database object of the specified class without a name and with default permissions.

Specified by:
createObject in interface OzoneInterface
Parameters:
type - the type of the object to be created
Returns:
A proxy object for the newly created object.
Throws:
OzoneRemoteException - (or one of its sub-classes) to signal a ozone related problem.
java.lang.RuntimeException - To signal an implementation specific problem, such as IOException

createObject

public OzoneProxy createObject(java.lang.Class type,
                               int access)
                        throws java.lang.RuntimeException,
                               OzoneRemoteException
Description copied from interface: OzoneInterface
Creates a database object of the specified class without a name and with the specified access rights.

Specified by:
createObject in interface OzoneInterface
Parameters:
type - the type of the object to be created
access - The access rights (ORed).
Returns:
proxy A proxy object for the newly created database object.
Throws:
java.lang.RuntimeException - To signal an implementation specific problem, such as IOException
OzoneRemoteException - (or one of its sub-classes) to signal a ozone related problem.

createObject

public OzoneProxy createObject(java.lang.Class type,
                               int access,
                               java.lang.String objName)
                        throws java.lang.RuntimeException,
                               OzoneRemoteException
Description copied from interface: OzoneInterface
Creates a database object of the specified class with the specified name and the specified access rights.

Specified by:
createObject in interface OzoneInterface
Parameters:
type - the type of the object to be created
access - The access right. (ORed)
objName - The name of the object. (optional)
Returns:
A proxy object for the newly created object.
Throws:
java.lang.RuntimeException - To signal an implementation specific problem, such as IOException
OzoneRemoteException - (or one of its sub-classes) to signal a ozone related problem.

createObject

public OzoneProxy createObject(java.lang.Class type,
                               int access,
                               java.lang.String objName,
                               java.lang.Class[] sig,
                               java.lang.Object[] args)
                        throws java.lang.RuntimeException,
                               OzoneRemoteException
Description copied from interface: OzoneInterface
Creates an object by calling the constructor with the specified signature with the specified parameters. Generated proxy objects use this method.

Specified by:
createObject in interface OzoneInterface
Parameters:
type - the type of the object to be created
access - access right (ORed)
objName - name of the object (optional
sig - An array of signature params for the constructor in question.
args - The parameter that are passed to the constructor.
Returns:
proxy A OzoneProxy object for the newly created object.
Throws:
java.lang.RuntimeException - To signal an implementation specific problem, such as IOException
OzoneRemoteException - (or one of its sub-classes) to signal a ozone related problem.

createObject

public OzoneProxy createObject(java.lang.Class type,
                               java.lang.Class[] sig,
                               java.lang.Object[] args)
                        throws java.lang.RuntimeException,
                               OzoneRemoteException
Description copied from interface: OzoneInterface
Creates an object by calling the constructor with the specified signature with the specified parameters and default permissions.

Specified by:
createObject in interface OzoneInterface
Parameters:
type - the type of the object to be created
sig - An array of signature params for the constructor in question.
args - The parameter that are passed to the constructor.
Returns:
proxy A OzoneProxy object for the newly created object.
Throws:
OzoneRemoteException - (or one of its sub-classes) to signal a ozone related problem.
java.lang.RuntimeException - To signal an implementation specific problem, such as IOException

ozone API

Copyright (C) The Ozone Database Project - www.ozone-db.org. All rights reserved.