graceland-core Documentation...A quick guide to getting started using Graceland, using the example of a counting machine, and resources and tasks that use a CountingMachine singleton

graceland-core DocumentationRelease 0.1.0-SNAPSHOT

Javier Campanini

April 14, 2014

Contents

1 About 31.1 Contributing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2 Overview 52.1 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.2 Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.3 Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

3 Getting Started 73.1 Step 1 - Silly Counting Machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73.2 Step 3 - Wire It Up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83.3 Step 4 - Resources, Tasks & Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83.4 Step 5 - Building the Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93.5 Step 6 - Add a New Machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113.6 Step 7 - Switch It Up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

4 Plugins 134.1 Why Plugins? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134.2 Plugins vs. Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134.3 Writing Your First Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134.4 A Sample Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134.5 Plugin Loaders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

5 Applications 155.1 Simple Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155.2 Modal Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155.3 Custom Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

6 Configurations 176.1 Binding a Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

7 Platform 197.1 Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197.2 Platform Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

8 Escape Hatches 218.1 How We Use Dropwizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218.2 Configurator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

i

8.3 Initializer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

9 Metrics Graphite 239.1 Host-Aware Graphite Reporter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

10 Indices and tables 25

ii

graceland-core Documentation, Release 0.1.0-SNAPSHOT

Contents:

Contents 1


2 Contents

CHAPTER 1

About

1.1 Contributing

We’re on github, so just head over there, fork the repo, and submit a pull request.

While Test-Driven Development is not strictly required, it is highly encouraged, and at the very least, a high degree oftest coverage is.

1.2 License

Graceland is licensed under the Apache License v2.0. See the LICENSE file for more details.

3

https://github.com/jmcampanini/graceland-core

http://www.apache.org/licenses/LICENSE-2.0.txt


4 Chapter 1. About

CHAPTER 2

Overview

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et do-lore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex eacommodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nullapariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id estlaborum.

2.1 Motivation

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magnaaliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sintoccaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

2.2 Architecture


2.3 Modules


5


6 Chapter 2. Overview

CHAPTER 3

Getting Started

A quick guide to getting started using Graceland, using the example of a counting machine, and resources andtasks that use a CountingMachine singleton.

3.1 Step 1 - Silly Counting Machine

For this example, we’ll create a silly counting machine that will keep count and can be represented in JSON, like thefollowing:

{"count": 4,"timestamp: 1396591214348

}

You can do this by creating a simple POJO representation of the counter:

public class Counter {private final long count;private final DateTime timestamp;

public Counter(long count, DateTime timestamp) {this.count = count;this.timestamp = timestamp;

}

public long getCount() { return count; }

public DateTime getTimestamp() { return timestamp; }}

And the interface that for the counting machine:

package io.graceland.example.counting;

public interface CountingMachine {

void increment();

void resetCount();

Counter getCurrentCount();}

7


This should be enough of a toy example to shed some light on Graceland’s plugins.

3.2 Step 3 - Wire It Up

Now let’s create a simple implementation of the CountingMachine:

public class SimpleCountingMachine implements CountingMachine {

private final AtomicLong count = new AtomicLong();

@Overridepublic void increment() { count.incrementAndGet(); }

@Overridepublic void resetCount() { count.set(0); }

@Overridepublic Counter getCurrentCount() {

return new Counter(count.get(), DateTime.now());}

}

And lets wire it up inside of an Plugin:

public class SimpleCountingPlugin extends AbstractPlugin {

@Overrideprotected void configure() {

// hook up the counting machinebind(CountingMachine.class).to(SimpleCountingMachine.class).in(Singleton.class);

}}

Whenever we include this SimpleCountingPlugin, we’ll be telling Guice to use theSimpleCountingMachine implementation wherever it needs a CountingMachine.

You can look into the Guice documentation if you need more information.

3.3 Step 4 - Resources, Tasks & Plugins

Now that we have a counting machine, we need to expose it through a RESTful endpoint. We can do that with thefollowing class. Notice how the CountingMachine is injected into the constructor.

@Path("/api/example")public class ExampleResource {

private final CountingMachine countingMachine;

@InjectExampleResource(CountingMachine countingMachine) {

this.countingMachine = countingMachine;}

@Timed@GET

8 Chapter 3. Getting Started


@Produces(MediaType.APPLICATION_JSON)public Counter getCurrentCount() {

countingMachine.increment();return countingMachine.getCurrentCount();

}}

We also want to add a Dropwizard Task to help us clear the counting machine whenever we want. We can inject thesame CountingMachine here as well:

public class ResetTask extends Task {

private final CountingMachine countingMachine;

@InjectResetTask(CountingMachine countingMachine) {

super("reset");this.countingMachine = countingMachine;

}

@Overridepublic void execute(ImmutableMultimap<String, String> stringStringImmutableMultimap, PrintWriter printWriter) throws Exception {

countingMachine.resetCount();

printWriter.println("Count Reset!");printWriter.flush();

}}

Now let’s add the Task and Resource to our web service:

public class ExamplePlugin extends AbstractPlugin {


// add the resourcebindJerseyComponent(ExampleResource.class);

// add the taskbindTask(ResetTask.class);

}}

This should be enough for you to start wiring up a simple application!

3.4 Step 5 - Building the Application

Now we’ll need both of those plugins to wire up our application. We can extend the SimpleApplication for thisexample, and load the plugins explictly:

public class ExampleApplication extends SimpleApplication {


loadPlugin(new ExamplePlugin());loadPlugin(new SimpleCountingPlugin());

3.4. Step 5 - Building the Application 9


}}

To run the application, we just add a public static void main(String[] args) method and run it fromour IDE:

public static void main(String[] args) throws Exception {Platform

.forApplication(new ExampleApplication())

.start(args);}

You’ll receive a message, listing the commands available. Create a configuration file platform.yml to tell grace-land where to start up the server:

server:applicationConnectors:

- type: httpport: 8080

And then re-run the application with the following command line arguments: server platform.yml

Note: Make sure the current working directory contains the platform.yml file.

You should see text similar to the following:

INFO [2014-04-04 06:38:55,065] io.dropwizard.server.ServerFactory: Starting PlatformINFO [2014-04-04 06:38:55,127] org.eclipse.jetty.setuid.SetUIDListener: Opened application@24a06fb1{HTTP/1.1}{0.0.0.0:8080}INFO [2014-04-04 06:38:55,128] org.eclipse.jetty.setuid.SetUIDListener: Opened admin@2104e040{HTTP/1.1}{0.0.0.0:8081}INFO [2014-04-04 06:38:55,130] org.eclipse.jetty.server.Server: jetty-9.0.7.v20131107INFO [2014-04-04 06:38:55,225] com.sun.jersey.server.impl.application.WebApplicationImpl: Initiating Jersey application, version ’Jersey: 1.18.1 02/19/2014 03:28 AM’INFO [2014-04-04 06:38:55,291] io.dropwizard.jersey.DropwizardResourceConfig: The following paths were found for the configured resources:

GET /api/example (io.graceland.example.ExampleResource)

INFO [2014-04-04 06:38:55,505] org.eclipse.jetty.server.handler.ContextHandler: Started i.d.j.MutableServletContextHandler@3ba6d328{/,null,AVAILABLE}INFO [2014-04-04 06:38:55,506] io.dropwizard.setup.AdminEnvironment: tasks =

POST /tasks/gc (io.dropwizard.servlets.tasks.GarbageCollectionTask)POST /tasks/reset (io.graceland.example.ResetTask)

WARN [2014-04-04 06:38:55,507] io.dropwizard.setup.AdminEnvironment:!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! THIS APPLICATION HAS NO HEALTHCHECKS. THIS MEANS YOU WILL NEVER KNOW !! IF IT DIES IN PRODUCTION, WHICH MEANS YOU WILL NEVER KNOW IF YOU’RE !! LETTING YOUR USERS DOWN. YOU SHOULD ADD A HEALTHCHECK FOR EACH OF YOUR !! APPLICATION’S DEPENDENCIES WHICH FULLY (BUT LIGHTLY) TESTS IT. !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!INFO [2014-04-04 06:38:55,511] org.eclipse.jetty.server.handler.ContextHandler: Started i.d.j.MutableServletContextHandler@5ae9fa73{/,null,AVAILABLE}INFO [2014-04-04 06:38:55,525] org.eclipse.jetty.server.ServerConnector: Started application@24a06fb1{HTTP/1.1}{0.0.0.0:8080}INFO [2014-04-04 06:38:55,526] org.eclipse.jetty.server.ServerConnector: Started admin@2104e040{HTTP/1.1}{0.0.0.0:8081}

You can finally test it out: http://127.0.0.1:8080/api/example


http://127.0.0.1:8080/api/example


3.5 Step 6 - Add a New Machine

Now lets extend our application by adding a new CountingMachine implementation. This time, we’ll use one thatuses a configuration file to set itself up.

First, lets make a configuration file, starting-up.yml:

startingOn: 500

Now let’s make a configuration class to represent the values as a POJO.

public class StartingOnConfiguration implements io.graceland.configuration.Configuration {

private final long startingOn;

@JsonCreatorpublic StartingOnConfiguration(@JsonProperty("startingOn") long startingOn) {

this.startingOn = startingOn;}

public long getStartingOn() { return startingOn; }}

Using the configuration, let’s build another CountingMachine. It’s very similar to our earlier version, but this onehas a constructor where the StartingOnConfiguration is injected into.

public class StartingOnCountingMachine implements CountingMachine {

private final AtomicLong count;

@InjectStartingOnCountingMachine(StartingOnConfiguration configuration) {

// use the configuration to get the starting on countcount = new AtomicLong(configuration.getStartingOn());

}

@Overridepublic void increment() { count.incrementAndGet(); }

@Overridepublic void resetCount() { count.set(0); }

@Overridepublic Counter getCurrentCount() {

return new Counter(count.get(), DateTime.now());}

}

and finally the plugin to bind the CountingMachine and to tell Graceland what file to use for the configuration.

public class StartingOnCountingPlugin extends AbstractPlugin {


// hook up the counting machinebind(CountingMachine.class).to(StartingOnCountingMachine.class).in(Singleton.class);

// bind the configuration file to the classbindConfiguration(StartingOnConfiguration.class).toFile("starting-on.yml");

3.5. Step 6 - Add a New Machine 11


}}

Note: The configuration files look for the files relative to the current working directory (cwd). If you’re running intotrouble finding a configuration file, check to see what the cwd is.

Now let’s see how we can bring this new CountingMachine into our application.

3.6 Step 7 - Switch It Up

We can simply swap out the plugin being loaded!


loadPlugin(new ExamplePlugin());

// replace the simple with the StartingOn// loadPlugin(new SimpleCountingPlugin());loadPlugin(new StartingOnCountingPlugin());

}

And now when you check out the URL, you’ll see the counting machine starts at the configured value.


CHAPTER 4

Plugins


4.1 Why Plugins?


4.2 Plugins vs. Modules


4.3 Writing Your First Plugin


4.4 A Sample Plugin


13


4.5 Plugin Loaders


4.5.1 Native Plugin Loader


14 Chapter 4. Plugins

CHAPTER 5

Applications

The purpose of the Application is to manage the list of plugins that define your application. The two primarypieces of functionality are loadPlugin and getPlugins.

5.1 Simple Applications

A simple plugin provides the most basic implementation of an application. It provides a configure() method soyou can define the plugins to load.

5.2 Modal Applications

You may want an application to end up having different modes of operation - loading different plugins while in thestaging environment vs. the production environment. It would be ideal for swapping out implementations that areeither not present or not deployed in a given environment.

If you want different modes, you can extend the io.graceland.application.ModalApplication class,and use your own enum to define the different modes.

Note: You’ll need to provide a default mode for the application in the constructor. Choosing a production-ready modewould make deploying to a production environment that much less complicated.

Instead of using the configure() method, you will use the configureFor(Enum<?> Mode) so you can loaddetermine what to do based on the mode.

public class SampleModalApplication extends ModalApplication<SampleModes> {

protected SampleModalApplication(String[] args) {// it helps to pass in a reference to the class, and the default// mode of the applicationsuper(SampleModes.class, SampleModes.PROD, args);

}

@Overrideprotected void configureFor(SampleModes mode) {

// load plugins that will be used in all modesloadPlugin(new SamplePlugin());

switch (mode) {

15


case DEV:// do dev stuffloadPlugin(new SampleDevPlugin());

case PROD:// do prod stuffloadPlugin(new SampleProdPlugin());

}}

}

5.2.1 Choosing a Mode

To tell your application what mode to run in, add a command line argument with a leading double-dash and the modeenum name. For example: --DEV will match up to the enum value DEV.

If no value is passed in, the default mode is used.

Note: The mode passed in the command line is case-sensitive.

5.3 Custom Applications

If the provided applications do not provide the functionality needed, you can extend them or write your own imple-mentation of the io.graceland.application.Application interface.

16 Chapter 5. Applications

CHAPTER 6

Configurations


6.1 Binding a Configuration


17


18 Chapter 6. Configurations

CHAPTER 7

Platform

The graceland-platform module provides everything you’ll need to build out modular Dropwizard applica-tions.

7.1 Platform


7.2 Platform Configuration


19


20 Chapter 7. Platform

CHAPTER 8

Escape Hatches

Graceland is built on top of the dropwizard platform and tries to wrap up the functionality so your plugins don’tneed to deal directly with it. Because we can’t begin to pretend that we’ll cover all of your use cases, we’veprovided some escape hatches so you could access the low-level dropwizard functionality when needed.

8.1 How We Use Dropwizard

A dropwizard application has two primary phases: initialize and run. Graceland provides access to the drop-wizard components in each of those phases.

public class Platform extends io.dropwizard.Application<PlatformConfiguration> {@Overridepublic void initialize(Bootstrap<PlatformConfiguration> bootstrap) {

// run the Initializers and other code}

@Overridepublic void run(PlatformConfiguration configuration, Environment environment) throws Exception {

// run the Configurators and other code}

}

8.2 Configurator

Configurators are triggered during the run phase of the dropwizard application. It provides access to two importantlow level components:

• configuration - the application’s configuration.

• environment - an io.dropwizard.setup.Environment, which provides access to the underlyingframeworks, such as jetty, jersey, and the metrics registry.

Most of the work done in a dropwizard application is done during the run phase, so the majority of the custom codewill come in the form of a Configurator.

public class SampleConfigurator implements Configurator {@Overridepublic void configure(PlatformConfiguration configuration, Environment environment) {

// example of adding a filter directly to the environmentenvironment.servlets().addFilter(...)

21


}}

8.3 Initializer

If you need access to the a io.dropwizard.setup.Bootstrap, you can use an Initializer. This phaseis usually used to add commands and bundles to a dropwizard applicataion.

public class SampleInitializer implements Initializer {@Overridepublic void initialize(Bootstrap<PlatformConfiguration> bootstrap) {

// add a configured commandbootstrap.addCommand(...);

}}

22 Chapter 8. Escape Hatches

CHAPTER 9

Metrics Graphite

The graceland-metrics-graphite module provides a metrics reporting factory that automatically uses thehostname in the prefix.

9.1 Host-Aware Graphite Reporter

Reports metrics periodically to Graphite. The prefix provided may include a variable %s that will be replaced with thecurrent machine’s host name. This is so each instance of the service will have a different prefix, letting you differentiateeach machine’s activity, while still letting you roll them up using Graphite.

Note: If no hostname can be determined, the variable is removed and any double dots .. will be replaced with singledots.

Note: All non-alphanumeric characters (including dots) in the hostname will be replaced with an underscore _ toensure graphite does not break down the hostname variable.

9.1.1 Configuration

Extends the attributes that are available to the graphite reporter. See the graphite reporter documentation for moredetails.

metrics:reporters:

- type: graphite-hostawarehost: localhostport: 8080prefix: <prefix>

Name Default Descriptionhost localhost The hostname of the Graphite server to report to.port 8080 The port of the Graphite server to report to.prefix (none) The prefix for Metric key names to report to Graphite.

23

http://dropwizard.github.io/dropwizard/manual/configuration.html#graphite-reporter


24 Chapter 9. Metrics Graphite

CHAPTER 10

Indices and tables

• genindex

• modindex

• search

25

Documents

graceland-core Documentation...A quick guide to getting started using Graceland, using the example of a counting machine, and resources and tasks that use a CountingMachine singleton