Configuring Avatica with Java

Avatica TLS server is distributed as a standalone JAR file.

To start an Avatica instance using Java, you will need:

The latest JAR file of the Avatica TLS Server from https://github.com/sirensolutions/avatica-tls-server/releases .
A Java distribution from https://jdk.java.net (it is advised to use the latest LTS release).
The JDBC driver of the datasource and its dependencies.
A P12 file containing the server key and certificate if you want to enable TLS (optional but recommended).

After downloading the latest jar file from the releases page to a directory on your system, the Avatica server can be executed as follows:

java -cp "./*" "io.siren.avatica.TlsServer" <OPTIONS>

Supported options

The supported options are as follows:

-u: the JDBC URL of the datasource Avatica is connected to (e.g. jdbc:postgresql://postgres:5432/test). Note that credentials must not be set in the URL, as they will be specified by Avatica clients and passed through by the Avatica server.
--keystore: the path to a Java keystore or p12 bundle that contains a key and a certificate for the server.
--keystorePassword: the password of the keystore.
-s: the serialization format of Avatica requests; valid values are json and protobuf, defaults to protobuf.
--host: the IP address that the Avatica server will bind to (default to all addresses in the system).
-p: the port that the Avatica server will bind to (defaults to 8765).

Example

Assuming that you want to connect to the test database of a PostgreSQL server already running at localhost:5432, you can follow these steps to start an Avatica instance using Java:

Create a new directory named avatica and switch to it.
Download the latest Avatica TLS server jar and the PostgreSQL JDBC Driver to the directory.
Create a new directory named pki.

Create a new self-signed certificate and its key by executing keytool as follows; set the password to password when asked:

keytool -genkey \
  -keystore pki/avatica.p12 -storetype PKCS12 \
  -alias avatica \
  -keyalg RSA -keysize 2048 -sigalg SHA256withRSA \
  -validity 3650 \
  -dname CN=localhost -ext san=dns:localhost

Start Avatica server as follows:

java -cp "./*" "io.siren.avatica.TlsServer" \
  --host 127.0.0.1 \
  --keystore pki/avatica.p12 \
  --keystorePassword password \
  -s json \
  -u "jdbc:postgresql://localhost:5432/test"

You should now be able to test that Avatica is connected to the PostgreSQL database by sending a raw connection opening request with curl:

curl -k https://localhost:8765 -H "Content-Type: application/json" -d '{
  "request": "openConnection",
  "connectionId": "123",
  "info": {
    "user": "test",
    "password": "password"
  }
}'

If the connection is successful, you will get back a JSON response containing the same value as request in the response field, for example:

{
  "response": "openConnection",
  "rpcMetadata": {
    "response": "rpcMetadata",
    ...
  }
}

You can then stop the Avatica server by pressing CTRL+C.

Next steps

After starting an Avatica server, you will need to configure JDBC support in Siren Federate.