A file system or S3 backed Pairtree library for the Vert.x tool-kit.
Clone or download
ksclarke Merge 'develop' branch (#21)
* Rename S3 IT profile
* Add JDK 9,10, 11 to Travis build
* Update dependencies for security fix
* Update Travis config
* Update PMD rules
* Write tests to separate S3 buckets in Travis
* Update docs with Travis S3 bucket example
Latest commit b2ea1e3 Jan 10, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src Merge 'develop' branch (#21) Jan 11, 2019
.gitignore Initial commit Aug 3, 2016
.travis.yml Merge 'develop' branch (#21) Jan 11, 2019
LICENSE.txt Change license to BSD-3-Clause Nov 12, 2018
README.md Merge 'develop' branch (#21) Jan 11, 2019
pom.xml Merge 'develop' branch (#21) Jan 11, 2019

README.md

vertx-pairtree  Build Status Codacy Badge Known Vulnerabilities Maven Javadocs

A file system or S3 backed Pairtree library for use with the Vert.x tool-kit. To use it, include its Jar file in your project's classpath.

Getting Started

To check out and build the project, type on the command line:

git clone https://github.com/ksclarke/vertx-pairtree.git
cd vertx-pairtree
mvn install

This will run the build and the unit tests for the file system back end. Right now, the only tests for the S3 back end are integration tests. To run a build with them, you will need to put the following properties in your settings.xml file and run the build with the s3it profile:

<vertx.pairtree.bucket>YOUR_S3_BUCKET_NAME</vertx.pairtree.bucket>
<vertx.pairtree.access_key>YOUR_ACCESS_KEY</vertx.pairtree.access_key>
<vertx.pairtree.secret_key>YOUR_SECRET_KEY</vertx.pairtree.secret_key>

Or, you can supply the required properties on the command line (with the same s3it profile) when you build the project:

mvn install -Ps3it -Dvertx.pairtree.bucket=YOUR_S3_BUCKET_NAME \
  -Dvertx.pairtree.access_key=YOUR_ACCESS_KEY \
  -Dvertx.pairtree.secret_key=YOUR_SECRET_KEY

The YOUR_S3_BUCKET_NAME, YOUR_ACCESS_KEY and YOUR_SECRET_KEY values obviously need to be replaced with real values. Within AWS' Identity and Access Management service you can configure a user that has permission to perform actions on the S3 bucket you've created for this purpose. For an example of the IAM inline user policy for an S3 bucket, consult the example JSON file in the project's src/test/resources directory.

You can name the S3 bucket whatever you want (and change its system property to match), but make sure the bucket is only used for these integration tests. The tests will delete all the contents of the bucket as a part of the test tear down. When these tests are run in Travis, a JDK name is appended onto the S3 bucket name so that the tests can be run concurrently (e.g. YOUR_S3_BUCKET_NAME-openjdk11). These buckets also need to be created ahead of time in order for the tests to pass.

If you want to put your test S3 bucket in a region other than the standard us-east-1, you will also need to supply a vertx.pairtree.region argument. For example:

mvn install -Ps3it -Dvertx.pairtree.bucket=YOUR_S3_BUCKET_NAME \
  -Dvertx.pairtree.access_key=YOUR_ACCESS_KEY \
  -Dvertx.pairtree.secret_key=YOUR_SECRET_KEY \
  -Dvertx.pairtree.region="us-west-2"

It can also be supplied through your settings.xml file. At this point, only regions that support signature version 2 authentication are supported. To see the valid S3 region endpoints, consult AWS' documentation.

Lastly, if you don't want to build it yourself, the library can be downloaded from the Maven central repository by putting the following in your project's pom.xml file:

<dependency>
  <groupId>info.freelibrary</groupId>
  <artifactId>vertx-pairtree</artifactId>
  <version>${vertx.pairtree.version}</version>
</dependency>

Acknowledgements

In addition to all the dependencies listed in the pom.xml file, this project incorporates a Pairtree implementation from the Library of Congress and a Vert.x S3Client from the SuperS3t project. The licenses for their use are included in the headers of their Java files. Both have been modified from their original versions.

Contact

If you have questions about vertx-pairtree feel free to ask or, if you encounter a problem, please feel free to open a ticket in the project's issues queue.