An EntityConnectionProvider is a factory and lifecycle manager for EntityConnection instances — ensuring reliable access to the database regardless of protocol (JDBC, RMI, HTTP).

In most cases EntityConnections are retrieved from a EntityConnectionProvider, which is responsible for establishing a connection to the underlying database. The EntityConnectionProvider class is central to the framework and is a common constructor parameter in classes requiring database access.

Each call to connection() returns the current active connection. If the existing connection is invalid (e.g., due to network failure or server restart), a new one is transparently established. If the EntityConnectionProvider is unable to connect to the underlying database or server, connection() throws an exception.

Important
 Do NOT cache the EntityConnection instance. The instance returned by connection() should only be kept for a short time, such as a local variable or method parameter since it can become invalid and thereby unusable. Always use connection() to make sure you have a healthy EntityConnection.

1. LocalEntityConnectionProvider

LocalEntityConnectionProvider

Provides a connection based on a local JDBC connection.

Database.URL.set("jdbc:h2:mem:h2db");
Database.INIT_SCRIPTS.set("src/main/sql/create_schema.sql");

Database database = Database.instance();

LocalEntityConnectionProvider connectionProvider =
        LocalEntityConnectionProvider.builder()
                .database(database)
                .domain(new ChinookImpl())
                .user(User.parse("scott:tiger"))
                .build();

LocalEntityConnection entityConnection =
        connectionProvider.connection();

DatabaseConnection databaseConnection =
        entityConnection.databaseConnection();

// the underlying JDBC connection is available in a local connection
Connection connection = databaseConnection.getConnection();

connectionProvider.close();

2. RemoteEntityConnectionProvider

RemoteEntityConnectionProvider

Provides a connection based on a remote RMI connection.

RemoteEntityConnectionProvider connectionProvider =
        RemoteEntityConnectionProvider.builder()
                .domain(Chinook.DOMAIN)
                .user(User.parse("scott:tiger"))
                .clientType(EntityConnectionProviderDemo.class.getSimpleName())
                .hostName("localhost")
                .registryPort(1099)
                .build();

EntityConnection entityConnection =
        connectionProvider.connection();

Entities entities = entityConnection.entities();

Entity track = entityConnection.select(entities.primaryKey(Track.TYPE, 42L));

connectionProvider.close();

3. HttpEntityConnectionProvider

HttpEntityConnectionProvider

Provides a connection based on a remote HTTP connection.

HttpEntityConnectionProvider connectionProvider =
        HttpEntityConnectionProvider.builder()
                .domain(Chinook.DOMAIN)
                .clientType(EntityConnectionProviderDemo.class.getSimpleName())
                .user(User.parse("scott:tiger"))
                .hostName("localhost")
                .port(8080)
                .https(false)
                .build();

EntityConnection entityConnection = connectionProvider.connection();

Entities entities = entityConnection.entities();

entityConnection.select(entities.primaryKey(Track.TYPE, 42L));

connectionProvider.close();