Package org.apache.cayenne.runtime

# Class CayenneRuntime

java.lang.Object
org.apache.cayenne.runtime.CayenneRuntime

Direct Known Subclasses:
  `ServerRuntime`

public class CayenneRuntime extends Object
Object representing Cayenne stack. Serves as an entry point to Cayenne for user applications and a factory of ObjectContexts. It provides a default Cayenne configuration as well as a way to customize this configuration via a built-in dependency injection (DI) container. In fact implementation-wise, Runtime object is just a convenience thin wrapper around a DI `Injector`.

To create CayenneRuntime use builder available with one of the `builder()` methods:

     CayenneRuntime cayenneRuntime = CayenneRuntime.builder()
             .addConfig("cayenne-project.xml")
             .build();

Since:
  3.1 is introduced, 5.0 is repurposed as a single implementation of Cayenne runtime and moved to `org.apache.cayenne.runtime` package.
See Also:
  - `builder()`
  - `builder(String)`
  - `CayenneRuntimeBuilder`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected final Injector`
  `injector`
  `protected final Collection<Module>`
  `modules`
  `protected static final ThreadLocal<Injector>`
  `threadInjector`
  A holder of an Injector bound to the current thread.

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `CayenneRuntime(Collection<Module> modules)`
  Creates a runtime configuring it with a standard set of services contained in `CoreModule`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static void`
  `bindThreadInjector(Injector injector)`
  Binds a DI `Injector` bound to the current thread.
  `static CayenneRuntimeBuilder`
  `builder()`
  Creates a builder of CayenneRuntime.
  `static CayenneRuntimeBuilder`
  `builder(String name)`
  Creates a builder of CayenneRuntime.
  `DataChannel`
  `getChannel()`
  Returns the runtime `DataChannel`.
  `DataDomain`
  `getDataDomain()`
  Returns the main runtime DataDomain.
  `DataSource`
  `getDataSource()`
  Returns a default DataSource for this runtime.
  `DataSource`
  `getDataSource(String dataNodeName)`
  Provides access to the JDBC DataSource assigned to a given DataNode.
  `Injector`
  `getInjector()`
  Returns DI injector used by this runtime.
  `Collection<Module>`
  `getModules()`
  Returns the collection of modules used to initialize this runtime.
  `static Injector`
  `getThreadInjector()`
  Returns the `Injector` bound to the current thread.
  `ObjectContext`
  `newContext()`
  Returns a new ObjectContext instance based on the runtime's main DataChannel.
  `ObjectContext`
  `newContext(DataChannel parentChannel)`
  Returns a new ObjectContext which is a child of the specified DataChannel.
  `<T> T`
  `performInTransaction(TransactionalOperation<T> op)`
  Runs provided operation wrapped in a single transaction.
  `<T> T`
  `performInTransaction(TransactionalOperation<T> op, TransactionDescriptor descriptor)`
  Runs provided operation wrapped in a single transaction.
  `<T> T`
  `performInTransaction(TransactionalOperation<T> op, TransactionListener callback)`
  Runs provided operation wrapped in a single transaction.
  `<T> T`
  `performInTransaction(TransactionalOperation<T> op, TransactionListener callback, TransactionDescriptor descriptor)`
  Runs provided operation wrapped in a single transaction.
  `void`
  `shutdown()`
  Shuts down the DI injector of this runtime, giving all services that need to release some resources a chance to do that.

  ### Methods inherited from class java.lang.Object

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

- ## Field Details

  - ### threadInjector

    protected static final ThreadLocal<Injector> threadInjector
    A holder of an Injector bound to the current thread. Used mainly to allow serializable contexts to attach to correct Cayenne stack on deserialization.
    Since:
      3.1

  - ### injector

    protected final Injector injector

  - ### modules

    protected final Collection<Module> modules

- ## Constructor Details

  - ### CayenneRuntime

    protected CayenneRuntime(Collection<Module> modules)
    Creates a runtime configuring it with a standard set of services contained in `CoreModule`. CoreModule is created with one or more 'configurationLocations'. An optional array of extra modules may contain service overrides and/or user services.

- ## Method Details

  - ### bindThreadInjector

    public static void bindThreadInjector(Injector injector)
    Binds a DI `Injector` bound to the current thread. It is primarily intended for deserialization of ObjectContexts.
    Since:
      3.1

  - ### getThreadInjector

    public static Injector getThreadInjector()
    Returns the `Injector` bound to the current thread. Will return null if none is bound.
    Since:
      3.1

  - ### builder

    public static CayenneRuntimeBuilder builder()
    Creates a builder of CayenneRuntime.
    Returns:
      a builder of CayenneRuntime.
    Since:
      5.0
    See Also:
      - `builder(String)`
      - `CayenneRuntimeBuilder`

  - ### builder

    public static CayenneRuntimeBuilder builder(String name)
    Creates a builder of CayenneRuntime.
    Parameters:
      `name` - optional symbolic name of the created runtime.
    Returns:
      a named builder of CayenneRuntime.
    Since:
      5.0
    See Also:
      - `builder()`
      - `CayenneRuntimeBuilder`

  - ### performInTransaction

    public <T> T performInTransaction(TransactionalOperation<T> op)
    Runs provided operation wrapped in a single transaction. Transaction handling delegated to the internal `TransactionManager`. Nested calls to 'performInTransaction' are safe and attached to the same in-progress transaction. TransactionalOperation can be some arbitrary user code, which most often than not will consist of multiple Cayenne operations.
    Since:
      4.0

  - ### performInTransaction

    public <T> T performInTransaction(TransactionalOperation<T> op, TransactionListener callback)
    Runs provided operation wrapped in a single transaction. Transaction handling delegated to the internal `TransactionManager`. Nested calls to 'performInTransaction' are safe and attached to the same in-progress transaction. TransactionalOperation can be some arbitrary user code, which most often than not will consist of multiple Cayenne operations.
    Since:
      4.0

  - ### performInTransaction

    public <T> T performInTransaction(TransactionalOperation<T> op, TransactionDescriptor descriptor)
    Runs provided operation wrapped in a single transaction. Transaction handling delegated to the internal `TransactionManager`. Nested calls to 'performInTransaction' are safe and attached to the same in-progress transaction. TransactionalOperation can be some arbitrary user code, which most often than not will consist of multiple Cayenne operations.
    Type Parameters:
      `T` - result type
    Parameters:
      `op` - an operation to perform within the transaction.
      `descriptor` - describes additional transaction parameters
    Returns:
      a value returned by the "op" operation.
    Since:
      4.2

  - ### performInTransaction

    public <T> T performInTransaction(TransactionalOperation<T> op, TransactionListener callback, TransactionDescriptor descriptor)
    Runs provided operation wrapped in a single transaction. Transaction handling delegated to the internal `TransactionManager`. Nested calls to 'performInTransaction' are safe and attached to the same in-progress transaction. TransactionalOperation can be some arbitrary user code, which most often than not will consist of multiple Cayenne operations.
    Type Parameters:
      `T` - returned value type
    Parameters:
      `op` - an operation to perform within the transaction.
      `callback` - a callback to notify as transaction progresses through stages.
      `descriptor` - describes additional transaction parameters
    Returns:
      a value returned by the "op" operation.
    Since:
      4.2

  - ### getDataDomain

    public DataDomain getDataDomain()
    Returns the main runtime DataDomain. Note that by default the returned DataDomain is the same as the main DataChannel returned by `getChannel()`. Although users may redefine DataChannel provider in the DI registry, for instance to decorate this DataDomain with a custom wrapper.

  - ### getDataSource

    public DataSource getDataSource()
    Returns a default DataSource for this runtime. If no default DataSource exists, an exception is thrown.
    Since:
      4.0

  - ### getDataSource

    public DataSource getDataSource(String dataNodeName)
    Provides access to the JDBC DataSource assigned to a given DataNode. A null argument will work if there's only one DataNode configured.

    Normally Cayenne applications don't need to access DataSource or any other JDBC code directly, however in some unusual conditions it may be needed, and this method provides a shortcut to raw JDBC.

  - ### getModules

    public Collection<Module> getModules()
    Returns the collection of modules used to initialize this runtime.
    Since:
      4.0

  - ### getInjector

    public Injector getInjector()
    Returns DI injector used by this runtime.

  - ### shutdown

    @BeforeScopeEnd public void shutdown()
    Shuts down the DI injector of this runtime, giving all services that need to release some resources a chance to do that.

  - ### getChannel

    public DataChannel getChannel()
    Returns the runtime `DataChannel`.

  - ### newContext

    public ObjectContext newContext()
    Returns a new ObjectContext instance based on the runtime's main DataChannel.
    Since:
      4.0

  - ### newContext

    public ObjectContext newContext(DataChannel parentChannel)
    Returns a new ObjectContext which is a child of the specified DataChannel. This method is used for creation of nested ObjectContexts, with parent ObjectContext passed as an argument.
    Since:
      4.0