Connection Builders

An EntityConnection built via one of the builders below manages itself, regardless of protocol (JDBC, RMI, HTTP): it connects on demand, validates the underlying connection before each operation and re-establishes it when it has gone bad.

A client therefore holds on to a single EntityConnection instance for its lifetime, handing it to the models requiring database access. The instance stays valid across a network failure or a server restart, only the connection underneath it being replaced. If no connection can be established the operation throws.

Tip	Use EntityConnection.builder() to build a connection of the type specified by the CLIENT_CONNECTION_TYPE configuration value, instead of naming a transport at compile time.

1. LocalEntityConnection

LocalEntityConnection

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

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

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

entityConnection.close();

2. RemoteEntityConnection

RemoteEntityConnection

A connection based on a remote RMI connection.

EntityConnection entityConnection =
        RemoteEntityConnection.builder()
                .domain(Chinook.DOMAIN)
                .user(User.parse("scott:tiger"))
                .hostname("localhost")
                .registryPort(1099)
                .build();

Entities entities = entityConnection.entities();

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

entityConnection.close();

3. HttpEntityConnection

HttpEntityConnection

A connection based on a remote HTTP connection.

EntityConnection entityConnection =
        HttpEntityConnection.builder()
                .domain(Chinook.DOMAIN)
                .user(User.parse("scott:tiger"))
                .hostname("localhost")
                .port(8080)
                .https(false)
                .build();

Entities entities = entityConnection.entities();

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

entityConnection.close();

For more information see HTTP Connections in the technical docs.

4. Customizing the Description

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

4.1. Default Descriptions

Each connection type has its own default description:

LocalEntityConnection - Database name in uppercase (e.g., "H2DB")
RemoteEntityConnection - Server name and hostname (e.g., "SERVER@HOST")
HttpEntityConnection - Hostname or URL (e.g., "example.com")

4.2. Overriding the Description

You can override the default description using the configuration property EntityConnection.DESCRIPTION

EntityConnection.DESCRIPTION.set("MyDescription");

or the associated JVM argument

-Dis.codion.framework.db.EntityConnection.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.EntityConnection.description=production \
     -jar myapp-client.jar

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