Hector (API)

Hector is a high-level client API for Apache Cassandra. Named after Hector, the builder of Troy in Greek mythology, it is a substitute for the Cassandra Java Client, or Thrift,^[1] that is encapsulated by Hector.^[2] It also has Maven repository access.^[3]

History

As Cassandra is shipped with the low-level Thrift (protocol), there was a potential to develop a better protocol for application developers. Hector was developed by Ran Tavory as a high-level interface that overlays the shortcomings of Thrift. It is licensed with the MIT License that allows to use, modify, split and change the design.

Over the last couple of days I got the conclusion that the java client I’ve been using so far to speak to cassanrda wasn’t satisfactory. I used the one simply called cassandra-java-client, which is a good start but had some shortcomings I could just not live with (no support for Cassandra v0.5, no JMX and no failover). So I’ve written my own.

Features

The high-level features of Hector are^[1]

• A high-level object oriented interface to Cassandra: It is mainly inspired by the Cassandra-java-client. The API is defined in the Keyspace interface.
• Connection pooling. As in high-scale applications, the usual pattern for DAOs is a large number of reads/writes. It is too expensive for clients to open new connections with each request. So, a client may easily run out of available sockets, if it operates fast enough. Hector provides connection pooling and a nice framework that manages the details.
• Failover support: As Cassandra is a distributed data store where hosts (nodes) may go down. Hector has its own failover policy.

• JMX support: Hector exposes JMX for many important runtime metrics, such as number of available connections, idle connections, error statistics.
• Load balancing: A simple load balancing exists in the newer version.^[4]
• Supports the command design pattern to allow clients to concentrate on their business logic and let Hector take care of the required plumbing.

Availability metrics

Hector exposes availability counters and statistics through JMX.^[5]

Load balancing

Hector follows two load balancing policies with the LoadBalancingPolicy interface. The default is called the LeastActiveBalancingPolicy and routes requests to the pools having the lowest number of active connections, ensuring a good spread of utilisation across the cluster. The RoundRobinBalancingPolicy is a simple round-robin distribution algorithm.^[6]

Pooling

The ExhaustedPolicy determines how the underlying client connection pools are controlled. Currently, three options are available:^[7]

Code examples

As an example, an implementation of a simple distributed hashtable over Cassandra is listed.

 /**
   * Insert a new value keyed by key
   * @param key Key for the value
   * @param value the String value to insert
   */
  public void insert(final String key, final String value) throws Exception {
    execute(new Command(){
      public Void execute(final Keyspace ks) throws Exception {
        ks.insert(key, createColumnPath(COLUMN_NAME), bytes(value));
        return null;
      }
    });
  }
 
  /**
   * Get a string value.
   * @return The string value; null if no value exists for the given key.
   */
  public String get(final String key) throws Exception {
    return execute(new Command(){
      public String execute(final Keyspace ks) throws Exception {
        try {
          return string(ks.getColumn(key, createColumnPath(COLUMN_NAME)).getValue());
        } catch (NotFoundException e) {
          return null;
        }
      }
    });
  }
 
  /**
   * Delete a key from cassandra
   */
  public void delete(final String key) throws Exception {
    execute(new Command(){
      public Void execute(final Keyspace ks) throws Exception {
        ks.remove(key, createColumnPath(COLUMN_NAME));
        return null;
      }
    });
  }

References

See also

• Apache Cassandra
• JMX

External links

• Apache Thrift
• Hector on github
• The Cassandra Java client