Skip to content

Tarantool Cartridge Java driver for Tarantool versions 1.10+ based on Netty framework

License

Notifications You must be signed in to change notification settings

tarantool/cartridge-java

Repository files navigation

Java driver for Tarantool Cartridge

Tests Community Tests Enterprise

Java driver for Tarantool Cartridge for Tarantool versions 1.10+ based on the asynchronous Netty framework and official MessagePack serializer. Provides CRUD APIs for seamlessly working with standalone Tarantool servers and clusters managed by Tarantool Cartridge with sharding via vshard.

Quickstart

Here is an easy way to try using Tarantool together with this Java driver.

Look at the single instance test to start experimenting with a single Tarantool server instance and a simple Java app. You can set breakpoints and run it in "debug" mode using your IDE. Testcontainers library will start a single instance Tarantool server for you. Try to manipulate data in Tarantool in real time through evaluating Java expressions in debug mode or using the Tarantool console.

If you want to start a simple Tarantool application manually, all you need is to install Tarantool and run it with this file:

tarantool src/test/resources/single-instance.lua

Example of creating a TarantoolClient instance:

return TarantoolClientFactory.createClient()
// If any addresses or an address provider are not specified,
// the default host 127.0.0.1 and port 3301 are used
.withAddress(container.getHost(), container.getPort())
// For connecting to a Cartridge application, use the value of cluster_cookie parameter in the init.lua file
.withCredentials(container.getUsername(), container.getPassword())
// you may also specify more client settings, such as:
// timeouts, number of connections, custom MessagePack entities to Java objects mapping, etc.
.build();

Example of the TarantoolClient API usage:

try (TarantoolClient<TarantoolTuple, TarantoolResult<TarantoolTuple>> client = setupClient()) {
TarantoolTupleFactory tupleFactory =
new DefaultTarantoolTupleFactory(mapperFactory.defaultComplexTypesMapper());
TarantoolSpaceOperations<TarantoolTuple, TarantoolResult<TarantoolTuple>> regionSpace =
client.space("region");
TarantoolTuple tarantoolTuple = tupleFactory.create(Arrays.asList(77, "Moscow"));
TarantoolResult<TarantoolTuple> insertTuples = regionSpace.insert(tarantoolTuple).get();
TarantoolResult<TarantoolTuple> selectTuples =
regionSpace.select(Conditions.equals("id", 77)).get();
TarantoolTuple insertTuple = insertTuples.get(0);
TarantoolTuple selectTuple = selectTuples.get(0);
assertEquals(insertTuple.getInteger("id"), selectTuple.getInteger("id"));
assertEquals(insertTuple.getString("name"), selectTuple.getString("name"));
}

If you use this code in another project don't forget to add a cartridge-driver dependency:

<dependency>
  <groupId>io.tarantool</groupId>
  <artifactId>cartridge-driver</artifactId>
  <version>0.14.0</version>
</dependency>

Advanced usage

Documentation

The Java Docs are available at Github pages.

If you have any questions about working with Tarantool, check out the site tarantool.io.

Feel free to ask questions about Tarantool and usage of this driver on Stack Overflow with tag tarantool or join our community support chats in Telegram: English and Russian.

Requirements

Java 1.8 or higher is required for building and using this driver.

Building

  1. Docker accessible to the current user is required for running integration tests.
  2. Set up the right user for running Tarantool with in the container:
export TARANTOOL_SERVER_USER=<current user>
export TARANTOOL_SERVER_GROUP=<current group>

Substitute the user and group in these commands with the user and group under which the tests will run. 3. Use ./mvnw verify to run unit tests and ./mvnw test -Pintegration to run integration tests. 4. Use ./mvnw install for installing the artifact locally.

Contributing

Contributions to this project are always welcome and highly encouraged. See conventions for tests