Karaf CXF REST QuickStart

This quickstart demonstrates how to create a RESTful (JAX-RS) web service using CXF and expose it through the OSGi HTTP Service.

The REST service provides a customer service that supports the following operations

• PUT /customerservice/customers/ - to create or update a customer

• GET /customerservice/customers/{id} - to view a customer with the given id

• DELETE /customerservice/customers/{id} - to delete a customer with the given id

• GET /customerservice/orders/{orderId} - to view an order with the given id

• GET /customerservice/orders/{orderId}/products/{productId} - to view a specific product on an order with the given id

When the application is deployed, you can access the REST service using a web browser.

Important

This quickstart can run in 1 mode: on Kubernetes / OpenShift Cluster. Quickstart requires Java 8 or Java 11 (fuse-karaf-openshift-jdk11-rhel8 image is used to build in Java 11)

Running the Quickstart on a single-node Kubernetes/OpenShift cluster

Important

You need to run this example on Container Development Kit 3.3 or OpenShift 3.7. Both of these products have suitable Fuse images pre-installed. If you run it in an environment where those images are not preinstalled follow the steps described in Running the Quickstart on a single-node Kubernetes/OpenShift cluster without preinstalled images.

A single-node Kubernetes/OpenShift cluster provides you with access to a cloud environment that is similar to a production environment.

If you have a single-node Kubernetes/OpenShift cluster, such as Minishift or the Red Hat Container Development Kit, installed and running, you can deploy your quickstart there.

1. Download the project and extract the archive on your local filesystem.

2. Log in to your OpenShift cluster:

   $ oc login -u developer -p developer

3. Create a new OpenShift project for the quickstart:

   $ oc new-project MY_PROJECT_NAME

4. Change the directory to the folder that contains the extracted quickstart application (for example, my_openshift/karaf-cxf-rest) :

   $ cd my_openshift/karaf-cxf-rest

5. Build and deploy the project to the OpenShift cluster:

   $ mvn clean -DskipTests oc:deploy -Popenshift

Running the Quickstart on a single-node Kubernetes/OpenShift cluster without preinstalled images

A single-node Kubernetes/OpenShift cluster provides you with access to a cloud environment that is similar to a production environment.

If you have a single-node Kubernetes/OpenShift cluster, such as Minishift or the Red Hat Container Development Kit, installed and running, you can deploy your quickstart there.

1. Download the project and extract the archive on your local filesystem.

2. Log in to your OpenShift cluster:

   $ oc login -u developer -p developer

3. Create a new OpenShift project for the quickstart:

   $ oc new-project MY_PROJECT_NAME

4. Import base images in your newly created project (MY_PROJECT_NAME) according to documentation.

5. Change the directory to the folder that contains the extracted quickstart application (for example, my_openshift/karaf-cxf-rest) :

   $ cd my_openshift/karaf-cxf-rest

6. Build and deploy the project to the OpenShift cluster:

   $ mvn clean -DskipTests oc:deploy -Popenshift -Djkube.generator.fromMode=istag -Djkube.generator.from=MY_PROJECT_NAME/fuse7-karaf-openshift:1.13

Accessing the REST service

When the example is running, a REST service is available. This allows you to very easily test a few of the RESTful services we defined:

If you run the example on a single-node OpenShift cluster, then the REST service is exposed at 'http://karaf-cxf-rest-MY_PROJECT_NAME.OPENSHIFT_IP_ADDR.nip.io/cxf/`.

Notice: As it depends on your OpenShift setup, the hostname (route) might vary. Verify with oc get routes which hostname is valid for you. Add the -Djkube.deploy.createExternalUrls=true option to your Maven commands if you want it to deploy a Route configuration for the service.

Use this URL to display the root of the REST service, which also allows to access the WADL of the service:

http://karaf-cxf-rest-MY_PROJECT_NAME.OPENSHIFT_IP_ADDR.nip.io/cxf/crm

Use this URL to display the XML representation for customer 123:

http://karaf-cxf-rest-MY_PROJECT_NAME.OPENSHIFT_IP_ADDR.nip.io/cxf/crm/customerservice/customers/123

You can also access the XML representation for order 223 …​

http://karaf-cxf-rest-MY_PROJECT_NAME.OPENSHIFT_IP_ADDR.nip.io/cxf/crm/customerservice/orders/223

Note: if you use Safari, you will only see the text elements but not the XML tags - you can view the entire document with 'View Source'

To run a command-line utility:

You can use a command-line utility, such as cURL or wget, to perform the HTTP requests. We have provided a few files with sample XML representations in src/test/resources, so we will use those for testing our services.

1. Open a command prompt and change directory to karaf-cxf-rest.

2. Run the following curl commands (curl commands may not be available on all platforms):

   • Create a customer

     curl -X POST -T src/test/resources/add_customer.xml -H "Content-Type: text/xml" http://karaf-cxf-rest-MY_PROJECT_NAME.OPENSHIFT_IP_ADDR.nip.io/cxf/crm/customerservice/customers

   • Retrieve the customer instance with id 123

     curl http://quickstart-cxf-rest.f8/cxf/crm/customerservice/customers/123

   • Update the customer instance with id 123

     curl -X PUT -T src/test/resources/update_customer.xml -H "Content-Type: text/xml" http://karaf-cxf-rest-MY_PROJECT_NAME.OPENSHIFT_IP_ADDR.nip.io/cxf/crm/customerservice/customers

   • Delete the customer instance with id 123

     curl -X DELETE http://karaf-cxf-rest-MY_PROJECT_NAME.OPENSHIFT_IP_ADDR.nip.io/cxf/crm/customerservice/customers/123

Integration Testing

The example includes a Kubernetes Integration Test. Once the container image has been built and deployed in Kubernetes, the integration test can be run with:

mvn test -Dtest=*KT

The test is disabled by default and has to be enabled using -Dtest.

More details

You can find more details about running this quickstart on the website. This also includes instructions how to change the Docker image user and registry.