Service Seed

About

Service seed is a starting point for developing homogenous, SOA/Enterprise-friendly webservices. It is a fork of the Netflix/karyon project found on github, with added functionality and examples. Out of the box, the seed offers:

• Java webservice development (Jersey stack and working examples)
• Dynamic webservice development (runtime-deployment of Javascript-defined webservices)
• Database/ORM integration (via JPA)
• Asynchronous logging (Blitz4j)
• Properties management (via Netflix Archaeus)
• JMX monitoring (made easy) and metrics reporting (via Netflix Servo)
• Framework-level monitoring (bytes in/out, CPU high water mark, number of requests handled per endpoint, etc)
• Auditing
• PCI and Hippa requirements are modeled within the seed framework
• Custom auditing appender
• Administrative console
• Every seed exposes an administrative console on port 8077, regardless of deployment/container configuration.

Pre-requisites

* Gradle >= 1.4 * JDK >= 6 * Note that JDK 7 currently breaks unit tests instrumented by Cobertura

To run

• From the project root, "gradle jettyRun"
• Checkout the admin console at http://localhost:8077
• Checkout the example REST services at http://localhost:8989/hello-world/v1/
• /hello - example of static service (no parameters)
• /hello/to/world - example of dynamic query parameter
• Checkout the dynamic services landing page
• localhost:8989/dyn

To deploy

* From the project root, "gradle war" * Then copy (deploy) to your container of choice

Developing a concrete service from the seed

There are currently four modules within the seed:

• karyon-admin-web
• karyon-admin
• service-framework
• service-implementation

The first two, for admin, are only coupled to the project as source as an artifact of the karyon project, and have not been moved out because they will likely be modified by this project within the near to mid term.

The service-framework module, like the admin modules, contain the homogenous functionality like auditing, servlet filter exception processing, system/generic metrics, and dynamic services. Likely, for a given implementation, there will be no need to modify this module.

The service-implementation module is the module everyone will be concerned with. Out of the box, it defines a hello-world project with two endpoints (one static and one that takes a template parameter), and a simple health check servlet. This module is meant to be refactored into a useful service implementation.

Example

Let's say you wanted to develop a service called "math" that multiplies two template parameters and returns the result.

First step, barebones implementation

* Get/fork the project, (ie) git clone github:robertjchristian/service-seed * As a sanity check, perform the steps in "to run" outlined above` * nano service-implementation/src/main/java/com/liaison/service/HelloworldResource * Copy/paste the helloTo service, including annotations * Change path from "to/{name}" to "multiply/{a}/{b}" * Change method name to multiply, and the single "name" path parameter interface to take a and b "int" parameters instead * Change the response.put call to return the value of a*b instead.

That's it!

Second step, productize

Realistically you will want to productize your service, which basically means fixing up the namespace from hello-world to something more specific to your particular service. These steps outline that process. Note that scaffolding is on the near-term roadmap, and will make most or all of these steps obsolete:

• Edit ./service-implementation/build.gradle
• Change project.war.basename from "hello-world" to "math"
• Change System.setProperty("archaius.deployment.applicationId", "hello-world") to System.setProperty("archaius.deployment.applicationId", "math")
• Rename ./service-implementation/src/main/resources/hello-world* to use prefix "math" instead.
• Refactor your package namespace as desired
• Make sure to update math.properties to reflect any high-level namespace change, ie com.netflix.karyon.server.base.packages=com.liaison to com.netflix.karyon.server.base.packages=com.acme

Keeping up with change

This project is going to be in flux for the foreseeable future (see roadmap).

Adding service-seed as a remote tracking branch is a low cost and easy way to pick up changes. It's recommended to do something like:

git remote add --track multi-project service-seed [email protected]:robertjchristian/service-seed.git
git fetch service-seed
git merge service-seed/master