Skip to content

Latest commit

 

History

History
148 lines (82 loc) · 6.38 KB

DEVELOPERS.md

File metadata and controls

148 lines (82 loc) · 6.38 KB

This document contains a technical overview of this project for development. For instructions on using this client, see the README.

Javadocs

The Javadocs contain detailed information about each class. They can be built using:

mvn javadoc:javadoc

Then open target/site/apidocs/index.html.

Bundling

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.

Overview

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 --Response classes

Classes

Example

A typical fetch for an object from the Riak HTTP interface is handled as follows:

  1. User calls RiakClient.fetch(...)

  2. Calls ClientHelper.fetch(...) which builds the HttpMethod

  3. Calls ClientHelper.executeMethod(...) which executes the method and fetches the response with getResponseBodyAsString()

  4. RiakClient.fetch(...) constructs a FetchResponse from the response

  5. FetchResponse parses the response and constructs a RiakObject

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.

Serialization/Parsing

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.

Client Interface

Users primarily use RiakClient/RiakObject. 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 --Response.

Development

Unit Tests

The unit tests exercise the code. The coverage for the unit tests can be obtained by running

mvn cobertura:cobertura

Then browse to

riak-java-client/target/site/cobertura/index.html

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.

Integration Tests

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

-DargLine="-Dcom.basho.riak.search=true"

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

-DargLine="-Dcom.basho.riak.2i=true"

Code Format

The files eclipse-cleanup-profile.xml and 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.

Releasing

Sonatype Access

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>

Deploying Snapshots

At this point, SNAPSHOT artifacts can be deployed by simply running:

mvn clean deploy

Deploying Releases

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:

  1. Edit pom.xml to reflect the correct scm.connection and scm.developerConnection and check in.

  2. 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>

  3. Run

     gpg-agent --use-standard-socket --daemon 2>/dev/null

  4. 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.