params.json

{"name":"swookiee REST Services Runtime","tagline":"","body":"[![Build Status](https://travis-ci.org/swookiee/com.swookiee.runtime.svg?branch=develop)](https://travis-ci.org/swookiee/com.swookiee.runtime)\r\n\r\n## What is swookiee*\r\nThis is how a shaved wookiee could look like:\r\n\r\n![shaved wookiee](https://raw.github.com/swookiee/swookiee.github.io/master/images/swookiee.png)\r\n\r\nSwookiee basically is a JVM Runtime for REST Services. It is lightweight (~17 MB, yeah... \"lightweight\") and includes libraries like guava, joda-time, metrics, etc. It also supports service implementation written in Groovy and Scala (+7MB each). It uses a JAX-RS 2 (Jersey), Jetty, Jackson stack on top of the Equinox OSGi runtime to serve REST Services. swookiee also provides multiple REST APIs to deploy and control services and components via REST.\r\n\r\nOur main goals are:\r\n* simplify exposing REST Services in the JVM\r\n* JVM-Polyglot: Solve problems in best fit language\r\n* reduce mandatory infrastructure and architectural knowledge from developers\r\n* define boundaries and APIs\r\n* enable deployment on artifact level (very simple OSGi [RFC-182 implementation](https://github.com/osgi/design/tree/master/rfcs/rfc0182))\r\n* increase transparency through direct metrics, graphite and JSON logging support\r\n\r\n## Build \\& start\r\n\r\nBuild & Start\r\n```shell\r\ncd com.swookiee.runtime\r\nmvn clean install\r\n\r\ncd com.swookiee.runtime\r\nmvn exec:exec\r\n```\r\n\r\n## Web Console\r\nWhen swookiee is up and running the Web Console can be accessed via [`http://localhost:8080/system/console`](http://localhost:8080/system/console). The default credentials are `admin:admin123`.\r\n\r\n## REST Services\r\n\r\nTo expose a REST service in swookiee you can describe the REST API with a simple interface:\r\n```java\r\n@Path(\"/hello\")\r\n@Produces(APPLICATION_JSON)\r\npublic interface HelloWorld {\r\n    @GET\r\n    String hello();\r\n}\r\n```\r\n\r\nThrough using the given [`@Component`](http://www.osgi.org/javadoc/r5/cmpn/org/osgi/service/component/annotations/Component.html) annotation the implementation of the interface will be exposed.\r\n```java\r\n@Component\r\npublic class HelloWorldService implements HelloWorld {\r\n    @Override\r\n    public String hello() {\r\n        return \"Hola!\";\r\n    }\r\n}\r\n```\r\n\r\nA REST service will be exposed using the [OSGi - JAX-RS Connector](https://github.com/hstaudacher/osgi-jax-rs-connector). Thus, every JAX-RS component which is an available OSGi service will also be published via Jersey. You will find a deteiles Jersey user guide [here](https://jersey.java.net/documentation/latest).\r\n\r\n## Filters, Exception Mapping, ...\r\n\r\nIn addition to provide services you might need to register Filter (e.g. for CORS). This can be done via `ContainerResponseFilter` and `ContainerRequestFilter` implementations:\r\n\r\n```java\r\n@Component\r\n@Provider\r\npublic class MyFilter implements ContainerResponseFilter {\r\n\r\n    @Override\r\n    public void filter(final ContainerRequestContext requestContext, final ContainerResponseContext responseContext) {\r\n    }\r\n}\r\n```\r\n\r\n```java\r\n@Component\r\n@Provider\r\npublic class MyFilter implements ContainerRequestFilter {\r\n\r\n    @Override\r\n    public void filter(final ContainerRequestContext requestContext) {\r\n    }\r\n}\r\n```\r\n\r\nIn order to register an exception mapper you have to implement the `ExceptionMapper` interface:\r\n```java\r\n@Component\r\n@Provider\r\npublic class MyExceptionMapper implements ExceptionMapper<MyException> {\r\n\r\n    @Override\r\n    public Response toResponse(final MyException exception) {\r\n        return Response.status(Status.INTERNAL_SERVER_ERROR).build();\r\n    }\r\n}\r\n\r\n```\r\n\r\n## JSON logging output\r\nIn case you want to use logstash and kibana to analyze your logs you might want to use JSON as an output format.\r\nThis can be achieved through setting the property `productionLogging` to `true`. To change the output folder configure `loggingDirectory` with your desired path. The output filename will be `osgi-json.log`. \r\n\r\n## Deployment and runtime management via REST\r\n[RFC-182](https://github.com/osgi/design/tree/master/rfcs/rfc0182)\r\n\r\n## Configuration\r\nThe Swookiee Runtime can be configured programmatically and via the UI of the Web Console. \r\n\r\n### Programmatic Configuration\r\nThe programmatic configuration can be done via an API on top of the OSGi Configuration Admin. The full sample can be found [here](https://github.com/swookiee/swookiee-samples/tree/develop/config)\r\n\r\nDefine a POJO with the components you want to configure. In this case we want to change the admin user credentials and the graphite reporter configuration:\r\n```java\r\npublic class Configuration {\r\n    public AdminUserConfiguration adminUserConfiguration;\r\n    public GraphiteReporterConfiguration graphiteReporterConfiguration;\r\n}\r\n```\r\n\r\nDefine a YAML file which matches the attributes of your POJO. Additionally set the desired parameter values:\r\n```yml\r\nadminUserConfiguration:\r\n  username: \"admin\"\r\n  password: \"admin42\"\r\n    \r\ngraphiteReporterConfiguration:\r\n  graphiteHost: localhost\r\n  graphitePort: 2003\r\n  reportingIntervalInSeconds : 42\r\n  reportingEnabled: true\r\n  reportingPrefix: \"configDemo\"\r\n```\r\n\r\nIn order to set your configuration values to the addressed components you can create a Declarative Service Component which is then using `ConfigurationUtils` to set your configuration parameters\r\n```java\r\n@Component\r\npublic class ConfigurationProviderSample {\r\n\r\n    private ConfigurationAdmin configAdmin;\r\n\r\n    @Activate\r\n    public void activate(final BundleContext bundleContext) {\r\n\r\n        final URL configurationFile = bundleContext.getBundle().getResource(\"Configuration.yaml\");\r\n        ConfigurationUtils.applyConfiguration(Configuration.class, configurationFile, configAdmin);\r\n\r\n    }\r\n\r\n    @Reference\r\n    public void setConfigurationAdmin(final ConfigurationAdmin configurationAdmin) {\r\n        this.configAdmin = configurationAdmin;\r\n    }\r\n\r\n    public void unsetConfigurationAdmin(final ConfigurationAdmin configurationAdmin) {\r\n        this.configAdmin = null;\r\n    }\r\n}\r\n```\r\n\r\n### UI\r\nMost configuration parameters can be controlled via the Web Console: [http://localhost:8080/system/console/configMgr](http://localhost:8080/system/console/configMgr)\r\n\r\n## Pushing metrics to graphite\r\n\r\nEvery published REST interface will be monitored via metrics. In addition basic JVM statistics will be collected. In order to configure the graphite reporter you can configure various settings:\r\n\r\n```yml\r\ngraphiteReporterConfiguration:\r\n  graphiteHost: localhost\r\n  graphitePort: 2003\r\n  reportingIntervalInSeconds : 42\r\n  reportingEnabled: true\r\n  reportingPrefix: \"configDemo\"\r\n```\r\n\r\nExample Screenshot of some made up traffic:\r\n![graphite](https://raw.github.com/swookiee/swookiee.github.io/master/screenshots/graphite.png)\r\n\r\n## Swagger\r\nThe above described REST Resource can be enriched using `swagger-annotations`. A full sample can be found [here](https://github.com/swookiee/swookiee-samples/tree/develop/demo.swagger).\r\n\r\nWe could add the `@Api` and `@ApiOperation` annotations to our sample service:\r\n```java\r\n@Path(Status.PATH)\r\n@Produces(APPLICATION_JSON)\r\n@Api(value = Status.PATH, description = \"Returns a status\")\r\npublic interface Status {\r\n\r\n    final static String PATH = \"/status\";\r\n\r\n    @GET\r\n    @ApiOperation(value = \"Ping the Status API to receive a StatusObject\", response = StatusObject.class)\r\n    public StatusObject ping();\r\n}\r\n```\r\n\r\nThe following steps are important to let swookiee deliver you swagger api documentation:\r\n\r\n1. Make sure you have the `maven-swagger-plugin` configured properly and you are able to see generated swagger json files? Also make sure that the `<basePath>/services</basePath>` is set according to your configuration. Otherwise you won’t be able to test you API.\r\n2. Is the generated json part of your bundle/artefact/`.jar`? Is the folder accessable from within the Bundle?  Set the  the `Bundle-Classpath` to include the documentation folder.\r\n3. Add the `X-Swagger-Documentation` header in you `MANIFEST.MF` or your `maven-bundle-plugin` configuration to point to the documentation folder inside the `jar`, such as: `X-Swagger-Documentation: /swagger`.\r\n\r\nAfter installing the bundle you will find the `swagger-ui` under `http://localhost:8080/swagger/index.html`. Click on the small swookiee icon to see your documentation and test your API.\r\n\r\nScreenshot of the sample:\r\n![swagger](https://raw.github.com/swookiee/swookiee.github.io/master/screenshots/swagger.png)\r\n\r\n## Archetype(s) & Tooling & Samples\r\n### Samples & Archetype\r\n* [Configuration & Swagger](https://github.com/swookiee/swookiee-samples)\r\n* [Archetype & Simple REST Service](https://github.com/swookiee/com.swookiee.archetype)\r\n\r\n### Eclipse\r\n\r\n### Netbeans\r\n\r\n## Todos\r\n - [ ] provide rpm, deb and other packages\r\n - [ ] more JVM languages? (see [clojure branch](https://github.com/swookiee/com.swookiee.runtime/tree/feature/clojure_support))\r\n - [ ] Running swookiee programatically\r\n - [ ] Integration Test Tooling\r\n\r\n## Thanks\r\nMany thanks to **Intuit Data Engineering \\& Analytics** for the support!\r\n\r\n[![IDEA](https://raw.githubusercontent.com/swookiee/swookiee.github.io/master/images/idea_logo.jpg)](http://intuit.com)\r\n\r\n## License\r\nThe code is published under the terms of the [Eclipse Public License, version 1.0](http://www.eclipse.org/legal/epl-v10.html).\r\n\r\n\\* derived from \"shaved wookiee\"\r\n","google":"UA-48180947-1","note":"Don't delete this file! It's used internally to help with page regeneration."}