*If you're reading this on GitHub, please note that this is the readme

for the development version and that some features described here might

not yet have been released. You can find the documentation for latest

version through [Java driver

docs](http://datastax.github.io/java-driver/) or via the release tags,

[e.g.

2.1.5](https://github.com/datastax/java-driver/tree/2.1.5).*

A Java client driver for Apache Cassandra. This driver works exclusively with

the Cassandra Query Language version 3 (CQL3) and Cassandra's binary protocol.

- JIRA: https://datastax-oss.atlassian.net/browse/JAVA

- MAILING LIST: https://groups.google.com/a/lists.datastax.com/forum/#!forum/java-driver-user

- IRC: #datastax-drivers on [irc.freenode.net](http://freenode.net)

- TWITTER: Follow the latest news about DataStax Drivers - [@olim7t](http://twitter.com/olim7t), [@mfiguiere](http://twitter.com/mfiguiere)

- DOCS: http://www.datastax.com/documentation/developer/java-driver/2.1/index.html

- API: http://www.datastax.com/drivers/java/2.1

- CHANGELOG: https://github.com/datastax/java-driver/blob/2.1/driver-core/CHANGELOG.rst

The driver architecture is based on layers. At the bottom lies the driver core.

This core handles everything related to the connections to a Cassandra

cluster (for example, connection pool, discovering new nodes, etc.) and exposes a simple,

relatively low-level API on top of which higher level layer can be built.

The driver contains the following modules:

- driver-core: the core layer.

- driver-mapping: the object mapper.

- driver-examples: example applications using the other modules which are

only meant for demonstration purposes.

Please refer to the README of each module for more information.

The last release of the driver is available on Maven Central. You can install

it in your application using the following Maven dependency:

<dependency>

<groupId>com.datastax.cassandra</groupId>

<artifactId>cassandra-driver-core</artifactId>

<version>2.1.5</version>

</dependency>

Note that the object mapper is published as a separate artifact:

<dependency>

<groupId>com.datastax.cassandra</groupId>

<artifactId>cassandra-driver-mapping</artifactId>

<version>2.1.5</version>

</dependency>

We also provide a [shaded JAR](http://datastax.github.io/java-driver/features/shaded_jar/)

to avoid the explicit dependency to Netty.

The Java client driver 2.1 ([branch 2.1](https://github.com/datastax/java-driver/tree/2.1)) is compatible with Apache

Cassandra 1.2, 2.0 and 2.1.

UDT and tuple support is available only when using Apache Cassandra 2.1 (see [CQL improvements in Cassandra 2.1](http://www.datastax.com/dev/blog/cql-in-2-1)).

Other features are available only when using Apache Cassandra 2.0 or higher (e.g. result set paging,

[BatchStatement](https://github.com/datastax/java-driver/blob/2.1/driver-core/src/main/java/com/datastax/driver/core/BatchStatement.java),

[lightweight transactions](http://www.datastax.com/documentation/cql/3.1/cql/cql_using/use_ltweight_transaction_t.html)

-- see [What's new in Cassandra 2.0](http://www.datastax.com/documentation/cassandra/2.0/cassandra/features/features_key_c.html)).

Trying to use these with a cluster running Cassandra 1.2 will result in

an [UnsupportedFeatureException](https://github.com/datastax/java-driver/blob/2.1/driver-core/src/main/java/com/datastax/driver/core/exceptions/UnsupportedFeatureException.java) being thrown.

If you are upgrading from the 2.0.x branch of the driver, be sure to have a look at

the [upgrade guide](https://github.com/datastax/java-driver/blob/2.1/driver-core/Upgrade_guide_to_2.1.rst).

If you are upgrading from the 1.x branch, follow the [upgrade guide to 2.0](https://github.com/datastax/java-driver/blob/2.0/driver-core/Upgrade_guide_to_2.0.rst),

and then the above document.

If you are having issues connecting to the cluster (seeing `NoHostAvailableConnection` exceptions) please check the

[connection requirements](https://github.com/datastax/java-driver/wiki/Connection-requirements).

Copyright 2012-2014, DataStax

Licensed under the Apache License, Version 2.0 (the "License");

you may not use this file except in compliance with the License.

You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software

distributed under the License is distributed on an "AS IS" BASIS,

WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

See the License for the specific language governing permissions and

limitations under the License.

title: Java Driver for Apache Cassandra

summary: High performance Java client for Apache Cassandra

homepage: http://datastax.github.io/java-driver/

sections:

- title: Features

prefix: /features

sources:

- type: markdown

files: 'features/**/*.md'

links:

- title: Code

href: https://github.com/datastax/java-driver/

- title: Docs

href: http://datastax.github.io/java-driver/

- title: Issues

href: https://datastax-oss.atlassian.net/browse/JAVA/

- title: Mailing List

href: https://groups.google.com/a/lists.datastax.com/forum/#!forum/java-driver-user

- title: IRC Channel

href: irc://irc.freenode.net/datastax-drivers

- title: Releases

href: https://github.com/datastax/java-driver/releases

This documentation is a work in progress. Use the "Read More" menu on the right hand side to browse currently documented features.

You can also refer to the

[user documentation](http://www.datastax.com/documentation/developer/java-driver/2.1/java-driver/whatsNew2.html)

on the DataStax website.

The driver auto-detects new Cassandra nodes added to the cluster through server

side push notifications and through checking the system tables.

For each node, the address the driver will receive will correspond to the address set as

`rpc_address` in the node's `cassandra.yaml` file. In most cases, this is the correct value.

However, sometimes the addresses received through this mechanism will either not be

reachable directly by the driver, or should not be the preferred address to use

(for instance, it might be a private IP, but some clients may have to use a public IP, or

go through a router).

This interface allows you to deal with such cases, by transforming the address sent by a

Cassandra node to another address to be used by the driver for connection.

public class MyAddressTranslater implements AddressTranslater {

public InetSocketAddress translate(InetSocketAddress address) {

... // your custom translation logic

}

}

Cluster cluster = Cluster.builder()

.addContactPoint("1.2.3.4")

.withAddressTranslater(new MyAddressTranslater())

.build();

Notes:

* the contact points provided while creating the `Cluster` are not translated, only addresses

retrieved from or sent by Cassandra nodes are;

* you might want to implement `CloseableAddressTranslater` if your implementation has state that

should be cleaned up when the `Cluster` shuts down. This is provided as a separate interface for

historical reasons, the `close()` method will be merged in `AddressTranslater` in a future

release.

`EC2MultiRegionAddressTranslater` is provided out of the box. It helps optimize network costs when

your infrastructure (both Cassandra nodes *and* clients) is distributed across multiple Amazon EC2

regions:

* a client communicating with a Cassandra node *in the same EC2 region* should use the node's

private IP (which is less expensive);

* a client communicating with a node in a different region should use the public IP.

To use this implementation, provide an instance when initializing the `Cluster`:

Cluster cluster = Cluster.builder()

.addContactPoint("1.2.3.4")

.withAddressTranslater(new EC2MultiRegionAddressTranslater())

.build();

This class performs a reverse DNS lookup of the origin address, to find the domain name of the

target instance. Then it performs a forward DNS lookup of the domain name; the EC2 DNS does the

private/public switch automatically based on location.

If connections stay idle for too long, they might be dropped by

intermediate network devices (routers, firewalls...). Normally, TCP

keepalive should take care of this; but tweaking low-level keepalive

settings might be impractical in some environments.

The driver provides application-side keepalive in the form of a

connection heartbeat: when a connection has been idle for a given amount

of time, the driver will simulate activity by writing a dummy request to

it.

This feature is enabled by default. The default heartbeat interval is 30

seconds, it can be customized through `PoolingOptions`:

cluster.getConfiguration().getPoolingOptions()

.setHeartbeatIntervalSeconds(60);

This can be changed at runtime, but only connections created after that

will use the new interval. Most users will want to do this at startup:

Cluster cluster = Cluster.builder()

.addContactPoint("127.0.0.1")

.withPoolingOptions(new PoolingOptions()

.setHeartbeatIntervalSeconds(60))

.build();

The heartbeat interval should be set higher than

[SocketOptions.readTimeoutMillis](http://www.datastax.com/drivers/java/2.1/com/datastax/driver/core/SocketOptions.html#getReadTimeoutMillis()):

the read timeout is the maximum time that the driver waits for a regular

query to complete, therefore the connection should not be considered

idle before it has elapsed.

To disable heartbeat, set the interval to 0.

Implementation note: the dummy request sent by heartbeat is an

[OPTIONS](https://github.com/apache/cassandra/blob/trunk/doc/native_protocol_v3.spec#L278)

message.

The default driver JAR depends on [Netty](http://netty.io/), which is

used internally for networking.

This explicit dependency can be a problem if your application already

uses another Netty version. To avoid conflicts, we provide a "shaded"

version of the JAR, which bundles the Netty classes under a different

package name:

<dependency>

<groupId>${project.groupId}</groupId>

<artifactId>cassandra-driver-core</artifactId>

<version>2.1.5</version>

<classifier>shaded</classifier>

<!-- Because the shaded JAR uses the original POM, you still need

to exclude this dependency explicitly: -->

<exclusions>

<exclusion>

<groupId>io.netty</groupId>

<artifactId>*</artifactId>

</exclusion>

</exclusions>

</dependency>

If you also use the mapper, you need to remove its dependency to the

non-shaded JAR:

<dependency>

<groupId>com.datastax.cassandra</groupId>

<artifactId>cassandra-driver-core</artifactId>

<version>2.1.5</version>

<classifier>shaded</classifier>

<exclusions>

<exclusion>

<groupId>io.netty</groupId>

<artifactId>*</artifactId>

</exclusion>

</exclusions>

</dependency>

<dependency>

<groupId>com.datastax.cassandra</groupId>

<artifactId>cassandra-driver-mapping</artifactId>

<version>2.1.5</version>

<exclusions>

<exclusion>

<groupId>com.datastax.cassandra</groupId>

<artifactId>cassandra-driver-core</artifactId>

</exclusion>

</exclusions>

</dependency>