dropwizard-couchbase

Build Status: Coverage Status: Stories Ready:

Introduction

dropwizard-couchbase is a Dropwizard bundle for Couchbase persistence.

The current version is 0.9.1 and it has the following dependencies:

io.dropwizard dropwizard-core 1.1.1 (provided)
com.couchbase.client couchbase-client 2.4.5 (compile time)

dropwizard-couchbase is compiled against JDK 8.

Quickstart

Dependencies

Add the following dependency to your build.gradle

dependencies {
  compile "io.smartmachine:dropwizard-couchbase:0.9.1"
}

or pom.xml

<project>
  ...
  <dependencies>
    <dependency>
      <groupId>io.smartmachine</groupId>
      <artifactId>dropwizard-couchbase</artifactId>
      <version>0.9.1</version>
      <scope>runtime</scope>
    </dependency>
  </dependencies>
</project>

Add bundle

Add a CouchbaseBundle to your Application class:

package io.sample;

import io.dropwizard.Application;
import io.dropwizard.setup.Bootstrap;
import io.dropwizard.setup.Environment;
import io.smartmachine.couchbase.CouchbaseBundle;

public class ConfigurationServer extends Application<ConfigurationServerConfig> {

    public static void main(String[] args) throws Exception {
        new ConfigurationServer().run(args);
    }

    private final CouchbaseBundle<ConfigurationServerConfig> couchbaseBundle = new CouchbaseBundle<ConfigurationServerConfig>() {

        @Override
        public CouchbaseClientFactory getCouchbaseClientFactory(ConfigurationServerConfig configuration) {
            return configuration.getCouchbaseClientFactory();
        }
    };

    @Override
    public void initialize(Bootstrap<ConfigurationServerConfig> bootstrap) {
        bootstrap.addBundle(couchbaseBundle);
    }

    @Override
    public void run(ConfigurationServerConfig configuration, Environment environment) throws Exception {
        // Register all your resources here as usual
    }

    @Override
    public String getName() {
        return "configuration-server";
    }
}

Implement your configuration class.

package io.smartmachine.cs;

import com.fasterxml.jackson.annotation.JsonProperty;
import io.dropwizard.Configuration;
import org.hibernate.validator.constraints.NotEmpty;

import javax.validation.Valid;
import javax.validation.constraints.NotNull;

class ConfigurationServerConfig extends Configuration {

    // All your usual setup goes here
    
    @Valid
    @NotNull
    private CouchbaseClientFactory ccf = new CouchbaseClientFactory();

    @JsonProperty("couchbase")
    public CouchbaseClientFactory getCouchbaseClientFactory() {
        return ccf;
    }

    @JsonProperty("couchbase")
    public void setCouchbaseClientFactory(CouchbaseClientFactory ccf) {
        this.ccf = ccf;
    }
}

Configuration

Add the following to your yaml configuration file:

# Your server configuration
server:
  applicationConnectors:
    - type: http
      port: 9000
  adminConnectors:
    - type: http
      port: 9001

# Default Couchbase Configuration
couchbase:
  bucket: default
  hosts:
    - http://localhost:8091/pools
  password: ""

If you don't add a couchbase configuration section to your yaml the defaults (above) will be assumed. More CouchbaseClient configuration options will be added in the future.

Implementation

Automatic DAO generation

dropwizard-couchbase will autogenerate DAO implementation classes and views for you to facilitate standard CRUD operations.

We assume that you have a standard dropwizard resource class as well as a model class with the appropriate JsonProperty and JsonCreator annotations for Jackson de/serialization. Let's look at such a class, called Device.java:

package io.sample.api;

import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonProperty;
import org.hibernate.validator.constraints.Length;
import org.hibernate.validator.constraints.NotEmpty;

import java.util.List;

public class  Device {

    @Length(min = 12, max=12)
    @NotEmpty
    private final String serial;

    private List<String> modules;

    @JsonCreator
    public Device(@JsonProperty("serial") String serial) {
        this.serial = serial;
    }

    @JsonProperty
    public void setModules(List<String> modules) {
        this.modules = modules;
    }

    @JsonProperty
    public List<String> getModules() {
        return modules;
    }

    @JsonProperty
    public String getSerial() {
        return serial;
    }

}

In order to enable automatic DAO generation you need to write an Accessor interface (similar to DAO class/interface in JPA/Hibernate):

package io.sample.api;

import io.smartmachine.couchbase.GenericAccessor;
import io.smartmachine.couchbase.CouchbaseView;

import java.util.List;

public interface DeviceAccessor extends GenericAccessor<Device> {

    @ViewQuery("/^DEVICE/.test(meta.id)")
    public List<Device> findAll();

}

The findall() method will be autogenerated. The @ViewQuery annotation will generate a Couchbase Design Document called DEVICE with a view called findAll like so:

function (doc, meta) {
  if (/^DEVICE/.test(meta.id)) {
    emit(meta.id, null);
  }
}

The emit statement can be controlled as well, emit(meta.id, null) is the default. The following annotation will generate a view that emits full documents: @ViewQuery("/^DEVICE/.test(meta.id)", emit = "emit(meta.id, doc)"). Note that the name of the Design Document will be your model class .toUpperCase().

The extended GenericAccessor<Device> interface has the following contract, all methods will be automatically implemented:

package io.smartmachine.couchbase;

public interface GenericAccessor<T>  {

    void create(String id, T newinstance);
    T read(String id);
    void update(String id, T object);
    void delete(String id);
    void set(String id, T object);

}

Note that this is CRUD plus an extra set operation to conform with the provided methods of CouchbaseClient.

The last step is to annotate your Resource class as follows:

package io.sample.resources;

import com.codahale.metrics.annotation.Timed;
import io.sample.api.Device;
import io.sample.api.DeviceAccessor;
import io.smartmachine.couchbase.Accessor;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import javax.validation.Valid;
import javax.ws.rs.*;
import javax.ws.rs.core.MediaType;
import java.util.List;

@Path("/devices")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class DeviceResource {

    private static final Logger log = LoggerFactory.getLogger(DeviceResource.class);

    // Note the Accessor annotation
    @Accessor
    private DeviceAccessor accessor;

    private final List<String> defaultModules;

    public DeviceResource(List<String> defaultModules) {
        this.defaultModules = defaultModules;
    }

    @GET
    @Path("{id}")
    @Timed
    public Device devices(@PathParam("id") String id) {
        return accessor.read(id);
    }

    @GET
    @Timed
    public List<Device> all() {
        return accessor.findAll();
    }

    @PUT
    @Path("{id}")
    @Timed
    public Device add(@PathParam("id") String id, @Valid Device device) {
        if (device.getModules() == null || device.getModules().size() == 0) {
            device.setModules(defaultModules);
        }
        accessor.create(id, device);
        return device;
    }

}

Note the @Accessor annotation in the above example. dropwizard-couchbase will inject an implementation of DeviceAccessor for you to use in your Resource class.

Manual usage of CouchbaseClient

If you want to do some more low-level stuff with CouchbaseClient you can use the following annotation in your Resource class in stead:

import io.smartmachine.couchbase.CouchbaseClientFactory;
import io.smartmachine.couchbase.ClusterManager

public class DeviceResource {

    @Accessor
    private CouchbaseClientFactory factory;

    @GET
    @Path("{id}")
    @Timed
    public Device devices(@PathParam("id") String id) {
        CouchbaseClient client = factory.client();
        // and / or
        ClusterManager manager = factory.getClusterManager();
    }

    ...
    
}

Roadmap for version 0.9.2

Implement full set of configuration options for CouchbaseClientFactory
Implement proper Couchbase health checks and metrics
Finish out unit tests
Update Javadocs

Contributors

Pull requests are very welcome. Create issues in the Github issue system for this repository against any bugs/feature requests.

License

dropwizard-couchbase is released under the MIT license.

smartmachine / dropwizard-couchbase