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();

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

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"))
                .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)
                .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();

For more information see HTTP Connections in the technical docs.

4. Customizing the Description

The connection provider description is displayed in the application frame title (e.g., "Chinook - SCOTT@SERVER@HOST") and can be retrieved via EntityConnectionProvider.description().

4.1. Default Descriptions

Each connection provider type has its own default description:

  • LocalEntityConnectionProvider - Database name in uppercase (e.g., "H2DB")

  • RemoteEntityConnectionProvider - Server name and hostname (e.g., "SERVER@HOST")

  • HttpEntityConnectionProvider - Hostname or URL (e.g., "example.com")

4.2. Overriding the Description

You can override the default description using the configuration property:

-Dis.codion.framework.db.EntityConnectionProvider.description=MyDescription

This is particularly useful when:

  • Using HTTP connections with long URLs

  • Hiding production server details from the frame title

  • Providing a more user-friendly connection identifier

Example: Production client with generic description
java -Dis.codion.framework.db.EntityConnectionProvider.description=production \
     -jar myapp-client.jar

Result: MyApp - SCOTT@PRODUCTION instead of MyApp - SCOTT@SERVER@PROD-DB-01.COMPANY.COM