Using the Java OJAI Thin Client

Starting with EEP 6.3.0, you can use the Java OJAI Thin Client to write HPE Ezmeral Data Fabric Database JSON applications. The Java OJAI Thin Client provides a lightweight library that supports the OJAI API. You can connect to HPE Ezmeral Data Fabric Database JSON, and add, update, and query documents in a HPE Ezmeral Data Fabric Database JSON table.

Java OJAI Thin Client Benefits

The client provides you with the following benefits:

  • Easy installation and use
  • Access to HPE Ezmeral Data Fabric Database JSON through the OJAI interface
  • An OJAI interface that is tailored to Java developers
  • Support for L3/L4 (transport level) and L7 (application level) proxy load balancing

Comparing the Java OJAI Client and the Java OJAI Thin Client

Note these considerations when deciding whether to use the Java OJAI Client or the Java OJAI Thin Client:
  • Both the Java OJAI client and Java OJAI Thin Client use the same API (Java OJAI Client API).
  • The Java OJAI client is more scalable, more performant, and more fault tolerant, but also more complicated to deploy. See Using the Java OJAI Client.
  • The Java OJAI Thin Client requires you to specify the service (Data Fabric Data Access Gateway) to which you will connect.
  • The Java OJAI Thin Client is a pure Java client, while the Java OJAI client requires a JNI library.

Installing the Data Fabric Data Access Gateway

To use the Java OJAI Thin Client, you must install the Data Fabric Data Access Gateway on your HPE Ezmeral Data Fabric cluster. The gateway serves as a proxy for translating requests between the Java OJAI Thin Client and the HPE Ezmeral Data Fabric cluster. To administer the gateway and configure load balancing, see Administering the Data Access Gateway.

Java OJAI Thin Client Security

The client supports username/password authentication. The initial connection (and token renewal) use these credentials. Subsequent communication uses JWT.

When connecting to a secure cluster, the client uses:

  • X.509 certificates to authenticate with the Data Access Gateway
  • TLS v1.2 to encrypt communication between the client and the Data Access Gateway

Java OJAI Thin Client Connection String

The string you use to connect your OJAI client to a HPE Ezmeral Data Fabric cluster must have the following format:

"ojai:mapr:thin:@<hostname>[:<port>][?<option_name>=<option_value>;...]"
<hostname>
Name of the HPE Ezmeral Data Fabric Data Access Gateway host
<port>
Port number (see Ports Used by HPE Ezmeral Data Fabric Software) that gRPC clients use to connect to the HPE Ezmeral Data Fabric Data Access Gateway

Default: 5678

auth=<scheme_name>

The authentication scheme for the current connection; currently, only basic

user=<username>

The user name for basic authentication

password=<password>

The password for basic authentication

ssl=true|false

Whether to establish a secure connection using SSL/TLS

An error is returned if there is a mismatch between your client and cluster security settings. The default for this option is true, which is the required setting if connecting to a secure HPE Ezmeral Data Fabric cluster. If connecting to a nonsecure HPE Ezmeral Data Fabric cluster, set it to false.

If set to false, the other SSL parameters are ignored.

sslCA=<path to PEM file containing CA certificate>

Path to a local file containing Certificate Authority (CA) signed certificates in PEM format. For information about the PEM format, see Configuring SSL for OJAI Clients.

Must be set if the ssl option is true.

Here is an example of a connection string:

"ojai:mapr:thin:@localhost:5678?auth=basic;user=fred;password=george;sslCA=/opt/app/conf/rootca.pem"

Advanced Parameters

Advanced parameters such as maxmsgsize are optional for the Java OJAI Thin Client connection string:

maxmsgsize

If you use thin-client version 1.0.2-mapr and later, maxmsgsize sets the maximum message size that the gRPC client accepts. The default is set to 32 MB, as this is the default maximum document size for HPE Ezmeral Data Fabric Database JSON tables.

The value specified in the connection string should be less than or equal to the value set in the Data Access Gateway configuration on the server side (see Administering the Data Access Gateway).

Maven Coordinates

The Maven coordinates are:
<dependency>
    <groupId>com.mapr.ojai</groupId>
    <artifactId>mapr-ojai-driver-thin</artifactId>
    <version>1.0.3-mapr</version>
</dependency>

Additional Resources

The Java OJAI Client examples at the following location also apply to the Java OJAI Thin Client. Only the connection string and the Maven artifact name will be different for the thin client: https://github.com/mapr-demos/ojai-examples/tree/master/java/src/main/java/com/mapr/ojai/examples