service-nucleus

Service-Nucleus is largely made up of two core projects, NetFlix Karyon and Angular-Enterprise-Seed.

About

Service-nucleus 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, examples, and a UI. Out of the box, this project offers:

• Rich Client-MVC-Based UI built on Angular with:
• Twitter Bootstrap and FontAwesome styling
• Pre-built components (modals, pagination, grids, etc)
• If you are interested only in the UI, check out Angular-Enterprise-Seed.
• Java REST webservice development (Jersey stack and working examples)
• Dynamic webservice development (runtime-deployment of Javascript-defined webservices)
• Asynchronous logging (Log4J2)
• Properties management (via Netflix Archaeus)
• JMX monitoring made easy with annotations, 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
• Always exposes an administrative console on port 8077, regardless of deployment/container configuration.

Pre-requisites

* Gradle >= 1.6 * JDK >= 6 *

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-nucleus * 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

Building LESS

In addition to the prerequisites outlined above, you'll need npm, less, and uglify-js to build Twtter Bootstrap.

Keeping up with changes to Karyon

git remote add --track master karyon [email protected]:Netflix/karyon.git
git fetch karyon
git merge karyon/master

Keeping up with changes

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

Adding the service-nucleus as a remote tracking branch is a low cost and easy way to stay current. It's recommended to do something like:

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

Note that similarly, when developing on this project, a remote tracking branch should be setup against NetFlix/karyon.

12/13/2013 - Recent Changes to Service Nucleus

1. Merge with HEAD of karyon master: https://github.com/Netflix/karyon 2. AsyncServlet enabled and wired into web.xml 3. Upgrade all gradle 1.5 references to 1.6 4. Remove dependencies on junit in favor of testing 5. Delete fs2 source (grab snapshot 0.0.2 jar from nexus and refer to it locally instead i.e. in service-implementation/lib 6. Deprecate initialization servlet (should be using HelloWorldComponent.initialize() instead ) 7. Add Servlet 3.0 8. Added swqgger annotations and swagger ui

Swagger REST Documentation

Located at http://localhost:8989/hello-world/swagger-ui/index.html

Swagger-UI Config:

For release or war deployment edit src/main/webapps/ui/swagger-ui/index.html to point to public api-docs url

For more info read swagger-ui docs at service-implementation/src/main/webapp/ui/swagger-ui/README.md

Roadmap

* Add thread sandboxing (mainly for dynamic services)