Module is.codion.framework.db.local
Package is.codion.framework.db.local

Interface LocalEntityConnection

All Superinterfaces:
AutoCloseable, EntityConnection
public interface LocalEntityConnection extends EntityConnection
EntityConnection implementation based on a local JDBC connection. A factory for LocalEntityConnection instances. 
Domain domain = new ChinookImpl();
String url = "jdbc:h2:file:/path/to/database";
Database database = DatabaseFactory.instance(url).create(url);
User user = User.parse("scott:tiger");

try (EntityConnection connection = localEntityConnection(database, domain, user)) {
  List<Entity> customers = connection.select(Condition.all(Customer.TYPE));
}

  • Field Details

    • TRACING

      static final PropertyValue<Boolean> TRACING
      Specifies whether method tracing is enabled by default.
      • Value type: Boolean
      • Default value: false
      See Also:

    • TRACES

      static final PropertyValue<Integer> TRACES
      Specifies the number of log traces to keep while tracing is enabled.
      • Value type: Integer
      • Default value: 50

    • QUERY_TIMEOUT

      static final PropertyValue<Integer> QUERY_TIMEOUT
      Specifies the query timeout in seconds
      • Value type: Integer
      • Default value: 120

    • ITERATOR_BUFFER_SIZE

      static final PropertyValue<Integer> ITERATOR_BUFFER_SIZE
      Specifies the buffer size to use when iterating over entities.

      When iterating, entities are fetched in batches of this size to allow for efficient population of foreign key references. Each batch has its foreign keys populated before the entities are returned via Iterator.next().

      Note that buffering is only performed when there are foreign keys to populate. If the select does not include any foreign keys (or all have reference depth 0), the iterator returns entities directly without buffering, minimizing memory overhead.

      • Value type: Integer
      • Default value: 200
      See Also:

    • OPTIMISTIC_LOCKING

      static final PropertyValue<Boolean> OPTIMISTIC_LOCKING
      Specifies whether optimistic locking should be performed, that is, if entities should be selected for update and checked for modification before being updated. This is the connection-level switch; the per-entity default is specified by EntityDefinition.OPTIMISTIC_LOCKING.
      • Value type: Boolean
      • Default value: true
      See Also:

    • LIMIT_REFERENCE_DEPTH

      static final PropertyValue<Boolean> LIMIT_REFERENCE_DEPTH
      Specifies whether the foreign key value graph depth should be limited by the foreign key reference depth setting instead of being fully populated.
      • Value type: Boolean
      • Default value: true

  • Method Details

    • connection

      Connection connection()
      Returns the underlying connection, throwing in case it is closed.

      Statements executed on the returned connection are not guarded by this connection's monitor, so they may interleave with operations performed by other threads, see EntityConnection.

      Returns:
      the underlying connection
      Throws:
      DatabaseException - in case this connection is closed

    • database

      Database database()
      Returns:
      the underlying database

    • optimisticLocking

      boolean optimisticLocking()
      Returns:
      true if optimistic locking is enabled

    • optimisticLocking

      void optimisticLocking(boolean optimisticLocking)
      Parameters:
      optimisticLocking - true if optimistic locking should be enabled

    • iteratorBufferSize

      int iteratorBufferSize()
      Returns the buffer size used when iterating over entities with foreign keys to populate.
      Returns:
      the iterator buffer size
      See Also:

    • iteratorBufferSize

      void iteratorBufferSize(int iteratorBufferSize)
      Sets the buffer size to use when iterating over entities with foreign keys to populate.
      Parameters:
      iteratorBufferSize - the buffer size
      See Also:

    • limitReferenceDepth

      boolean limitReferenceDepth()
      Returns:
      true if foreign key reference depths are being limited

    • limitReferenceDepth

      void limitReferenceDepth(boolean limitReferenceDepth)
      Note that disabling the reference depth limit fetches the full foreign key graph, including foreign keys specifying a reference depth of 0, which are otherwise never populated automatically.

      Note also that disabling the reference depth limit (or specifying a reference depth of -1) removes the only bound on foreign key population; a cyclic foreign key reference in the data then causes unbounded recursion and a StackOverflowError, since no cycle detection is performed.

      Parameters:
      limitReferenceDepth - false to override the reference depth limit specified by conditions or entities
      See Also:

    • queryTimeout

      int queryTimeout()
      Returns:
      the default query timeout being used

    • queryTimeout

      void queryTimeout(int queryTimeout)
      Parameters:
      queryTimeout - the query timeout in seconds

    • builder

      static LocalEntityConnection.Builder builder()

      Instantiates a builder for a self-managing LocalEntityConnection, one which connects on demand and reconnects when the underlying connection has gone bad, serving for the lifetime of a client.

      Contrast with localEntityConnection(Database, Domain, Connection), which wraps a connection supplied by the caller, for scoped use such as a pooled connection on a server.

      Returns:
      a new builder
      See Also:

    • localEntityConnection

      static LocalEntityConnection localEntityConnection(Database database, Domain domain, User user)
      Constructs a new LocalEntityConnection instance
      Parameters:
      database - the Database instance
      domain - the domain model
      user - the user used for connecting to the database
      Returns:
      a new LocalEntityConnection instance
      Throws:
      DatabaseException - in case there is a problem connecting to the database
      AuthenticationException - in case of an authentication error

    • localEntityConnection

      static LocalEntityConnection localEntityConnection(Database database, Domain domain, Connection connection)
      Constructs a new LocalEntityConnection instance. Note that auto-commit is disabled on the given connection.
      Parameters:
      database - the Database instance
      domain - the domain model
      connection - the connection object to base the entity connection on, it is assumed to be in a valid state
      Returns:
      a new LocalEntityConnection instance, wrapping the given connection
      Throws:
      DatabaseException - in case there is a problem with the supplied connection

    • localEntityConnection

      static LocalEntityConnection localEntityConnection(Domain domain, LocalEntityConnection connection)

      Constructs a new LocalEntityConnection for the given domain, joined to the given connection: sharing its database, JDBC connection and transaction. For a domain kept apart from the application's, such as a module's own tables, written in the application's transaction.

      • A transaction started, committed or rolled back on either is the other's too. An operation outside a transaction commits, on either, as it does on the given connection.
      • The operations of the two are serialized, as those of a single connection.
      • A JDBC connection attached to the given connection, see ConnectionHolder, is the joined one's too, and is configured by its domain before it uses it, see Domain.configure(Connection). A joined connection throws UnsupportedOperationException from the ConnectionHolder methods.
      • Closing the joined connection leaves the given connection, and any open transaction, as they are. Closing the given connection closes the joined one as well.

      The joined connection starts with the given connection's settings, its query timeout for example, and shares its method tracer. It has its own query cache, see EntityConnection.cacheQueries().

      A connection joined to a self-managing one, see builder(), is joined to the JDBC connection that one holds at the time. Should it re-establish its connection, the statements of the joined one fail as on a closed connection, as does starting a transaction or using a savepoint through it, while a transaction the self-managing one is in can still be committed or rolled back through it. A connection joined to a joined one is joined to the same connection.

      Parameters:
      domain - the domain model
      connection - the connection to join
      Returns:
      a new LocalEntityConnection, joined to the given one
      Throws:
      IllegalArgumentException - in case the given connection was created by neither localEntityConnection(Database, Domain, User), localEntityConnection(Database, Domain, Connection), builder() nor this method
      IllegalStateException - in case the given connection is a self-managing one which has been closed

    • configureDatabase

      static Database configureDatabase(Database database, Domain domain)
      Runs the database configuration for the given domain on the given database. Prevents multiple runs for the same domain/database combination.
      Parameters:
      database - the database to configure
      domain - the domain doing the configuring
      Returns:
      the Database instance
      Throws:
      DatabaseException - in case of an exception