This document contains a technical overview of this project for development. For instructions on using this client, see the README.
The Javadocs contain detailed information about each class. They can be built using:
As a convenience you can have maven build a zip/tar.gz/bz2 archive with the client .jar and all dependencies and/or a all-in-one .jar by adding -Dbundle.archives -Dbundle.fat respectively to the mvn command.
The most important classes are:
ClientHelper: executes HTTP methods
RiakObject: Java representations of a Riak object capable of serializing to an HTTP request
--Response classes: parse HTTP responses from Riak
RiakClient: calls ClientHelper and wraps responses in
A typical fetch for an object from the Riak HTTP interface is handled as follows:
ClientHelper.fetch(...)which builds the
ClientHelper.executeMethod(...)which executes the method and fetches the response with
FetchResponsefrom the response
FetchResponseparses the response and constructs a
The other operations follow the same basic flow: Client -> ClientHelper -> Response.
Executing HTTP Methods
The heart of the client is
ClientHelper. It builds and executes the HTTP methods corresponding to each operation. The
executeMethod() method performs the HTTP operation using Commons HttpClient and retrieves the response.
While the HTTP operations are performed by ClientHelper, the majority of the work actually consists of serializing objects and parsing the HTTP responses from Riak. Serialization of objects to send to Riak is performed by
RiakObject.writeToHttpMethod(...). Responses are parsed by the
--Response classes which read the
HttpResponse returned by
ClientHelper and construct the appropriate domain objects.
Users primarily use
RiakClient is a simple adapter from
ClientHelper to the
RiakClient interface. It uses
ClientHelper to execute the HTTP methods and wraps the resulting response with the proper
The unit tests exercise the code. The coverage for the unit tests can be obtained by running
Then browse to
to see the coverage report. Coverage is currently ~66%. It should only go up from here. If you add code, add a test. If you fix a bug, add a test.
The integration tests perform each of the basic operations (store bucket schema, list bucket, store, fetch, modify, walk, map/reduce) against a running Riak instance. They can be run using:
mvn -Pitest clean verify
Riak must be running on
127.0.0.1:8098 with the HTTP interface located at
/riak. Note that prior to Riak 0.9, the HTTP interface was located at
/raw by default. The integration tests expect to find the protobuffers interface at '127.0.0.1:8087'
If you want to run the integrattion tests against a Riak that is running on a different host/ports then you can do so by specifying host/port information in the "argLine" argument. You only need to specify
mvn -Pitest clean verify -DargLine="-Dcom.basho.riak.host=10.0.1.5 -Dcom.basho.riak.http.port=8091 -Dcom.basho.riak.pbc.port=8081"
If you do have Riak Search enabled, then you can enable the search integration tests by adding the following property to the -DargLine
If you do have the eleveldb backend configured, then you can enable the secondary indexes integration tests by adding the following property to the -DargLine
eclipse-format-profile.xml are provided to be used with Eclipse. Import them using Preferences > Java > Code Style > Clean Up and ... > Formatter. New code can be formatted like the current code using the Source > Clean Up... feature.
Artifacts are deployed to the Sonatype OSS Nexus repository, which is synchronized with the Maven Central Repository. Therefore, in order to deploy you must have a Sonatype account with write permission to the repository. First, sign up for an account on the Sonatype Nexus homepage (link on upper right of page). Next, send me a message with your account name to request access to the repository.
Once you have the proper permissions, place the following blob inside
~/.m2/settings.xml. You may need to create this file.
<settings> <servers> <server> <id>sonatype-nexus-snapshots</id> <username>your-sonatype-username</username> <password>your-sonatype-password</password> </server> <server> <id>sonatype-nexus-staging</id> <username>your-sonatype-username</username> <password>your-sonatype-password</password> </server> </servers> </settings>
At this point, SNAPSHOT artifacts can be deployed by simply running:
mvn clean deploy
Releases are more complicated because they must be properly signed. Follow the instructions here to set up GPG locally. Once that is done, to release:
Edit pom.xml to reflect the correct scm.connection and scm.developerConnection and check in.
Run the Maven release:prepare goal until it succeeds
# Note: this command pushes to bitbucket! mvn release:prepare -Dresume=true -Dusername=<bitbucket-username> -Dpassword=<bitbucket-password>
gpg-agent --use-standard-socket --daemon 2>/dev/null
In the same terminal, run
mvn release:perform -Dgpg.passphrase=<gpg-password> -Darguments="-Dgpg.passphrase=<gpg-password>"
If the release succeeds, you should be able to log in to Sonatype and see the new artifact in the Staging section. Right click and choose "Close" to approve the artifact to be synchronized to Maven Central.