REST API - switching Jersey dependencies for CXF

[Svetoslav Neykov <sv...@cloudsoftcorp.com>]

HI all,

As part of the process of improving OSGi support in Brooklyn and creating a Karaf runtime [1], there's been work [2] to switch the REST API from Jersey to CXF as the JAX-RS implementation. Btw thanks Cipi who's done the bulk of the work on this.
Here's a list of the major changes in the PR:
  * Remove support for installing the REST API as a servlet filter. Servlet is the default now.
  * /v1 prefix removed from resource paths and added at the servlet context path. User URLs remain the same.
  * Resource (REST API) implementations can't assume the url at which they live, need to use "@Context UriBuilder uriBuilder" to construct urls returned to the user.
  * remove multipart rest call for creating apps (file upload)
  * move all rest related code from "rest-server" to a new "rest-resources" module. Leave only servlet related code (like filters) in "rest-server".

None of the above changes should affect users of the REST API, full backwards compatibility is expected. Because of the size of the change set and the different JAX-RS implementation used there's always the chance for unanticipated problems, so testing the it with any clients of the API for compatibility will be really appreciated.

Downstream projects enriching the Brooklyn REST API with their own REST calls need to follow these steps:
  * Remove "/v1" prefix from the resource path
  * Don't make assumptions in the code at which URI the resource will live at. Use "@Context UriBuilder uriBuilder" to construct urls returned to the user.
  * Ideally target JAX-RS 2.0 API instead of a specific implementation [3]
  * If the above is not possible then replace Jersey specific code with CXF v3.1.4.

Currently there's support in the PR to keep Jersey compatibility behind an optional build flag (-Djax-rs=jersey). It will switch between a dist using either Jersey or CXF (which is the default). That's needed in the case where downstream projects either have a hard dependency on Jersey or adding CXF in the classpath would cause conflicts. We are currently deliberating whether the support for this flag should be merged into master and if so how long we should keep it there. That's why early testing your project for compatibility is very important here. If no one claims interest in the Jersey compat, then it's highly likely that it will not reach master due to the additional support burden it will cause.

Svet.


[1] https://issues.apache.org/jira/browse/BROOKLYN-183
[2] https://github.com/apache/brooklyn-server/pull/15
[3] https://issues.apache.org/jira/browse/BROOKLYN-183