graceland-core Documentation · Combining these two frameworks - Dropwizard and Guice - you can...
Transcript of graceland-core Documentation · Combining these two frameworks - Dropwizard and Guice - you can...
graceland-core DocumentationRelease 0.1.0
Javier Campanini
June 02, 2014
Contents
1 Overview 31.1 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2 Getting Started 52.1 Step 0 - Depending On It . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.2 Step 1 - Silly Counting Machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.3 Step 3 - Wire It Up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.4 Step 4 - Resources, Tasks & Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.5 Step 5 - Building the Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82.6 Step 6 - Add a New Machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92.7 Step 7 - Switch It Up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3 Plugins 133.1 Why Plugins? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133.2 Plugins vs. Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133.3 A Sample Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133.4 Plugin Loaders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4 Applications 154.1 Simple Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154.2 Modal Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154.3 Custom Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
5 Configurations 175.1 Binding a Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
6 Filters 196.1 FilterBinder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196.2 An Example Binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
7 Platform 217.1 Platform Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
8 Escape Hatches 238.1 How We Use Dropwizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238.2 Configurator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238.3 Initializer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
i
9 Metrics Graphite 259.1 Host-Aware Graphite Reporter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
10 Frequently Asked Questions 2710.1 Contributing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2710.2 License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
11 Indices and tables 29
ii
graceland-core Documentation, Release 0.1.0
Contents:
Contents 1
graceland-core Documentation, Release 0.1.0
2 Contents
CHAPTER 1
Overview
Graceland is a modular web application framework. It combines some powerful frameworks to achieve it’sgoals. These frameworks include: Dropwizard and Guice.
1.1 Motivation
Graceland was written because Dropwizard is amazing, but it’s not very easy to build a modular application with it.There is only a single Configuration available to a service, so swapping between different components gets prettytedious.
Guice is a pretty amazing framework for Dependency Injection, and it makes building modular applications a heck ofa lot easier and managable. There’s just one, large, easy to understand and manage Dependency Graph that is used tobuild your application.
Combining these two frameworks - Dropwizard and Guice - you can build a pretty functional framework for quicklybuilding modular, easy to maintain and upgrade web applications.
The goal of Graceland is to stay out of your way and let you develop. Hopefully Graceland you’ll find Gracelanduseful.
1.2 Modules
The graceland-core project consists of the following sub-modules:
• graceland-example - An example project that uses as much of graceland as possible.
• graceland-metrics-graphite - a Metrics Reporter for graphite that uses your host in the prefix.
• graceland-platform - The Graceland Platform. Use this to build your application with.
3
graceland-core Documentation, Release 0.1.0
4 Chapter 1. Overview
CHAPTER 2
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.
2.1 Step 0 - Depending On It
Graceland is currently publishing to both the Sonatype Snapshot Central Repository and Maven Central.
The versions currently available are:
• Stable: 0.1.0 - available on Maven Central
• Development: 0.2.0-SNAPSHOT - available on Sonatype Snapshot
Maven Instructions:
<!-- This is only necessary if you plan on using a SNAPSHOT version --><repositories>
<repository><id>Sonatype Snapshots</id><url>https://oss.sonatype.org/content/repositories/snapshots/</url>
</repository></repositories>
<dependencies><dependency>
<groupId>io.graceland</groupId><artifactId>graceland-platform</artifactId><version>${graceland.version}</version>
</dependency><dependencies>
Gradle Instructions:
repositories {mavenCentral()
// This is only necessary if you plan on using a SNAPSHOT versionmaven {
url "https://oss.sonatype.org/content/repositories/snapshots/"}
}
dependencies {
5
graceland-core Documentation, Release 0.1.0
compile "io.graceland:graceland-platform:$gracelandVersion"}
2.2 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();}
This should be enough of a toy example to shed some light on Graceland’s plugins.
2.3 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(); }
6 Chapter 2. Getting Started
graceland-core Documentation, Release 0.1.0
@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.
2.4 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@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;
@Inject
2.4. Step 4 - Resources, Tasks & Plugins 7
graceland-core Documentation, Release 0.1.0
ResetTask(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 {
@Overrideprotected void configure() {
// add the resourcebindJerseyComponent(ExampleResource.class);
// add the taskbindTask(ResetTask.class);
}}
This should be enough for you to start wiring up a simple application!
2.5 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 {
@Overrideprotected void configure() {
loadPlugin(new ExamplePlugin());loadPlugin(new SimpleCountingPlugin());
}}
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:
8 Chapter 2. Getting Started
graceland-core Documentation, Release 0.1.0
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
2.6 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.platform.configuration.Configuration {
private final long startingOn;
@JsonCreator
2.6. Step 6 - Add a New Machine 9
graceland-core Documentation, Release 0.1.0
public 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 {
@Overrideprotected void configure() {
// 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");
}}
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.
2.7 Step 7 - Switch It Up
We can simply swap out the plugin being loaded!
10 Chapter 2. Getting Started
graceland-core Documentation, Release 0.1.0
@Overrideprotected void configure() {
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.
2.7. Step 7 - Switch It Up 11
graceland-core Documentation, Release 0.1.0
12 Chapter 2. Getting Started
CHAPTER 3
Plugins
Plugins are the basic building block of a Graceland Application. They let the developer build discrete units offunctionality that they can load into their app at runtime, or easily share between different projects ate compiletime.
3.1 Why Plugins?
There are a lot of advantages to having a modular system.
• Easier to Understand - It makes it easier to break up the domain problem and think about what is important tosolve the problem in front of you.
• Testable Code - Writing modular code makes it easier to write testable code. A modular code base is lesscoupled, making testing a lot easier.
• Swap Out Functionality - It gives you the ability to swap out components, making it easy to change thefunctionality of your application in a sane and easy to understand way.
• Develop in Parallel - Plugins can be developed in parallel, and used by the same application.
3.2 Plugins vs. Modules
If you’re familiar with Guice, then you’re familiar with their concept of a Module. You’ve probably used theAbstractModule to build out your application, since it provides some nice plumbing for you.
In Graceland, a Plugin is just like a Module, providing the basic building blocks for your application. AnAbstractPlugin provides the a lot of helpful functionality for binding your application’s components.
3.3 A Sample Plugin
Below is a sample plugin. It binds a resource to be served by Jersey, and a task to the Dropwizard environment.
import io.graceland.platform.plugin.AbstractPlugin;
public class ExamplePlugin extends AbstractPlugin {
@Overrideprotected void configure() {
// add the resource
13
graceland-core Documentation, Release 0.1.0
bindJerseyComponent(ExampleResource.class);
// add the taskbindTask(ResetTask.class);
}}
3.4 Plugin Loaders
You won’t always be able to define what plugins to load in your application. If you want to load plugins dynamicallyat run time, you’ll need a mechanism for doing this. Plugin Loaders make this easy to do.
3.4.1 Native Plugin Loader
The NativePluginLoader will load all Plugins that it can find using the native, Java ServiceLoader. Thismeans it will look on the class path for the META-INF/services entries and loading those.
It’s a simple PluginLoader that can be used to scan the class path at runtime and load plugins dynamically.
14 Chapter 3. Plugins
CHAPTER 4
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.
4.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.
4.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.platform.application.ModalApplicationclass, 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
graceland-core Documentation, Release 0.1.0
case DEV:// do dev stuffloadPlugin(new SampleDevPlugin());
case PROD:// do prod stuffloadPlugin(new SampleProdPlugin());
}}
}
4.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.
4.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.platform.application.Application interface.
16 Chapter 4. Applications
CHAPTER 5
Configurations
A Graceland system can have more than one configuration. This section of the guide will walk you throughhow to bind these configurations so you can use them in your system.
5.1 Binding a Configuration
The easiest way to explain configurations may be to show an example:
public class ExamplePlugin extends AbstractPlugin {
@Overrideprotected void configure() {
// bind the configuration file to the classbindConfiguration(ExampleConfiguration.class).toFile("example.yml");
}}
Behind the scenes there is a ConfigurationBinder that is wiring up the configuration so it is available in yourGuice dependency graph.
There are two main ways of binding configurations:
• toInstance - an instance of the configuration is provided in the bind statement. This can be useful if youknow the values to use, or if you’re preparing an instance by some other means (i.e. loading from a database).
• toFile - an instance is created by reading the YAML file provided. It will look for the file relative to the currentworking directory. If there are any parsing issues, Graceland will not load and will attempt to provide a helpfulerror message.
17
graceland-core Documentation, Release 0.1.0
18 Chapter 5. Configurations
CHAPTER 6
Filters
The Guice Multibinder extension does not garauntee the ordering of the injected values - they use a Set<> to returnthe values. Because the ordering of filters is important to their function, a special FilterBinder is used to ensurethat they are added properly.
Warning: If a filter is added directly to the Environment (i.e. using a Configurator), there is no garuaunteethat it will be added in the right order. Please make sure to use a FilterBinder for all filters.
6.1 FilterBinder
A FilterBinder allows you to set the patterns, priority, and name of the filter.
Name Default Descriptionpriority 500 Used to determine the sort order of the filter.name The classes getSimpleName() The name the filter is registered with.pattern /* The pattern that the filter will be registered with.
6.2 An Example Binding
The example below does the following:
• adds a filter for the class TestFilter
• sets the priority to 900
• ensures the filter affects the following patterns: /test/** and /other/**
• the true/false parameters affect whether the pattern is applied before or after other patterns. false means it’llbe applied before other patterns, while true means it’ll be applied after other patterns
• sets the name to mySpecialName
import io.graceland.plugin.AbstractPlugin;
public class ExamplePlugin extends AbstractPlugin {
@Overrideprotected void configure() {
FilterBinder.forClass(binder(), TestFilter.class)
19
graceland-core Documentation, Release 0.1.0
.withPriority(900)
.addPattern(FilterPattern.newInstance(EnumSet.allOf(DispatcherType.class), false, "/test*")
.addPattern(FilterPattern.newInstance(EnumSet.allOf(DispatcherType.class), true, "/other/*")
.withName("mySpecialName")
.bind();}
}
20 Chapter 6. Filters
CHAPTER 7
Platform
The Platform replaces the io.dropwizard.Application in your graceland system. It’s the base for yourservice, and is what is responsible for wiring everything up.
To start up a Platform, just create one and call the start(String[] args) method, where the args are thecommand line arguments. A good place to put this is in a public static void main clause. Here’s an exam-ple:
public static void main(String[] args) throws Exception {Platform
.forApplication(new ExampleApplication())
.start(args);}
7.1 Platform Configuration
The graceland Platform has a single, platform-wide configuration. This extends the dropwizardio.dropwizard.Configuration class, and is where the user will set the HTTP ports, logging, etc.
In your graceland system, you may have more than one configuration file, but only one Platform configuration. Formore information on configurations, see the Configuration section.
21
graceland-core Documentation, Release 0.1.0
22 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}
}
Warning: Using an escape hatch will cause your code to run outside of the happy path. There are few guaranteesmade by the Platform for running these escape hatches. If there is a graceland-provided way of doing something(i.e. adding a resource), you’re better off using it rather than an escape hatch.
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.
23
graceland-core Documentation, Release 0.1.0
public class SampleConfigurator implements Configurator {@Overridepublic void configure(PlatformConfiguration configuration, Environment environment) {
// example of adding a filter directly to the environmentenvironment.servlets().addFilter(...)
}}
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(...);
}}
24 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.
25
graceland-core Documentation, Release 0.1.0
26 Chapter 9. Metrics Graphite
CHAPTER 10
Frequently Asked Questions
10.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.
10.2 License
Graceland is licensed under the Apache License v2.0. See the LICENSE file for more details.
27
graceland-core Documentation, Release 0.1.0
28 Chapter 10. Frequently Asked Questions
CHAPTER 11
Indices and tables
• genindex
• modindex
• search
29