How to use Amza

Amza originated as an embeddable replicated log from which it springboarded into a first-class distributed service with full REST capabilities. It has kept many of its roots, however, and therefore can be leveraged in a variety of ways depending on the desired use case.

Free-standing service

Amza can easily be spun up in JAR form in any Linux environment. (Other platforms may perform well, but they are neither tested nor supported at this time.)

The following is a simple example of service startup for a single node using automatic (multicast) service discovery:

$ java -jar amza.jar amza-node1.myhost.net testCluster

The following is a simple example of service startup using some advanced settings:

$ java -Damza.port=1175 -Damza.logicalName=node1 -Damza.discovery.group=225.4.5.6 -Damza.discovery.port=1223 -Damza.working.dirs=/data1,/data2 -Dhost.datacenter=us-west-2 -Dhost.rack=us-west-2a -jar amza.jar amza-node1.myhost.net testCluster

Each node can also be started using manual service discovery, in which you specify one or more active members of your Amza cluster:

$ java -Damza.port=1175 -Damza.logicalName=node1 -Damza.working.dirs=/data1,/data2 -Dhost.datacenter=us-west-2 -Dhost.rack=us-west-2a -jar amza.jar amza-node1.myhost.net testCluster node2:amza-node2.myhost.net:1175,node3:amza-node3.myhost.net:1175,node4:amza-node4.myhost.net:1175

The Amza UI can then be accessed on any node at http://amza-node1.myhost.net:1175/amza. For more information on using the Amza UI, see below.

Upena deployable

Amza is commonly run via Upena, an open source deployment manager that handles cluster configuration and routing. Amza runs as what is known as a deployable, identified by the Maven coordinate com.jivesoftware.os.amza:amza-deployable:tar.gz, where it is fully managed by the Upena ring. Discovery is handled via Upena’s Routing-bird implementation.

Embedded in a Java process

Amza can readily be embedded in a Java process using JAX-RS by depending on the com.jivesoftware.os.amza:amza-service artifact. The Amza node can then be started through use of the EmbeddedAmzaServiceInitializer initialization class, an example of which can be found in the fat-jar Main.

Note that this approach does not include client REST endpoints unless AmzaClientRestEndpoints is specifically injected as shown in the example. This behavior is optional, and it is left to the embedding application to enable usage as desired.

Additionally, the Amza UI can be made available by depending on the com.jivesoftware.os.amza:amza-ui artifact, which provides the AmzaUIInitializer initialization class (example provided).

Amza client library and REST API

A reference client implementation written in Java is available by depending on the com.jivesoftware.os.amza:amza-client artifact. In general, partition-specific instances of PartitionClient can be obtained from an instance of AmzaClientProvider, an example construction of which can be found in the fat-jar Main class (see above).

The reference partition client is a thread-safe, routing-aware implementation that identifies and caches ring and leadership information for the target partition, enabling worry-free interaction with the Amza cluster. The following API is supported:

• Commit: Write key-value transactions to the partition.
• GetApproximateCount: Retrieves a rough estimate of the number of keys in a partition.
• Get: Gets the value, timestamp, and version for one or more keys (point get).
• Scan: Gets the key, value, timestamp, and version for all entries in a key range.
• ScanKeys: Get the key for all entries in a key range.
• TakeFromTransactionId: Takes log-ordered payloads from a member-aligned set of transaction IDs. This operation is cursor-based and returns a cursor update.
• TakePrefixFromTransactionId: Like the above, but takes only keys with a specific prefix.