Class CayenneRuntime

java.lang.Object
org.apache.cayenne.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. To create CayenneRuntime use builder available with one of the of() methods: 

CayenneRuntime cayenneRuntime = CayenneRuntime.of()
        .addConfig("cayenne-project.xml")
        .build();
Since:
5.0

  • Field Details

    • injector

      protected final org.apache.cayenne.di.Injector injector

    • modules

      protected final Collection<org.apache.cayenne.di.Module> modules

  • Constructor Details

    • CayenneRuntime

      protected CayenneRuntime(Collection<org.apache.cayenne.di.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

    • of

      public static CayenneRuntimeBuilder of()
      Creates a builder of CayenneRuntime.
      Returns:
      a builder of CayenneRuntime.
      Since:
      5.0

    • of

      public static CayenneRuntimeBuilder of(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

    • builder

      @Deprecated(since="5.0", forRemoval=true) public static CayenneRuntimeBuilder builder()
      Deprecated, for removal: This API element is subject to removal in a future version.
      use of() instead
      Creates a builder of CayenneRuntime.

    • builder

      @Deprecated(since="5.0", forRemoval=true) public static CayenneRuntimeBuilder builder(String name)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use of(String) instead
      Creates a builder of CayenneRuntime.

    • 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

    • getChannel

      @Deprecated(since="5.0", forRemoval=true) public DataChannel getChannel()
      Deprecated, for removal: This API element is subject to removal in a future version.
      in favor of getDataDomain()
      Returns the runtime DataChannel.

    • getDataDomain

      public DataDomain getDataDomain()
      Returns the main runtime DataDomain.

    • 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

      @Deprecated(since="5.0", forRemoval=true) public Collection<org.apache.cayenne.di.Module> getModules()
      Deprecated, for removal: This API element is subject to removal in a future version.
      this is fairly useless. Modules are opaque. getInjector() is the closest useful thing.
      Returns the collection of modules used to initialize this runtime.
      Since:
      4.0

    • getInjector

      public org.apache.cayenne.di.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.

    • newContext

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

    • newContext

      @Deprecated(since="5.0", forRemoval=true) public ObjectContext newContext(DataChannel parentChannel)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use either newContext() or newContext(ObjectContext)
      Returns a new ObjectContext attached to the specified DataChannel.
      Since:
      4.0

    • newContext

      public ObjectContext newContext(ObjectContext parentContext)
      Returns a new ObjectContext nested in the specified parent context. The nested context selects and commits its objects via the parent.
      Since:
      5.0