Java driver for Tarantool Cartridge

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:

cartridge-java/src/test/java/io/tarantool/driver/integration/SingleInstanceExampleTest.java

Lines 51 to 59 in 2f8e826

	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:

cartridge-java/src/test/java/io/tarantool/driver/integration/SingleInstanceExampleTest.java

Lines 64 to 79 in 2f8e826

	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

• Using CRUD stored procedures
  Connecting to routers with tarantool/crud library. It proxies space interface's methods to CRUD methods.
• Connecting to multiple instances
  Connecting to multiple Tarantool instances.
• Retrying
  Retrying transient cluster failures.
• TarantoolTuple usage
  Creating and operating with TarantoolTuple entity.
• Mappers and converters
  Converting data from MessagePack types to basic Java types and back.
• Token authorization
  An example of TDG authorization by token
• Custom sharding function
  Determining bucket id on java side to send requests directly on storage.
• Thread control
  Specifying custom numbers of netty work threads.
• Space not found
  The problem of getting metadata.
• SSL and mTLS usage examples (enterprise edition only)
  Connect to Tarantool instances over an SSL or mTLS channel.

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.

Changelog

License

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