Alpha

These pages are built from turborel-java’s main, turborel 0.0.0. Anything may change from one build to the next: SQL, API, protocol and files alike.

The SQL-agent

NAME

Agent: a program's named connections, one current, as turborel-client's SQL-agent gives them

SYNOPSIS

package com.turborel.jdbc.internal.session;

public final class Agent {
    @FunctionalInterface public interface Connector {
        Connection connect(@Nullable String server, @Nullable String user) throws TurborelException;
    }
    public Agent(Connector connector);
    public static Agent connected(Connector connector, Connection connection);
    public Outcome query(String sql) throws TurborelException;
    public Streamed queryInto(String sql, Sink sink) throws TurborelException;
    public @Nullable Completed connectionStatement(String sql) throws TurborelException;
    public Connection current() throws TurborelException;
    public @Nullable Connection currentConnection();
    public @Nullable String currentName();
    public @Nullable Canceller canceller();
    public @Nullable String warning();
    public boolean isLost();
    public void terminate() throws TurborelException;
}

These packages are not exported by the module (RULES.md D2).

DESCRIPTION

query and queryInto run a connection statement themselves, giving its completion, and send every other statement to the current connection. A statement is a connection statement if it begins with CONNECT or DISCONNECT, or with SET CONNECTION, and is then read whole, as ISO/IEC 9075:1992 §15 writes them:

CONNECT TO DEFAULT
CONNECT TO <server> [ AS <connection name> ] [ USER <user name> ]
SET CONNECTION { DEFAULT | <connection name> }
DISCONNECT { DEFAULT | ALL | CURRENT | <connection name> }

Each name is a character string literal, its spaces trimmed. CONNECT asks the Connector for a connection to the server it names, or for DEFAULT none, as the user it names, or none; the connection is named by AS, else by the server's name, read as an identifier, a regular one in upper case; DEFAULT names the default connection. It becomes current. SET CONNECTION makes another current. DISCONNECT ends the connections it names; if the current one is ended, none is current. connected makes an agent whose default connection, current, is one the program made. terminate ends every connection.

ERRORS

SQLCODE SQLSTATE When
-900 0A001 CONNECT or SET CONNECTION while the current connection's transaction is active
-104 28000 A user that is no authorization identifier
-919 2E000 A connection name that is no identifier
-919 08002 A connection of the name, or the default one, already made
-919 08001 The connector's connection failure (SQLSTATE 08006): the server not reached
-919 08004 The connector's other failure: the server refused
-919 08003 No connection of the name, or none current
-917 25000 DISCONNECT of a connection whose transaction is active
0 01002 DISCONNECT of a connection that could not be ended: a warning, the connection gone still
-103 2A000 A name that is no character string literal, as a dynamic parameter
-102 2A000 A statement that begins as a connection statement and is not one
-101 2A000 A literal, a delimited identifier or a comment not closed
-900 0A000 An embedded variable, :name

EXAMPLES

agent.query("CONNECT TO DEFAULT");
agent.query("CONNECT TO '127.0.0.1:17434' AS 'reports' USER 'ann'");
System.out.println("current: " + agent.currentName());
current: REPORTS

The User's Guide's chapter Pipelines and Pools has the whole program.

STANDARD

ISO/IEC 9075:1992 §15.1, §15.2, §15.3; [CLIENT The SQL-agent].

SEE ALSO

Settings, Connections