Skip to content
CXF extension to manage JAX-RS applications in OSGi environment.
Java Shell
Branch: develop
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples/echo
src/main/java/hu/blackbelt/jaxrs
.gitignore
.maven.xml
CHANGELOG.adoc
LICENSE
README.adoc
ci.yml
local-build.sh
local-release.sh
pom.xml
wercker.env.sample
wercker.yml

README.adoc

JAX-RS application manager

JAX-RS application manager can be used to track JAX-RS application/resource/provider changes in OSGi environment.

Overview

javax.ws.rs.core.Application OSGi components are exposed automatically by JAX-RS application manager as RESTful web services. Application path is defined by OSGi service property (applicationPath) or @javax.ws.rs.ApplicationPath annotation. A default CXF service is created automatically in Apache Karaf environment and all JAX-RS application are registered in it (see: RuntimeDelegate.getInstance()).

There is a prepared hu.blackbelt.jaxrs.application.BasicApplication Declarative Service that can be used to define JAX-RS application by configuration (i.e. using Configuration Admin) tracking JAX-RS resources defined by OSGi filter.

Quick start

  • prepare Apache Karaf runtime environment described below

  • copy *.cfg configuration files from examples/echo to KARAF_HOME/deploy directory (note: CxfContext and CxfServerManager configurations are optinal, ensure that application has no reference to CXF context if it is not defined)

  • create OSGi bundle (i.e. using maven-bundle-plugin) containing Echo.java

  • copy created bundle to KARAF_HOME/deploy directory

Configuration options

  • Global JAX-RS providers: JAX-RS providers applied to all applications (note: custom bundles must have X-JAXRS-Provider: true header!)

    • jaxrs.provider.PROVIDER_CLASS_NAME.: recommended syntax for provider configuration options

    • application.id: reserved property for providers defined by applications, global providers are not allowed to use it

  • Shared JAX-RS providers: JAX-RS providers applied to a set of applications (note custom bundles must have X-JAXRS-Provider: true header!)

    • applications.filter: OSGi filter expression defining JAX-RS applications using the provider.

    • jaxrs.provider.PROVIDER_CLASS_NAME.: recommended syntax for provider configuration options

    • application.id: reserved property for providers defined by applications, shared providers are not allowed to use it

  • hu.blackbelt.jaxrs.application.BasicApplication

    • applicationPath: JAX-RS application path described above.

    • jaxrs.application.name: optional property that can be used to set application name

    • jaxrs.provider.components: OSGi filter expression defining JAX-RS providers (OSGi components)

    • jaxrs.provider.classes: comma-separated list of JAX-RS provider classes, instances are created by the application

    • jaxrs.provider.PROVIDER_CLASS_NAME.option: recommended syntax for provider configuration options so providers can filter their configuration options easily (all properties excluding service., component. and felix. prefixes are passed to provider)

    • jaxrs.resource.components: OSGi filter expression defining JAX-RS singletons resources (OSGi components)

    • jaxrs.resource.classes: comma-separated list of JAX-RS resource classes, instances are created by the application

    • cxf.context.target: OSGi filter expression define CXF context (bus, interceptors) of the application

  • hu.blackbelt.jaxrs.CxfContext

    • busId: CXF bus ID

    • skipDefaultJsonProviderRegistration: Skip default JSON provider registration, do not use CXF JSON provider as default message body reader.

    • wadlServiceDescriptionAvailable: WADL service description available.

    • interceptors.in.components: OSGi filter expression defining components used as CXF IN interceptors.

    • interceptors.out.components: OSGi filter expression defining components used as CXF OUT interceptors.

    • interceptors.fault.components: OSGi filter expression defining components used as CXF FAULT(OUT) interceptors.

  • JAX-RS resources

    • basePath: this property is recommended for hu.blackbelt.jaxrs.application.BasicApplication singletons resources (OSGi components) for binding to JAX-RS applications.

  • prepared JAX-RS providers:

    • hu.blackbelt.jaxrs.providers.JacksonProvider: Jackson provider marshalling/unmarshalling JSON payloads

      • jaxrs.provider.JacksonProvider.SerializationFeature.KEY: KEY is an enumeration value of com.fasterxml.jackson.databind.SerializationFeature, see referenced Java class for details

      • jaxrs.provider.JacksonProvider.DeserializationFeature.KEY: KEY is an enumeration value of com.fasterxml.jackson.databind.DeserializationFeature, see referenced Java class for details

      • jaxrs.provider.JacksonProvider.ObjectMapper.modules: comma separated list of com.fasterxml.jackson.databind.Module classes that are registered in default com.fasterxml.jackson.databind.ObjectMapper

      • objectMapper.target: optional OSGi filter choosing which Object mapper component is used by Jackson provider (if multiple instances are registered)

    • hu.blackbelt.jaxrs.providers.ISO8601DateParamHandler: extension supporting java.util.Date parameters

      • jaxrs.provider.ISO8601DateParamHandler.DATE_FORMAT: pattern for Date parameters

  • hu.blackbelt.jaxrs.CxfServerManager (singleton)

    • skipDefaultJsonProviderRegistration: Default CXF bus configuration: skip default JSON provider registration, do not use CXF JSON provider as default message body reader.

    • wadlServiceDescriptionAvailable: Default CXF bus configuration: WADL service description available.

    • interceptors.in.components: Default CXF bus configuration: OSGi filter expression defining components used as CXF IN interceptors.

    • interceptors.out.components: Default CXF bus configuration: OSGi filter expression defining components used as CXF OUT interceptors.

    • interceptors.fault.components: Default CXF bus configuration: OSGi filter expression defining components used as CXF FAULT(OUT) interceptors.

  • CXF configuration file used by Apache Karaf features: org.apache.cxf.osgi.cfg

    • org.apache.cxf.servlet.context: context root of default JAX-RS endpoints, applications are created under it (default: /cxf).

    • org.apache.cxf.servlet.hide-service-list-page: WADL descriptors are not available if this option is set to true.

Preparing runtime environment

  • download and install Apache Karaf (>= 4.1.0) from http://karaf.apache.org/download.html

  • install declarative services, JAX-RS API and CXF implementation features including JAX-RS JSON provider implementation (Jackson):

feature:install scr cxf-jaxrs cxf-jackson
  • copy cxf-jaxrs-application-manager-VERSION.jar into KARAF_HOME/deploy

  • create JAX-RS resources (and custom providers optionally)

You can’t perform that action at this time.