Package io.picodata.driver

Picodata/Tarantool Client implementation based on the Netty transport and official MessagePack serializer implementation.

See: Description

Class Summary

Class	Description
TarantoolVersion	Represents the Tarantool server version
TarantoolVersionHolder	Aware of detecting Tarantool versions in the passed source.

Exception Summary

Exception	Description
InvalidVersionException	Occurs when the version received from Tarantool server is invalid or unsupported

Package io.picodata.driver Description

Picodata/Tarantool Client implementation based on the Netty transport and official MessagePack serializer implementation.

Usage example:

     TarantoolClientConfig config = new TarantoolClientConfig.Builder()
         .withCredentials(new SimpleTarantoolCredentials("admin", "1q2w3e"))
         .build();

     TarantoolClient<TarantoolTuple, TarantoolResult<TarantoolTuple>> client;

     // using try-with-resources (auto close)
     try (client = 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("localhost", 3301)
           // For connecting to a Picodata instance, you need to first set up user authorization, e.g.
           // connect to the instance using picodata admin and execute a query like
           // ALTER USER "admin" WITH PASSWORD 'P@ssw0rd' USING md5;
           .withCredentials("admin", "P@ssw0rd")
           // This setting is important as the default authentication mechanism for Picodata
           // is different from Tarantool
           .withAuthMechanism(PicodataAuthMechanism.DEFAULT)
           // for connecting to a Tarantool Cartridge cluster, uncomment the next line:
           // .withProxyMethodMapping()
           // you may also specify more client settings, such as:
           // timeouts, number of connections, custom MessagePack entities to Java objects mapping, etc.
           .build()) {

         // Execute SQL queries on a Picodata server

         Map<String, Object> result = client.callForSingleResult(
             "pico.sql",
             Collections.singletonList(
                 "create table t (a int not null, primary key (a)) " +
                 "using memtx " +
                 "distributed by (a) " +
                 "option (timeout = 3) "
             ),
             Map.class
         ).get();

         // Work with Tarantool spaces ("box") API directly on a Tarantool server

         // built-in tuple type

         TarantoolResult<TarantoolTuple> tuples = client.space("test")
             // using index named "secondary"
             .select("secondary",
                     TarantoolIteratorType.ITER_ALL,
                     new TarantoolSelectOptions.Builder().withLimit(10).build())
             .get(); // using CompletableFuture in synchronous way

         // tuples can be iterated over
         tuples.forEach((t) -> System.out.println(String.format("Tuple ID=%d, name=%s",
             // Field interface with built-in primitive types conversions
             // Since each row can contain different number of fields, each field is wrapped in Optional
             t.getField(0).map(TarantoolField::getInteger).orElseThrow(RuntimeException::new),
             // Tuple interface for working with raw objects.
             // The mapper provided in config must contain a converter for the corresponding target type
             t.getObject(1, String.class).orElseThrow(RuntimeException::new))));

         // user-defined tuple type

         // using primary index
         TarantoolIndexQuery query = new TarantoolIndexQuery(TarantoolIndexQuery.PRIMARY);
         TarantoolResult<CustomTuple> customTuples = client.space("test")
             .select(query,
                     // specifying select options is mandatory to avoid unwanted loading of too much data
                     // the default parameters are set to unlimited, though
                     new TarantoolSelectOptions(),
                     // convert raw MessagePack array to object by hand
                     (v) -> new CustomTuple(v.get(0).asIntegerValue().asInt(), v.get(1).asStringValue().asString()))
             .get();

         customTuples.forEach(
             (t) -> System.out.println(String.format("Tuple ID=%d, name=%s", t.getId(), t.getName())));

         // call custom exposed API methods written in Lua

         CompletableFuture<Integer> result = client.callForSingleResult(
              "add_two_numbers", Arrays.asList(1, 2), Integer.class);

     } catch (TarantoolClientException | IOException | InterruptedException | ExecutionException e) {
         // checked exceptions
         e.printStackTrace();
     }