com.amazon.carbonado

Interface Repository

All Known Implementing Classes:

AbstractRepository

public interface Repository

A Repository represents a database for Storable instances. Some repositories do not have control over the schema (for example, a JDBC Repository depends on the schema defined by the underlying relational database); such repositories are called "dependent". Conversely, a repository which has complete control over the schema is termed "independent".

A dependent repository requires and will verify that Storables have a matching definition in the external storage layer. An independent repository will automatically update type definitions in its database to match changes to Storable definitions.

Repository instances should be thread-safe and immutable. Therefore, it is safe for multiple threads to be interacting with a Repository.

Author:

Brian S O'Neill

See Also:

RepositoryBuilder

Method Summary

Methods

Modifier and Type	Method and Description
void	close() Closes this repository reference, aborting any current transactions.
Transaction	enterTopTransaction(IsolationLevel level) Causes the current thread to enter a top-level transaction scope with an explict isolation level.
Transaction	enterTransaction() Causes the current thread to enter a transaction scope.
Transaction	enterTransaction(IsolationLevel level) Causes the current thread to enter a transaction scope with an explict isolation level.
<C extends Capability> C	getCapability(java.lang.Class<C> capabilityType) Requests a specific capability of this Repository.
java.lang.String	getName() Returns the name of this repository.
IsolationLevel	getTransactionIsolationLevel() Returns the isolation level of the current transaction, or null if there is no transaction in the current thread.
<S extends Storable> Storage<S>	storageFor(java.lang.Class<S> type) Returns a Storage instance for the given user defined Storable class or interface.

Method Detail

getName

java.lang.String getName()

Returns the name of this repository.

storageFor

<S extends Storable> Storage<S> storageFor(java.lang.Class<S> type)
                                       throws SupportException,
                                              RepositoryException

Returns a Storage instance for the given user defined Storable class or interface.

Returns:

specific type of Storage instance

Throws:

java.lang.IllegalArgumentException - if specified type is null

MalformedTypeException - if specified type is not suitable

SupportException - if specified type cannot be supported

RepositoryException - if storage layer throws any other kind of exception

enterTransaction

Transaction enterTransaction()

Causes the current thread to enter a transaction scope. Call commit inside the transaction in order for any updates to the repository to be applied. Be sure to call exit when leaving the scope.

To ensure exit is called, use transactions as follows:

 Transaction txn = repository.enterTransaction();
 try {
     // Make updates to storage layer
     ...

     // Commit the changes up to this point
     txn.commit();

     // Optionally make more updates
     ...

     // Commit remaining changes
     txn.commit();
 } finally {
     // Ensure transaction exits, aborting uncommitted changes if an exception was thrown
     txn.exit();
 }
 

enterTransaction

Transaction enterTransaction(IsolationLevel level)

Causes the current thread to enter a transaction scope with an explict isolation level. The actual isolation level may be higher than requested, if the repository does not support the exact level. If the repository does not support a high enough level, it throws an UnsupportedOperationException.

Parameters:

level - minimum desired transaction isolation level -- if null, a suitable default is selected

Throws:

java.lang.UnsupportedOperationException - if repository does not support isolation as high as the desired level

See Also:

enterTransaction()

enterTopTransaction

Transaction enterTopTransaction(IsolationLevel level)

Causes the current thread to enter a top-level transaction scope with an explict isolation level. The actual isolation level may be higher than requested, if the repository does not support the exact level. If the repository does not support a high enough level, it throws an UnsupportedOperationException.

This method requests a top-level transaction, which means it never has a parent transaction, but it still can be a parent transaction itself. This kind of transaction is useful when a commit must absolutely succeed, even if the current thread is already in a transaction scope. If there was a parent transaction, then a commit might still be rolled back by the parent.

Requesting a top-level transaction can be deadlock prone if the current thread is already in a transaction scope. The top-level transaction may not be able to obtain locks held by the parent transaction. An alternative to requesting top-level transactions is to execute transactions in separate threads.

Parameters:

level - minimum desired transaction isolation level -- if null, a suitable default is selected

Throws:

java.lang.UnsupportedOperationException - if repository does not support isolation as high as the desired level

See Also:

enterTransaction()

getTransactionIsolationLevel

IsolationLevel getTransactionIsolationLevel()

Returns the isolation level of the current transaction, or null if there is no transaction in the current thread.

getCapability

<C extends Capability> C getCapability(java.lang.Class<C> capabilityType)

Requests a specific capability of this Repository. This allows repositories to support extended features without having to clutter the main repository interface. The list of supported capabilities is documented with repository implementations.

Parameters:

capabilityType - type of capability requested

Returns:

capability instance or null if not supported

close

void close()

Closes this repository reference, aborting any current transactions. Operations on objects returned by this repository will fail when accessing the storage layer.

Throws:

java.lang.SecurityException - if caller does not have permission