i3.dragos.core.services.datasources
Class DataSource

java.lang.Object
  i3.dragos.core.services.datasources.DataSource

public abstract class DataSource
extends java.lang.Object

DRAGOS uses the concept of a data source to support abritrary storages. For each different database there must be a special implementation of this class.

Since DRAGOS uses reflection to instantiate the DataSource implementations, each must provide a public constructor that takes two DataSourceURL arguments (the physical and the logical DataSourceURL).

Author:

Boris Boehlen <boehlen@cs.rwth-aachen.de>, Thorsten Hermes <thermes@i3.informatik.rwth-aachen.de>

See Also:

DataSourceURL, DataSourceFactory

Constructor Summary

DataSource(DataSourceURL physicalDSURL, DataSourceURL logicalDSURL)
Constructs a new data source.

Method Summary

abstract void	close() Closes the connection to the data source and frees all resources that were used by the connection.
DataSourceTransaction	createTransaction() Creates an implementation specific top-level transaction for the data source.
abstract DataSourceTransaction	createTransaction(DataSourceTransaction parent) Creates a (potentially nested) transaction.
DataSourceURL	getLogicalURL() Returns the (logical) data source URL that identifies the data source.
abstract DataSourceMetaData	getMetaData() Returns informations on the data source and its capabilities.
DataSourceURL	getPhysicalURL() Returns the (physical) data source URL that identifies the data source.
abstract void	open() Opens a physical connection to the data source.

Methods inherited from class java.lang.Object

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

Constructor Detail

DataSource

public DataSource(DataSourceURL physicalDSURL,
                  DataSourceURL logicalDSURL)
           throws DataSourceException

Constructs a new data source.

Parameters:

physicalDSURL - The physical DataSourceURL that is needed to create the data source (must not be null).

logicalDSURL - The logical DataSourceURL that will identify the data source from now on (must not be null).

Throws:

DataSourceException - if something went wrong during the initial construction of the datasource

Method Detail

getPhysicalURL

public final DataSourceURL getPhysicalURL()

Returns the (physical) data source URL that identifies the data source.

Returns:

the (physical) data source URL that identifies the data source.

getLogicalURL

public final DataSourceURL getLogicalURL()

Returns the (logical) data source URL that identifies the data source.

Returns:

the (logical) data source URL that identifies the data source.

open

public abstract void open()
                   throws DataSourceException

Opens a physical connection to the data source. Further calls of open() on a opened data source should have no effect.

Throws:

DataSourceException - if it was not possible to open the data source.

close

public abstract void close()
                    throws DataSourceException

Closes the connection to the data source and frees all resources that were used by the connection. Further calls of close() on a closed data source should have no effect.

Throws:

DataSourceException - if it was not possible to close the data source.

getMetaData

public abstract DataSourceMetaData getMetaData()

Returns informations on the data source and its capabilities. The returned information may be unreliable if open() has not been called before!

Returns:

informations on the data source and its capabilities.

createTransaction

public final DataSourceTransaction createTransaction()
                                              throws DataSourceException

Creates an implementation specific top-level transaction for the data source.

In contrast to TransactionManager, there is a separate method for creating nested transactions, because we do not have a Thread<->Transaction mapping here that would allow us to automatically determine the appropriate parent transaction.

This method is a shortcut for createTransaction(null).

Returns:

A transaction specific for the data source.

Throws:

DataSourceException - if it was not possible to create the transaction.

createTransaction

public abstract DataSourceTransaction createTransaction(DataSourceTransaction parent)
                                                 throws DataSourceException

Creates a (potentially nested) transaction.

Throws a DataSourceTransactionException if

• an internal error occurs or
• parent != null and
  • this implementation does not support nested transactions or
  • the parent transaction is not in state Transaction.State.BEGUN or
  Transaction.State.ROLLBACK_ONLY or
  • there is another nested transaction already / still active.

The TransactionManager may only create one top-level transaction per thread. A DataSource implementation may throw a DataSourceTransactionException if there is already a top-level transaction for this thread that has not yet been rolled back or committed.

Parameters:

parent - the parent transaction, may be null.

Returns:

a new transaction.

Throws:

DataSourceException - in case of errors, see full method comment for details.

See Also:

DataSourceMetaData.supportsNestedTransactions()