ptdb.kernel.database

Class OracleXMLDBConnection

java.lang.Object

ptdb.kernel.database.OracleXMLDBConnection

All Implemented Interfaces:

DBConnection

Direct Known Subclasses:

RebuildReferenceFile

public class OracleXMLDBConnection
extends java.lang.Object
implements DBConnection

Create and manage the actual connection to the Oracle XML database. Manage the transactions for the database.

This is a wrapper class that acts as a Facade to the Oracle Berkeley XML Database interface.

Since:

Ptolemy II 10.0

Version:

$Id$

Author:

Ashwini Bijwe, Yousef Alsaeed

Pt.AcceptedRating:

Red (abijwe)

Pt.ProposedRating:

Red (abijwe)

Field Summary

Fields

Modifier and Type	Field and Description
protected static com.sleepycat.db.Environment	_environment The environment for the Oracle Berkeley XMLDatabase that defines the parameters like cache size, locking mechanism, storing mechanism etc.
protected static java.lang.String	_environmentPath Path for the given environment.
protected boolean	_isConnectionAlive Denote whether the database connection is active or not.
protected boolean	_isTransactionActive Denote whether the database connection is active or not.
protected DBConnectionParameters	_params This object contains the parameters like path, container name etc.
protected com.sleepycat.dbxml.XmlContainer	_xmlContainer This is the Oracle Berkeley XML DB Container that is used to add and remove documents.
protected com.sleepycat.dbxml.XmlManager	_xmlManager This is the Oracle BerkeleyXML DB manager that is used to execute queries over the opened container.
protected com.sleepycat.dbxml.XmlTransaction	_xmlTransaction This is the Oracle Berkeley XML DB Transaction that is used to commit or abort certain transactions.

Constructor Summary

Constructors

Constructor and Description
OracleXMLDBConnection(DBConnectionParameters dbConnParams) Construct an instance that initializes the environment and creates a database connection based on the given parameters.

Method Summary

Modifier and Type	Method and Description
protected java.util.ArrayList<XMLDBModel>	_getDistinctModelsList(java.util.ArrayList<java.lang.String> modelNamesList) Create a list of distinct XMLDBModels from the given list that may contain duplicates.
void	abortConnection() Abort the connection and roll back the transaction Invoke in case of errors.
void	closeConnection() Commit the transaction and close the connection to the database.
void	commitConnection() Commit the transaction running over the connection.
boolean	doesModelExist(XMLDBModel model) Check if the given model already exists in the database.
java.util.ArrayList<XMLDBModel>	executeAttributeSearchTask(AttributeSearchTask task) Search models that contain the given attributes in the database.
XMLDBAttribute	executeCreateAttributeTask(CreateAttributeTask task) Execute a create attribute task which adds a new attribute to the database.
java.lang.String	executeCreateModelTask(CreateModelTask task) Execute the necessary commands to create a new model in the database according to the model specification given in the task parameter.
void	executeDeleteAttributeTask(DeleteAttributeTask task) Execute delete attribute task which deletes a given attribute from the database.
java.util.ArrayList<XMLDBModel>	executeFetchHierarchyTask(FetchHierarchyTask task) Fetch the parent model hierarchies for the given models.
java.util.ArrayList<XMLDBAttribute>	executeGetAttributesTask(GetAttributesTask task) Get the attributes defined from the database.
XMLDBModel	executeGetCompleteModelTask(GetModelTask task) Execute the get model task and return the model requested as XMLDBModel object and resolve any references in it.
java.util.List<XMLDBModel>	executeGetFirstLevelParents(GetFirstLevelParentsTask task) Execute the given task to fetch the first level parents for the given model.
java.util.List<XMLDBModel>	executeGetListOfAllModels() Retrieve and return the list of all models in the database.
XMLDBModel	executeGetModelTask(GetModelTask task) Execute the get model task and return the model requested as XMLDBModel object as it is represented in the database.
java.lang.String	executeGetReferenceStringTask(GetReferenceStringTask task) Get the model reference string for the given model name.
java.util.ArrayList<XMLDBModel>	executeGraphSearchTask(GraphSearchTask task) Search models that contain given graphical pattern in the database.
java.util.ArrayList<XMLDBModel>	executeModelNameSearchTask(ModelNameSearchTask modelNameSearchTask) Execute the model name search task.
void	executeRemoveModelsTask(RemoveModelsTask task) Execute remove models task to delete a list of models from the database.
void	executeRenameModelTask(RenameModelTask task) Execute rename model task which will change the name of the model in the database and reflect the change in the reference file.
java.lang.String	executeSaveModelTask(SaveModelTask task) Execute the necessary commands to save/update a model in the database according to the model specification given in the task parameter.
void	executeUpdateAttributeTask(UpdateAttributeTask task) Execute update attribute task to update a given attribute in the database.
void	executeUpdateModelInCache(XMLDBModel xmlDBModel) Execute the necessary commands to update the cache with the given model.
void	executeUpdateParentsToNewVersion(UpdateParentsToNewVersionTask task) Execute the given task to update the referenced version for the given parents from the old model to the new model.
static void	initializeDatabase(java.lang.String url) Create a database environment with the given configuration.
java.lang.String	toString() Provide information regarding the state of the internal variables useful for unit testing purposes.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

_environment

protected static com.sleepycat.db.Environment _environment

The environment for the Oracle Berkeley XMLDatabase that defines the parameters like cache size, locking mechanism, storing mechanism etc. required for creating a database connection.

_environmentPath

protected static java.lang.String _environmentPath

Path for the given environment.

_isConnectionAlive

protected boolean _isConnectionAlive

Denote whether the database connection is active or not.

_isTransactionActive

protected boolean _isTransactionActive

Denote whether the database connection is active or not.

_params

protected DBConnectionParameters _params

This object contains the parameters like path, container name etc. required to connect with the database.

_xmlContainer

protected com.sleepycat.dbxml.XmlContainer _xmlContainer

This is the Oracle Berkeley XML DB Container that is used to add and remove documents.

_xmlManager

protected com.sleepycat.dbxml.XmlManager _xmlManager

This is the Oracle BerkeleyXML DB manager that is used to execute queries over the opened container.

_xmlTransaction

protected com.sleepycat.dbxml.XmlTransaction _xmlTransaction

This is the Oracle Berkeley XML DB Transaction that is used to commit or abort certain transactions. This will be set only if a transaction enabled connection is requested.

Constructor Detail

OracleXMLDBConnection

public OracleXMLDBConnection(DBConnectionParameters dbConnParams)
                      throws DBConnectionException

Construct an instance that initializes the environment and creates a database connection based on the given parameters.

Parameters:

dbConnParams - Encapsulate the parameters required to create a database connection.

Throws:

DBConnectionException - If thrown while creating a connection.

Method Detail

abortConnection

public void abortConnection()
                     throws DBConnectionException

Abort the connection and roll back the transaction Invoke in case of errors.

Specified by:

abortConnection in interface DBConnection

Throws:

DBConnectionException - If thrown while aborting transaction in the database.

initializeDatabase

public static void initializeDatabase(java.lang.String url)
                               throws DBConnectionException

Create a database environment with the given configuration.

Parameters:

url - Database URL

Throws:

DBConnectionException - If thrown while creating the environment.

commitConnection

public void commitConnection()
                      throws DBConnectionException

Commit the transaction running over the connection.

Specified by:

commitConnection in interface DBConnection

Throws:

DBConnectionException - If thrown while committing transaction in the database.

closeConnection

public void closeConnection()
                     throws DBConnectionException

Commit the transaction and close the connection to the database.

If the transaction on this connection is alive/open while closing the connection, the transaction will be aborted.

Specified by:

closeConnection in interface DBConnection

Throws:

DBConnectionException - If thrown while closing database connection.

executeCreateModelTask

public java.lang.String executeCreateModelTask(CreateModelTask task)
                                        throws DBExecutionException,
                                               ModelAlreadyExistException,
                                               CircularDependencyException

Execute the necessary commands to create a new model in the database according to the model specification given in the task parameter.

Specified by:

executeCreateModelTask in interface DBConnection

Parameters:

task - The task to be completed. In this case, CreateModelTask. This will tell the DB layer to create a new model in the database.

Returns:

The Id of the newly created model in the database.

Throws:

DBExecutionException - Thrown if there is a problem executing the task.

ModelAlreadyExistException - Thrown if the model being created already exists.

CircularDependencyException - If thrown while creating reference string.

executeFetchHierarchyTask

public java.util.ArrayList<XMLDBModel> executeFetchHierarchyTask(FetchHierarchyTask task)
                                                          throws DBExecutionException

Fetch the parent model hierarchies for the given models.

Specified by:

executeFetchHierarchyTask in interface DBConnection

Parameters:

task - Task that contains the list of models.

Returns:

List of models that contain the parent hierarchies.

Throws:

DBExecutionException - If thrown while searching in the database.

executeGetListOfAllModels

public java.util.List<XMLDBModel> executeGetListOfAllModels()
                                                     throws DBExecutionException

Retrieve and return the list of all models in the database.

Specified by:

executeGetListOfAllModels in interface DBConnection

Returns:

List of models in the database.

Throws:

DBExecutionException - thrown if there is an error while reading the model list from the database.

executeGetAttributesTask

public java.util.ArrayList<XMLDBAttribute> executeGetAttributesTask(GetAttributesTask task)
                                                             throws DBExecutionException

Get the attributes defined from the database.

Specified by:

executeGetAttributesTask in interface DBConnection

Parameters:

task - The criteria to get the attribute.

Returns:

List of attributes stored in the database.

Throws:

DBExecutionException - Thrown if there is a problem in executing the operation.

executeGetReferenceStringTask

public java.lang.String executeGetReferenceStringTask(GetReferenceStringTask task)
                                               throws DBExecutionException

Get the model reference string for the given model name.

Specified by:

executeGetReferenceStringTask in interface DBConnection

Parameters:

task - Task that contains the model name.

Returns:

The reference string for the given model name.

Throws:

DBExecutionException - If thrown while fetching the reference string.

executeGetFirstLevelParents

public java.util.List<XMLDBModel> executeGetFirstLevelParents(GetFirstLevelParentsTask task)
                                                       throws DBExecutionException

Execute the given task to fetch the first level parents for the given model. First level parents are models that are immediate parents for the given model.

Specified by:

executeGetFirstLevelParents in interface DBConnection

Parameters:

task - Task that contains the model for which the first level parents list needs to be fetched.

Returns:

List of models that are the first-level parents of the given model.

Throws:

DBExecutionException - If thrown while fetching the parents list from the database.

executeGetModelTask

public XMLDBModel executeGetModelTask(GetModelTask task)
                               throws DBExecutionException

Execute the get model task and return the model requested as XMLDBModel object as it is represented in the database.

Specified by:

executeGetModelTask in interface DBConnection

Parameters:

task - The GetModelTask object that contains the model name.

Returns:

Model retrieved from the database in XMLDBModel object format.

Throws:

DBExecutionException - Thrown if there is a problem executing the task.

executeGetCompleteModelTask

public XMLDBModel executeGetCompleteModelTask(GetModelTask task)
                                       throws DBExecutionException

Execute the get model task and return the model requested as XMLDBModel object and resolve any references in it.

Specified by:

executeGetCompleteModelTask in interface DBConnection

Parameters:

task - The GetModelTask object that contains the model name.

Returns:

Model retrieved from the database as XMLDBModel task.

Throws:

DBExecutionException - Thrown if there is a problem executing the task.

doesModelExist

public boolean doesModelExist(XMLDBModel model)
                       throws DBExecutionException

Check if the given model already exists in the database.

Parameters:

model - XMLDBModel that needs to be looked up in the database.

Returns:

True if model exists, false otherwise.

Throws:

DBExecutionException - If thrown while getting hte model from the database.

executeAttributeSearchTask

public java.util.ArrayList<XMLDBModel> executeAttributeSearchTask(AttributeSearchTask task)
                                                           throws DBExecutionException

Search models that contain the given attributes in the database.

Specified by:

executeAttributeSearchTask in interface DBConnection

Parameters:

task - Task that contains a list of attributes that need to be searched in the database.

Returns:

List of models that contain the attributes; Empty list if the search returns zero results; and Null list if the search is not performed due to empty or invalid search criteria.

Throws:

DBExecutionException - If thrown while searching in the database.

executeCreateAttributeTask

public XMLDBAttribute executeCreateAttributeTask(CreateAttributeTask task)
                                          throws DBExecutionException

Execute a create attribute task which adds a new attribute to the database.

Specified by:

executeCreateAttributeTask in interface DBConnection

Parameters:

task - The task that contains the new attribute to be created.

Returns:

The XMLDBAttribute object that was stored in the Database.

Throws:

DBExecutionException - Thrown if the operation fails.

executeDeleteAttributeTask

public void executeDeleteAttributeTask(DeleteAttributeTask task)
                                throws DBExecutionException

Execute delete attribute task which deletes a given attribute from the database.

Specified by:

executeDeleteAttributeTask in interface DBConnection

Parameters:

task - The task that contains the attribute to be deleted.

Throws:

DBExecutionException - Thrown if the operation fails.

executeGraphSearchTask

public java.util.ArrayList<XMLDBModel> executeGraphSearchTask(GraphSearchTask task)
                                                       throws DBExecutionException

Search models that contain given graphical pattern in the database.

Specified by:

executeGraphSearchTask in interface DBConnection

Parameters:

task - Task that contains the graph search criteria.

Returns:

List of models that match the given search criteria.

Throws:

DBExecutionException - If thrown while searching in the database.

executeSaveModelTask

public java.lang.String executeSaveModelTask(SaveModelTask task)
                                      throws DBExecutionException,
                                             CircularDependencyException

Execute the necessary commands to save/update a model in the database according to the model specification given in the task parameter.

Specified by:

executeSaveModelTask in interface DBConnection

Parameters:

task - a SaveModelTask to be completed.

Returns:

The Id of the model saved.

Throws:

DBExecutionException - Thrown if there is a problem executing the task.

CircularDependencyException - If thrown while creating reference string.

executeModelNameSearchTask

public java.util.ArrayList<XMLDBModel> executeModelNameSearchTask(ModelNameSearchTask modelNameSearchTask)
                                                           throws DBExecutionException

Execute the model name search task.

Specified by:

executeModelNameSearchTask in interface DBConnection

Parameters:

modelNameSearchTask - Task that contains the model name to be searched for.

Returns:

List of matching models.

Throws:

DBExecutionException - If thrown while searching the database.

executeRemoveModelsTask

public void executeRemoveModelsTask(RemoveModelsTask task)
                             throws DBExecutionException

Execute remove models task to delete a list of models from the database.

Specified by:

executeRemoveModelsTask in interface DBConnection

Parameters:

task - Contains a list of models to be deleted from the database.

Throws:

DBExecutionException - Thrown if the operation fails.

executeRenameModelTask

public void executeRenameModelTask(RenameModelTask task)
                            throws DBConnectionException,
                                   DBExecutionException,
                                   ModelAlreadyExistException,
                                   DBModelNotFoundException

Execute rename model task which will change the name of the model in the database and reflect the change in the reference file.

Specified by:

executeRenameModelTask in interface DBConnection

Parameters:

task - RenameModelTask object that contains the XMLDBModel object and the new name.

Throws:

DBConnectionException - Thrown if there was a problem with the connection.

DBExecutionException - Thrown if there is a problem in executing the task.

DBModelNotFoundException - Thrown if the model with the name to be changed does not exist.

ModelAlreadyExistException - Thrown if the new name is a name of a model that is already in the database.

executeUpdateAttributeTask

public void executeUpdateAttributeTask(UpdateAttributeTask task)
                                throws DBExecutionException

Execute update attribute task to update a given attribute in the database.

Specified by:

executeUpdateAttributeTask in interface DBConnection

Parameters:

task - The task that holds the attribute to be updated.

Throws:

DBExecutionException - Thrown if the operation fails with an error.

executeUpdateModelInCache

public void executeUpdateModelInCache(XMLDBModel xmlDBModel)
                               throws DBExecutionException

Execute the necessary commands to update the cache with the given model.

If the model exists, replace it with the new model.
If the model does not exist, save it in the cache.

Specified by:

executeUpdateModelInCache in interface DBConnection

Parameters:

xmlDBModel - The model object that needs to be added to the cache.

Throws:

DBExecutionException - Thrown if the operation fails. already exists.

executeUpdateParentsToNewVersion

public void executeUpdateParentsToNewVersion(UpdateParentsToNewVersionTask task)
                                      throws DBExecutionException

Execute the given task to update the referenced version for the given parents from the old model to the new model.

Specified by:

executeUpdateParentsToNewVersion in interface DBConnection

Parameters:

task - Task that contains the list of parents, the old model and the new model.

Throws:

DBExecutionException - If thrown while updating the parents in the database.

toString

public java.lang.String toString()

Provide information regarding the state of the internal variables useful for unit testing purposes.

Overrides:

toString in class java.lang.Object

Returns:

String representation for state of internal variables.

_getDistinctModelsList

protected java.util.ArrayList<XMLDBModel> _getDistinctModelsList(java.util.ArrayList<java.lang.String> modelNamesList)

Create a list of distinct XMLDBModels from the given list that may contain duplicates.

Parameters:

modelNamesList - List of models that may contain duplicates.

Returns:

List of distinct XMLDBModels.