Tutorial: CXF or Jersey for JaxRS Remote Services

Introduction

It's possible to use CXF running on Karaf as an ECF distribution provider for OSGi R7 remote services based upon the JaxRS specification. This tutorial goes through setting up and running an example JaxRS remote service on Karaf using the CXF distribution provider.

Requirements: Karaf 4.2+ running on Java 8

Install of CXF Server and Client Via Karaf Console

Add the ECF repo:

karaf@root()>feature:repo-add ecf

Install the CXF Server

karaf@root()>feature:install ecf-rs-distribution-cxf-server

Install the CXF Client (in this example these are run on same instance, but they can be easily installed on separate Karaf (or other) OSGi instances).

karaf@root()>feature:install ecf-rs-distribution-cxf-client

To run alongside the Karaf container's HttpService, the HttpService port must be set:

karaf@root()> system:property -p org.osgi.service.http.port 8181

Install of JaxRS Student Example

In this tutorial an example REST service is presented. The completed example bundles with source are available in the ECF JaxRSProviders repository. To run this example you may wish to clone this repo, and import into Eclipse these projects: examples/com.mycorp.examples.student', examples/com.mycorp.examples.remoteservice.host, and examples/com.mycorp.examples.client.

Install of Student Example Service Client and Host

karaf@root()> feature:install ecf-rs-examples-jaxrs-student-client
karaf@root()> feature:install ecf-rs-examples-jaxrs-student-server

This should produce output indicating the StudentService was exported

karaf@root()> feature:install ecf-rs-examples-jaxrs-student-host
16:17:04.904;EXPORT_REGISTRATION;exportedSR=[com.mycorp.examples.student.Student
Service];cID=URIID [uri=http://localhost:8181/1];rsId=1
--Endpoint Description---
<endpoint-descriptions xmlns="http://www.osgi.org/xmlns/rsa/v1.0.0">
  <endpoint-description>
    <property name="ecf.endpoint.id" value-type="String" value="http://localhost:8181/1"/>
    <property name="ecf.endpoint.id.ns" value-type="String" value="ecf.namespace.jaxrs"/>
    <property name="ecf.endpoint.ts" value-type="Long" value="1530573424662"/>
    <property name="ecf.rsvc.id" value-type="Long" value="1"/>
    <property name="endpoint.framework.uuid" value-type="String" value="7473f8a1-f0ac-4146-8087-0558ed8e46aa"/>
    <property name="endpoint.id" value-type="String" value="c9e3bb65-f157-40fe-b4bb-6c98c926ca03"/>
    <property name="endpoint.package.version.com.mycorp.examples.student" value-type="String" value="1.0.0"/>
    <property name="endpoint.service.id" value-type="Long" value="162"/>
    <property name="objectClass" value-type="String">
      <array>
        <value>com.mycorp.examples.student.StudentService</value>
      </array>
    </property>
    <property name="osgi.basic.timeout" value-type="String" value="50000"/>
    <property name="remote.configs.supported" value-type="String">
      <array>
        <value>ecf.jaxrs.cxf.server</value>
      </array>
    </property>
    <property name="remote.intents.supported" value-type="String">
      <array>
        <value>passByValue</value>
        <value>exactlyOnce</value>
        <value>ordered</value>
        <value>osgi.async</value>
        <value>osgi.private</value>
        <value>osgi.confidential</value>
        <value>jaxrs</value>
      </array>
    </property>
    <property name="service.imported" value-type="String" value="true"/>
    <property name="service.imported.configs" value-type="String">
      <array>
        <value>ecf.jaxrs.cxf.server</value>
      </array>
    </property>
    <property name="service.intents" value-type="String" value="osgi.async"/>
  </endpoint-description>
</endpoint-descriptions>
---End Endpoint Description
Discovered student service=com.mycorp.examples.student.remoteservice.host.StudentServiceImpl@51154196
Student0=Student [id=06f375e2-859d-4077-9bf4-edf8a1128439, name=Joe Senior, grade=First, address=Address [street=111 Park Ave, city=New York, state=NY, postalCode=11111]]
Updated Student0=Student [id=06f375e2-859d-4077-9bf4-edf8a1128439, name=Joe Senior, grade=Eighth, address=Address [street=111 Park Ave, city=New York, state=NY, postalCode=11111]]
Student=0=Student [id=06f375e2-859d-4077-9bf4-edf8a1128439, name=Joe Senior, grade=Eighth, address=Address [street=111 Park Ave, city=New York, state=NY, postalCode=11111]]
Created student=Student [id=ba408587-9546-45f2-b311-9b2d65c5761c, name=April Snow, grade=null, address=null]
Updated student=Student [id=ba408587-9546-45f2-b311-9b2d65c5761c, name=April Snow, grade=First, address=Address [street=111 NE 1st, city=Austin, state=Oregon, postalCode=97200]]
Deleted student=Student [id=ba408587-9546-45f2-b311-9b2d65c5761c, name=April Snow, grade=First, address=Address [street=111 NE 1st, city=Austin, state=Oregon, postalCode=97200]]
karaf@root()>

The output in between the --Start Endpoint Description-- and ---End Endpoint Description--- is debug output from the ECF RSA Console for the remote service export.

The output that begins Discovered student service... is output from the StudentService consumer when the remote service is discovered and injected into the client component so that it can be called. This output shows the invocation of the JaxRS remote service methods by the client component.

For reference, the [ https://github.com/ECF/JaxRSProviders/blob/master/examples/com.mycorp.examples.student.client/src/com/mycorp/examples/student/client/StudentServiceClient.java client component's source code is here].

Use of Jersey JaxRS Implementation Rather than CXF

To use Jersey rather than CXF, all that's necessary is to install the jersey server and client distribution providers rather than CXF providers:

karaf@root()>feature:install ecf-rs-distribution-jersey-server
karaf@root()>feature:install ecf-rs-distribution-jersey-client

These commands should be given rather than the CXF distribution provider install commands given above. Since CXF and Jersey are both implementations of the JaxRS specification they cannot be installed together on the same server. Once the Jersey provider is installed, the StudentService example may be installed and run in the same way as shown above, but now the Jersey implementation will be used as the distribution system for the StudentService.