Skip to content

Backend Properties — The Session Configuration Keys

Overview and Motivation

Every Tentackle tier — desktop client, application server, daemon, test — reads its connection configuration from a properties file, by default named backend.properties. The file answers one question: how does this JVM reach its persistence layer? For a client that may be a TRIP URL to a server; for a server or a two-tier client it is a JDBC URL to the database — swapping one for the other is the whole point of location transparency.

The file travels inside a SessionInfo as EncryptedProperties, so all keys below are session properties. Most of them configure the backend connection, some configure the server, and a few are interpreted by the application layer. This document is the reference for all of them.

Three general rules:

  • Keys are case-insensitive. jdbcIdleTimeout, jdbcidletimeout and JDBCIDLETIMEOUT are the same key (camelCase is the convention).
  • Values may be encrypted. A value starting with ~ is decrypted via the application's Cryptor — passwords never appear in clear text in a packaged image.
  • Keys may target the JVM. A key written as ^foo (or SYSTEM_foo) is not stored as a session property but set as the system property foo — used, for example, to point javax.net.ssl.keyStore at the image's keystore. See Application Bootstrap.

How the File Is Found

The properties name defaults to backend (the .properties extension is appended), taken from SessionInfo.getPropertiesName(). Applications built on the Application hierarchy accept --backend=<name> on the command line to select a different file — this is how the generated project switches between a direct database connection and a remote server connection.

The name is resolved by PropertiesUtilities through the pluggable PropertiesResourceService providers; the default provider tries the file system first and falls back to a classpath/module resource. Command-line properties take precedence over properties from the file.

Connection Keys

Read by BackendInfo and Db when the session opens.

Key Value
url Where the persistence layer lives. Three forms, see below.
user The username for the technical database connection (not necessarily the application user logging in).
password The password, usually ~-encrypted.
schemas Optional comma-separated list of database schemas.
driver Optional JDBC driver to load at runtime: <driver-class>:<jar-url>. Registers the driver via a URLClassLoader, for drivers that are not on the module path (e.g. added to an already-shipped image).
jdbcIdleTimeout Optional connection inactivity timeout in minutes, 0 (default) = none. Some managed/cloud databases close idle connections no matter what; when set, a dummy SELECT revives a connection idle longer than this.
jdbcKeepAlive Boolean, default false. Only meaningful with jdbcIdleTimeout: true sends the dummy SELECT periodically on idle connections; false sends it only when an idle connection is re-used.
batchsize Enables JDBC statement batching; off by default.
idsource Selects a non-default id source configuration.
backend Redirects the technical connection settings to another source — see Redirecting the Backend below.
application Overrides the application name (normally derived from the main class). Needed in tests that resolve @user/@system backend configurations, which are stored per application name.

The three forms of url

  1. jdbc:... — a direct JDBC connection; the matching backend (SQL dialect) is derived from the URL.
  2. jndi:<name> — a DataSource looked up via JNDI, typical inside containers; the backend is derived from the datasource's connection.
  3. A TRIP URI — anything else, e.g. trips://myserver:18000/MyApp: no local database at all, the session is remote and all persistence operations are delegated to the server at that URI. The scheme selects the transport: trip (plain TCP), trips (SSL), tripe (encrypting), tripce (compressing + encrypting), and with tentackle-quic tripq/tripcq.

For the jdbc: and jndi: forms, the URL may carry a |<BackendName> suffix to pin the SQL dialect explicitly when it cannot (or should not) be derived — e.g. jndi:jdbc/mydb|PostgreSQL. The names are those of the registered backends: PostgreSQL, H2, MariaDB, MySQL, MsSQL, Oracle, Oracle8, DB2, Informix.

Redirecting the Backend: @user, @system, and Named Files

By default, the technical connection settings come from the session properties themselves. The backend key redirects them:

Value Effect
@user / @system The login dialog lets the user manage named backend configurations (URL, credentials, optional runtime-loaded driver) through the UI and pick one at login. They are stored as BackendConfigurations in the user (@user) or system (@system) preferences, per application name.
@user:<name> / @system:<name> Loads the backend configuration <name> directly from the user/system preferences — no dialog interaction. Falls back to the session properties (with a logged warning) if no such configuration exists.
<propertiesName> Loads the technical settings from another properties resource — e.g. to keep technical credentials separate from the session configuration.

If the key is missing, the session properties (and possibly user input from the login dialog) are used as-is.

Server Keys

Read by TripServer when the tier is an application server (see Multi-Tier Cascade).

Key Value
service The TRIP endpoint the server listens to, as a URI: the scheme selects the transport, the path the connection class registered at the Registry, and query parameters are transport-specific — e.g. trips://myserver:18000/MyApp?idle=10&backlog=100.
service_<name> Additional endpoints if the server listens on more than one transport, e.g. service_plain, service_ssl, service_quic — each with its own URI.
connectionclass The fully qualified name of the RemoteDbConnection class to export; usually provided programmatically.
timeout The session timeout for dead client connections, in polling intervals. Defaults to 30 (i.e. 30 seconds at the default interval).
timeoutinterval The polling interval for dead sessions in milliseconds. Defaults to 1000; 0 turns the cleanup thread off entirely (risky).
updateService, updateURL Publish the self-update service for jlink-based clients.

Two different timeouts. timeout is the TRIP session timeout — how long a server keeps a dead client session around. jdbcIdleTimeout is the database connection inactivity timeout on the JDBC side. They are unrelated; a typical server sets both.

Desktop Client Keys

Interpreted by the Rich Desktop Client.

Key Value
autologin Log the user in with the user/password from the properties without asking for credentials. The mere presence of the key enables it (even autologin=false!) — remove the key to disable. A failed autologin terminates the application instead of offering retries.
noRdcCache The presence of the key disables the RDC's GUI caching — useful while editing database-backed bundles with BundleMonkey, so changes become visible immediately.

Application-Level Keys

A further set of well-known keys — notracker, nosecurity, statistics, scripting, locale, readonlyprefs, systemprefs, noprefsync — is interpreted by the application bootstrap itself and documented in Application Bootstrap — Well-known properties.

Examples

A two-tier client or server connecting directly to the database:

url=jdbc:postgresql://dbhost/myapp?sslmode=require
user=myapp
password=~mkfII6HTvbc3IcS2q9t7bA==
schemas=myapp
jdbcIdleTimeout=4
jdbcKeepAlive=true
batchsize=100

# server endpoint and self-update service
service=trips://myserver:18000/MyApp?idle=10
updateService=trips://myserver:18000/UpdateService
updateURL=https://myserver/updates
timeout=30

^javax.net.ssl.keyStore=@{RUNTIMEDIR?.}/conf/keystore.jks
^javax.net.ssl.keyStorePassword=~o93jd2iJdqw2Mss3uAA71g==

A three-tier desktop client connecting to that server, with user-managed backends:

url=trips://myserver:18000/MyApp
backend=@user
^javax.net.ssl.trustStore=@{RUNTIMEDIR?.}/conf/truststore.jks
^javax.net.ssl.trustStorePassword=~x0PoR8fFPqmboo3sJ11w7A==