graceland-core Documentation

Transcription

1 graceland-core Documentation Release SNAPSHOT Javier Campanini April 14, 2014

2

3 Contents 1 About Contributing License Overview Motivation Architecture Modules Getting Started Step 1 - Silly Counting Machine Step 3 - Wire It Up Step 4 - Resources, Tasks & Plugins Step 5 - Building the Application Step 6 - Add a New Machine Step 7 - Switch It Up Plugins Why Plugins? Plugins vs. Modules Writing Your First Plugin A Sample Plugin Plugin Loaders Applications Simple Applications Modal Applications Custom Applications Configurations Binding a Configuration Platform Platform Platform Configuration Escape Hatches How We Use Dropwizard Configurator i

4 8.3 Initializer Metrics Graphite Host-Aware Graphite Reporter Indices and tables 25 ii

5 Contents: Contents 1

6 2 Contents

7 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 of test coverage is. 1.2 License Graceland is licensed under the Apache License v2.0. See the LICENSE file for more details. 3

8 4 Chapter 1. About

9 CHAPTER 2 Overview Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 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 sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. 2.1 Motivation Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 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 sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. 2.2 Architecture Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 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 sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. 2.3 Modules Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 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 sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. 5

10 6 Chapter 2. Overview

11 CHAPTER 3 Getting Started A quick guide to getting started using Graceland, using the example of a counting machine, and resources and tasks 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 the following: { "count": 4, "timestamp: 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

12 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(); public void increment() { count.incrementandget(); public void resetcount() { count.set(0); public Counter getcurrentcount() { return new Counter(count.get(), DateTime.now()); And lets wire it up inside of an Plugin: public class SimpleCountingPlugin extends AbstractPlugin { protected void configure() { // hook up the counting machine bind(countingmachine.class).to(simplecountingmachine.class).in(singleton.class); Whenever we include this SimpleCountingPlugin, we ll be telling Guice to use the SimpleCountingMachine 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 the following class. Notice how the CountingMachine is injected into the public class ExampleResource { private final CountingMachine ExampleResource(CountingMachine countingmachine) { this.countingmachine 8 Chapter 3. Getting Started

13 @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 the same CountingMachine here as well: public class ResetTask extends Task { private final CountingMachine ResetTask(CountingMachine countingmachine) { super("reset"); this.countingmachine = countingmachine; public void execute(immutablemultimap<string, String> stringstringimmutablemultimap, PrintWriter 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 { protected void configure() { // add the resource bindjerseycomponent(exampleresource.class); // add the task bindtask(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 this example, and load the plugins explictly: public class ExampleApplication extends SimpleApplication { protected void configure() { loadplugin(new ExamplePlugin()); loadplugin(new SimpleCountingPlugin()); 3.4. Step 5 - Building the Application 9

14 To run the application, we just add a public static void main(string[] args) method and run it from our 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 graceland where to start up the server: server: applicationconnectors: - type: http port: 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 INFO INFO INFO INFO INFO [ :38:55,065] io.dropwizard.server.serverfactory: Starting Platform [ :38:55,127] org.eclipse.jetty.setuid.setuidlistener: Opened application@24a06fb1{ [ :38:55,128] org.eclipse.jetty.setuid.setuidlistener: Opened admin@2104e040{http/1 [ :38:55,130] org.eclipse.jetty.server.server: jetty v [ :38:55,225] com.sun.jersey.server.impl.application.webapplicationimpl: Initiating [ :38:55,291] io.dropwizard.jersey.dropwizardresourceconfig: The following paths we GET /api/example (io.graceland.example.exampleresource) INFO [ :38:55,505] org.eclipse.jetty.server.handler.contexthandler: Started i.d.j.mutabl INFO [ :38:55,506] io.dropwizard.setup.adminenvironment: tasks = POST POST /tasks/gc (io.dropwizard.servlets.tasks.garbagecollectiontask) /tasks/reset (io.graceland.example.resettask) WARN [ :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 [ :38:55,511] org.eclipse.jetty.server.handler.contexthandler: Started i.d.j.mutabl INFO [ :38:55,525] org.eclipse.jetty.server.serverconnector: Started application@24a06fb INFO [ :38:55,526] org.eclipse.jetty.server.serverconnector: Started admin@2104e040{http You can finally test it out: 10 Chapter 3. Getting Started

15 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 that uses 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 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 one has a constructor where the StartingOnConfiguration is injected into. public class StartingOnCountingMachine implements CountingMachine { private final AtomicLong StartingOnCountingMachine(StartingOnConfiguration configuration) { // use the configuration to get the starting on count count = new AtomicLong(configuration.getStartingOn()); public void increment() { count.incrementandget(); public void resetcount() { count.set(0); public 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 { protected void configure() { // hook up the counting machine bind(countingmachine.class).to(startingoncountingmachine.class).in(singleton.class); // bind the configuration file to the class bindconfiguration(startingonconfiguration.class).tofile("starting-on.yml"); 3.5. Step 6 - Add a New Machine 11

16 Note: The configuration files look for the files relative to the current working directory (cwd). If you re running into trouble 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! protected 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. 12 Chapter 3. Getting Started

17 CHAPTER 4 Plugins Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 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 sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. 4.1 Why Plugins? Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 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 sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. 4.2 Plugins vs. Modules Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 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 sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. 4.3 Writing Your First Plugin Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 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 sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. 4.4 A Sample Plugin Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 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 sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. 13

18 4.5 Plugin Loaders Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 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 sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum Native Plugin Loader Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 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 sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. 14 Chapter 4. Plugins

19 CHAPTER 5 Applications The purpose of the Application is to manage the list of plugins that define your application. The two primary pieces 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 so you 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 the staging environment vs. the production environment. It would be ideal for swapping out implementations that are either 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 mode would 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 load determine 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 application super(samplemodes.class, SampleModes.PROD, args); protected void configurefor(samplemodes mode) { // load plugins that will be used in all modes loadplugin(new SamplePlugin()); switch (mode) { 15

20 case DEV: // do dev stuff loadplugin(new SampleDevPlugin()); case PROD: // do prod stuff loadplugin(new SampleProdPlugin()); Choosing a Mode To tell your application what mode to run in, add a command line argument with a leading double-dash and the mode enum 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 implementation of the io.graceland.application.application interface. 16 Chapter 5. Applications

21 CHAPTER 6 Configurations Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 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 sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. 6.1 Binding a Configuration Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 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 sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. 17

22 18 Chapter 6. Configurations

23 CHAPTER 7 Platform The graceland-platform module provides everything you ll need to build out modular Dropwizard applications. 7.1 Platform Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 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 sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. 7.2 Platform Configuration Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 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 sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. 19

24 20 Chapter 7. Platform

25 CHAPTER 8 Escape Hatches Graceland is built on top of the dropwizard platform and tries to wrap up the functionality so your plugins don t need to deal directly with it. Because we can t begin to pretend that we ll cover all of your use cases, we ve provided 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 dropwizard components in each of those phases. public class Platform extends io.dropwizard.application<platformconfiguration> { public void initialize(bootstrap<platformconfiguration> bootstrap) { // run the Initializers and other code public 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 important low level components: configuration - the application s configuration. environment - an io.dropwizard.setup.environment, which provides access to the underlying frameworks, 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 code will come in the form of a Configurator. public class SampleConfigurator implements Configurator { public void configure(platformconfiguration configuration, Environment environment) { // example of adding a filter directly to the environment environment.servlets().addfilter(...) 21

26 8.3 Initializer If you need access to the a io.dropwizard.setup.bootstrap, you can use an Initializer. This phase is usually used to add commands and bundles to a dropwizard applicataion. public class SampleInitializer implements Initializer { public void initialize(bootstrap<platformconfiguration> bootstrap) { // add a configured command bootstrap.addcommand(...); 22 Chapter 8. Escape Hatches

27 CHAPTER 9 Metrics Graphite The graceland-metrics-graphite module provides a metrics reporting factory that automatically uses the hostname 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 the current machine s host name. This is so each instance of the service will have a different prefix, letting you differentiate each 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 single dots. Note: All non-alphanumeric characters (including dots) in the hostname will be replaced with an underscore _ to ensure graphite does not break down the hostname variable Configuration Extends the attributes that are available to the graphite reporter. See the graphite reporter documentation for more details. metrics: reporters: - type: graphite-hostaware host: localhost port: 8080 prefix: <prefix> Name Default Description host 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

28 24 Chapter 9. Metrics Graphite

29 CHAPTER 10 Indices and tables genindex modindex search 25