Repository (Carbonado 1.2.3 API)

+
+
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
    +
  +
+

Interface Repository

Method Summary

Method Detail

getName

storageFor

enterTransaction

enterTransaction

enterTopTransaction

getTransactionIsolationLevel

getCapability

close