Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "Tutorial: JaxRS Remote Services on Karaf"
Line 1: | Line 1: | ||
==Introduction== | ==Introduction== | ||
− | [https://github.com/ECF/JaxRSProviders CXF] can be run on Karaf as an ECF [https://wiki.eclipse.org/Distribution_Providers distribution provider] for JaxRS-based remote services that fully support [https://www.eclipse.org/ecf/NewAndNoteworthy.html OSGi R7 remote services]. | + | [https://github.com/ECF/JaxRSProviders Jersey and CXF ] can be run on Karaf as an ECF [https://wiki.eclipse.org/Distribution_Providers distribution provider] for JaxRS-based remote services that fully support [https://www.eclipse.org/ecf/NewAndNoteworthy.html OSGi R7 remote services]. |
This tutorial describes installing and running an example JaxRS remote service on Karaf. | This tutorial describes installing and running an example JaxRS remote service on Karaf. | ||
− | Requirements: [http://karaf.apache.org Karaf 4.2+ running on Java 8] | + | Requirements: [http://karaf.apache.org Karaf 4.2.1+ running on Java 8] |
− | ===Install | + | ===Install Jersey Distribution Provider via Karaf Console=== |
− | Add the ECF repo: | + | Add the ECF Remote Services features repo: |
<pre> | <pre> | ||
karaf@root()>feature:repo-add ecf | karaf@root()>feature:repo-add ecf | ||
</pre> | </pre> | ||
− | Install the | + | Install the Jersey Distribution Provider |
<pre> | <pre> | ||
− | karaf@root()>feature:install ecf-rs-distribution- | + | karaf@root()>feature:install ecf-rs-distribution-jersey |
</pre> | </pre> | ||
Line 26: | Line 26: | ||
Shutdown and restart Karaf so that the org.osgi.service.http.port system property set can take effect on startup. | Shutdown and restart Karaf so that the org.osgi.service.http.port system property set can take effect on startup. | ||
− | === | + | ===JaxRS Student Example=== |
In [https://wiki.eclipse.org/Tutorial:_Exposing_a_Jax_REST_service_as_an_OSGi_Remote_Service this tutorial] an example REST service is presented. The completed example bundles with source are available in the [https://github.com/ECF/JaxRSProviders ECF JaxRSProviders repository]. To run this example you may wish to clone this repo, and import into Eclipse these three projects: '''examples/com.mycorp.examples.student''', '''examples/com.mycorp.examples.remoteservice.host''', and '''examples/com.mycorp.examples.client'''. | In [https://wiki.eclipse.org/Tutorial:_Exposing_a_Jax_REST_service_as_an_OSGi_Remote_Service this tutorial] an example REST service is presented. The completed example bundles with source are available in the [https://github.com/ECF/JaxRSProviders ECF JaxRSProviders repository]. To run this example you may wish to clone this repo, and import into Eclipse these three projects: '''examples/com.mycorp.examples.student''', '''examples/com.mycorp.examples.remoteservice.host''', and '''examples/com.mycorp.examples.client'''. | ||
− | ====Install | + | ====Install JaxRS Student Example Service Client and Host ==== |
<pre> | <pre> | ||
Line 119: | Line 119: | ||
<pre> | <pre> | ||
− | karaf@root()>feature:install ecf-rs-distribution- | + | karaf@root()>feature:install ecf-rs-distribution-cxf |
</pre> | </pre> | ||
− | The | + | The CXF distribution provider will be installed instead of the Jersey distribution provider. |
− | Once the | + | Once the CXF provider is installed, the StudentService example may be installed and run in the same way as shown above, but now the CXF implementation will be used as the distribution system for the StudentService. |
==Remote Service Implementation Details== | ==Remote Service Implementation Details== | ||
See the [[Tutorial:_Exposing_a_Jax_REST_service_as_an_OSGi_Remote_Service | Exposing a Jax REST service as a Remote Service]] tutorial. | See the [[Tutorial:_Exposing_a_Jax_REST_service_as_an_OSGi_Remote_Service | Exposing a Jax REST service as a Remote Service]] tutorial. |
Revision as of 13:50, 19 October 2018
Contents
Introduction
Jersey and CXF can be run on Karaf as an ECF distribution provider for JaxRS-based remote services that fully support OSGi R7 remote services.
This tutorial describes installing and running an example JaxRS remote service on Karaf.
Requirements: Karaf 4.2.1+ running on Java 8
Install Jersey Distribution Provider via Karaf Console
Add the ECF Remote Services features repo:
karaf@root()>feature:repo-add ecf
Install the Jersey Distribution Provider
karaf@root()>feature:install ecf-rs-distribution-jersey
To properly run in Karaf the org.osgi.service.http.port system property must be set to the desired port:
karaf@root()> system:property -p org.osgi.service.http.port 8181
Shutdown and restart Karaf so that the org.osgi.service.http.port system property set can take effect on startup.
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 three projects: examples/com.mycorp.examples.student, examples/com.mycorp.examples.remoteservice.host, and examples/com.mycorp.examples.client.
Install JaxRS 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-host
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]]
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.
Note that once exported via a Jax-RS supporting provider (currently Jersey and CXF), the getStudents() service method can be accessed directly via an http get call via the following url:
http://localhost:8181/1/studentservice/students
This is because the ecf.endpoint.id=http://localhost:8181/1, the StudentService path is set to studentservice, and the StudentService.getStudents() method path is set to 'students'.
For example:
$ curl http://localhost:8181/1/studentservice/students {"students":[{"id":"24e7dfdb-b9e1-4540-a450-b0c19bf43ec9","name":"Joe Senior","grade":"Eighth","address":{"street":"111 Park Ave","city":"New York","state":"NY","postalCode":"11111"}}]}
For reference, the client component's source code is here.
Using Jersey JaxRS 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-cxf
The CXF distribution provider will be installed instead of the Jersey distribution provider.
Once the CXF provider is installed, the StudentService example may be installed and run in the same way as shown above, but now the CXF implementation will be used as the distribution system for the StudentService.
Remote Service Implementation Details
See the Exposing a Jax REST service as a Remote Service tutorial.