com.amazon.carbonado.spi
Class AbstractRepository<Txn>

java.lang.Object
  com.amazon.carbonado.spi.AbstractRepository<Txn>

Type Parameters:

Txn - Transaction type

All Implemented Interfaces:

Capability, ShutdownCapability, Repository, SequenceCapability

public abstract class AbstractRepository<Txn>
extends Object
implements Repository, ShutdownCapability, SequenceCapability

Implements basic functionality required by a core Repository.

Since:

1.2

Author:

Brian S O'Neill

Constructor Summary

protected

AbstractRepository(String name)

Method Summary

protected Collection<Storage>	allStorage() Returns all available Storage instances.
void	close() Closes this repository reference, aborting any current transactions.
protected abstract SequenceValueProducer	createSequenceValueProducer(String name) Called upon to create a new SequenceValueProducer instance.
protected abstract <S extends Storable> Storage<S>	createStorage(Class<S> type) Called upon to create a new Storage instance.
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(Class<C> capabilityType) Default implementation checks if Repository implements Capability interface, and if so, returns the Repository.
protected abstract org.apache.commons.logging.Log	getLog() Return the main Log object for this Repository.
String	getName() Returns the name of this repository.
SequenceValueProducer	getSequenceValueProducer(String name) Retrieve and/or generate a SequenceValueProducer for the given name.
IsolationLevel	getTransactionIsolationLevel() Returns the isolation level of the current transaction, or null if there is no transaction in the current thread.
boolean	isAutoShutdownEnabled() Returns true if repository has a shutdown hook registered to automatically call shutdown when the virtual machine exits.
protected abstract TransactionScope<Txn>	localTransactionScope() Returns the thread-local TransactionScope, creating it if needed.
protected void	lockoutShutdown() Call to prevent shutdown hook from running.
void	setAutoShutdownEnabled(boolean enabled) Request to enable or disable the automatic shutdown hook.
void	shutdown() Similar to calling close on a repository, except should only be called when the virtual machine is in the process of shutting down.
protected void	shutdownHook() Install custom shutdown logic by overriding this method.
<S extends Storable> Storage<S>	storageFor(Class<S> type) Returns a Storage instance for the given user defined Storable class or interface.
protected abstract TransactionManager<Txn>	transactionManager() Returns the repository's TransactionManager.
protected void	unlockoutShutdown() Only call this to release lockoutShutdown.

Methods inherited from class java.lang.Object

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

Constructor Detail

AbstractRepository

protected AbstractRepository(String name)

Method Detail

getName

public String getName()

Description copied from interface: Repository

Returns the name of this repository.

Specified by:

getName in interface Repository

storageFor

public <S extends Storable> Storage<S> storageFor(Class<S> type)
                                       throws SupportException,
                                              RepositoryException

Description copied from interface: Repository

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

Specified by:

storageFor in interface Repository

Returns:

specific type of Storage instance

Throws:

SupportException - if specified type cannot be supported

RepositoryException - if storage layer throws any other kind of exception

enterTransaction

public Transaction enterTransaction()

Description copied from interface: Repository

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();
 }
 

Specified by:

enterTransaction in interface Repository

enterTransaction

public Transaction enterTransaction(IsolationLevel level)

Description copied from interface: Repository

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.

Specified by:

enterTransaction in interface Repository

Parameters:

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

See Also:

Repository.enterTransaction()

enterTopTransaction

public Transaction enterTopTransaction(IsolationLevel level)

Description copied from interface: Repository

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.

Specified by:

enterTopTransaction in interface Repository

Parameters:

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

See Also:

Repository.enterTransaction()

getTransactionIsolationLevel

public IsolationLevel getTransactionIsolationLevel()

Description copied from interface: Repository

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

Specified by:

getTransactionIsolationLevel in interface Repository

getCapability

public <C extends Capability> C getCapability(Class<C> capabilityType)

Default implementation checks if Repository implements Capability interface, and if so, returns the Repository.

Specified by:

getCapability in interface Repository

Parameters:

capabilityType - type of capability requested

Returns:

capability instance or null if not supported

close

public void close()

Description copied from interface: Repository

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

Specified by:

close in interface Repository

isAutoShutdownEnabled

public boolean isAutoShutdownEnabled()

Description copied from interface: ShutdownCapability

Returns true if repository has a shutdown hook registered to automatically call shutdown when the virtual machine exits.

Specified by:

isAutoShutdownEnabled in interface ShutdownCapability

setAutoShutdownEnabled

public void setAutoShutdownEnabled(boolean enabled)

Description copied from interface: ShutdownCapability

Request to enable or disable the automatic shutdown hook. Repository may ignore this request if shutdown is in progress.

Specified by:

setAutoShutdownEnabled in interface ShutdownCapability

shutdown

public void shutdown()

Description copied from interface: ShutdownCapability

Similar to calling close on a repository, except should only be called when the virtual machine is in the process of shutting down. Calling close may cause spurious exceptions to be thrown by other threads which may be interacting with the repository. Shutdown tries to reduce these exceptions from being thrown by effectively suspending any threads which continue to interact with this repository. For this reason, this method should only ever be called during a virtual machine shutdown.

Repositories may choose to implement this method by simply calling close. There is no guarantee that shutdown will reduce exceptions, and it might not suspend any threads. Also, repositories that require proper shutdown should automatically register runtime hooks, and so this method usually doesn't need to be called manually.

Specified by:

shutdown in interface ShutdownCapability

getSequenceValueProducer

public SequenceValueProducer getSequenceValueProducer(String name)
                                               throws RepositoryException

Description copied from interface: SequenceCapability

Retrieve and/or generate a SequenceValueProducer for the given name.

Specified by:

getSequenceValueProducer in interface SequenceCapability

Parameters:

name - sequence name

Throws:

RepositoryException

transactionManager

protected abstract TransactionManager<Txn> transactionManager()

Returns the repository's TransactionManager.

localTransactionScope

protected abstract TransactionScope<Txn> localTransactionScope()

Returns the thread-local TransactionScope, creating it if needed.

lockoutShutdown

protected void lockoutShutdown()

Call to prevent shutdown hook from running. Be sure to call unlockoutShutdown afterwards.

unlockoutShutdown

protected void unlockoutShutdown()

Only call this to release lockoutShutdown.

allStorage

protected Collection<Storage> allStorage()

Returns all available Storage instances.

shutdownHook

protected void shutdownHook()

Install custom shutdown logic by overriding this method. By default it does nothing.

getLog

protected abstract org.apache.commons.logging.Log getLog()

Return the main Log object for this Repository. If none provided, then no messages are logged by AbstractRepository.

createStorage

protected abstract <S extends Storable> Storage<S> createStorage(Class<S> type)
                                                      throws RepositoryException

Called upon to create a new Storage instance.

Throws:

RepositoryException

createSequenceValueProducer

protected abstract SequenceValueProducer createSequenceValueProducer(String name)
                                                              throws RepositoryException

Called upon to create a new SequenceValueProducer instance.

Throws:

RepositoryException