Using the Java OJAI Thin Client

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

Java OJAI Thin Client Benefits

The client provides you with the following benefits:

  • Easy installation and use
  • Access to MapR 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 (MapR 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 MapR Data Access Gateway

To use the Java OJAI Thin Client, you must install the MapR Data Access Gateway on your MapR cluster. The gateway serves as a proxy for translating requests between the Java OJAI Thin Client and the MapR cluster. To administer the gateway and configure load balancing, see Administering the MapR 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 MapR cluster, the client uses:

  • X.509 certificates to authenticate with the MapR 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 MapR cluster must have the following format:

"ojai:mapr:thin:@<hostname>[:<port>][?<option_name>=<option_value>;...]"
<hostname>
Name of the MapR Data Access Gateway host
<port>
Port number (see Ports Used by MapR Data Platform Software) that gRPC clients use to connect to the MapR 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 MapR cluster. If connecting to a nonsecure MapR 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 MapR 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 MapR 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