Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 36 ยท Java API

Java Client: Connections and Tables

Set up the HBase Java client with Maven, create one shared Connection, get lightweight Table objects, convert values with Bytes, and follow resource and threading rules.

Applications talk to HBase through a client library, and the most complete one is the Java client (hbase-client). Other languages use gateways (REST, Thrift) or third-party clients, but the Java API is the reference: every feature appears there first. This lesson covers the foundation of every program: the dependency, the configuration, the heavy Connection, the light Table, and the Bytes helper.

The site cannot connect to a real HBase server, so the real client code appears as read-only listings. The runnable examples are Java stand-ins with the same shape (a Connection that hands out Tables) that you can use to practise the structure, including how an application can be tested without a cluster.

Adding the dependency

With Maven, add the client library. Use the version that matches your cluster's major line (2.x here):

XML
<dependency>
  <groupId>org.apache.hbase</groupId>
  <artifactId>hbase-client</artifactId>
  <version>2.6.1</version>
</dependency>

The example version is only an example; choose the release your server runs. Gradle users write implementation("org.apache.hbase:hbase-client:2.6.1"). The client pulls in Hadoop and ZooKeeper libraries as transitive dependencies, so a typical fat jar is large; avoid version clashes by using the same Hadoop line as your cluster.

Configuration

HBaseConfiguration.create() builds a Hadoop Configuration pre-loaded with hbase-default.xml and any hbase-site.xml found on the classpath. For a client, the one property that matters is how to find ZooKeeper:

Java
Configuration conf = HBaseConfiguration.create();
conf.set("hbase.zookeeper.quorum", "zk1.example.com,zk2.example.com,zk3.example.com");
conf.set("hbase.zookeeper.property.clientPort", "2181");

Instead of coding values, you can copy the cluster's hbase-site.xml onto the application's classpath. Useful client properties include hbase.client.operation.timeout, hbase.rpc.timeout, hbase.client.retries.number and hbase.client.scanner.caching. Set timeouts deliberately: the defaults retry for a long time (minutes), which can make a failing dependency look like a hang.

In HBase 2.x you can also use a connection URI such as hbase+zk://zk1:2181/ with ConnectionFactory.createConnection(URI) in newer releases; check the Javadoc of your version.

Connection: heavy, shared, thread-safe

Java
try (Connection connection = ConnectionFactory.createConnection(conf)) {
    // use it
}

A Connection is expensive: it holds ZooKeeper sessions, a location cache, thread pools and RPC channels to many RegionServers. It is thread-safe. The rule is: create one per application (or per process), share it everywhere, and close it only when the application exits. Creating one per request is the most common client performance bug in HBase code.

Table: light, per-use, not thread-safe

Java
try (Connection connection = ConnectionFactory.createConnection(conf);
     Table table = connection.getTable(TableName.valueOf("users"))) {
    // get, put, scan ...
}

getTable is cheap: it returns a handle sharing the connection's resources. Table is not thread-safe. Get one when you need it (per task or per request) and close it with try-with-resources. The TableName object identifies the table; use TableName.valueOf("ns:table") for a namespaced table.

Bytes: converting to and from byte arrays

HBase stores bytes, so row keys, families, qualifiers and values all go through org.apache.hadoop.hbase.util.Bytes:

Java
byte[] row = Bytes.toBytes("user#001");          // String -> bytes (UTF-8)
byte[] age = Bytes.toBytes(42);                  // int    -> 4 bytes (big-endian)
byte[] big = Bytes.toBytes(42L);                 // long   -> 8 bytes
String s = Bytes.toString(row);
int n = Bytes.toInt(age);

Numbers are written big-endian, so non-negative integers sort correctly as bytes. Negative numbers do not: they begin with a high bit, so -1 sorts after 1. Flip the sign bit if you need signed numbers in a row key. Also note Bytes.toBytes(42) (an int) and Bytes.toBytes(42L) (a long) are different arrays; reading with the wrong type gives garbage or an exception.

The stand-in reproduces this byte behavior using only the JDK, so you can see the sort order problem yourself.

Java Stand-in: byte encodings and sort order

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Code that can be tested

Production classes should depend on a small interface, not on Table directly. In tests you pass an in-memory fake. The stand-in uses the same names as the real client (Connection, Table, get, put) but keeps data in a map. Your repository class works with both the real client and the fake.

Java Stand-in: a Connection and Table you can test against

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Putting it together: a real skeleton

This is the typical shape of an application that uses HBase (read-only, needs a cluster):

Java
public final class HBaseClient implements AutoCloseable {
    private final Connection connection;

    public HBaseClient(String zkQuorum) throws IOException {
        Configuration conf = HBaseConfiguration.create();
        conf.set("hbase.zookeeper.quorum", zkQuorum);
        conf.setInt("hbase.client.retries.number", 5);
        conf.setInt("hbase.rpc.timeout", 10_000);
        this.connection = ConnectionFactory.createConnection(conf);
    }

    public Table table(String name) throws IOException {
        return connection.getTable(TableName.valueOf(name));
    }

    @Override
    public void close() throws IOException {
        connection.close();
    }
}

Frameworks fit this pattern: in Spring you declare the Connection as a singleton bean with a destroy method, and inject it into repositories that call getTable per operation.

Common mistakes

  • A new Connection per request. Slow and exhausts ZooKeeper sessions.
  • Sharing one Table between threads. Not thread-safe; get one per thread or task.
  • Not closing Tables, ResultScanners or the Connection. Leaks threads and sockets.
  • Mixing int and long encodings for the same column.
  • Default timeouts. Set them so failures show up in seconds.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How many Connection objects should a typical application create?

    Connection is heavy and thread-safe; share it for the life of the process.
  2. 2. Which statement about Table is correct?

    Table is cheap to create from a Connection but must not be shared across threads. Close it after use.
  3. 3. What is the byte length of Bytes.toBytes(42L)?

    A long is 8 bytes. An int is 4 bytes, so the two encodings differ.
  4. 4. What is a good way to locate the cluster from a client?

    The client contacts ZooKeeper first, so it needs the quorum addresses.

Summary

  • Add hbase-client matching your cluster's version line.
  • HBaseConfiguration.create() plus hbase.zookeeper.quorum (or hbase-site.xml) configures the client; set sensible timeouts.
  • One shared, thread-safe Connection; short-lived, single-threaded Table objects; close both properly.
  • Bytes converts values; numbers are big-endian and negative numbers do not sort naturally.
  • Depend on small interfaces so application code can be tested with an in-memory fake.

Next: Java Client: Put, Get and Delete