Skip to content

README.md

rest: demonstrates RESTful web services with CXF

Author: Fuse Team
Level: Beginner
Technologies: Fuse, OSGi, CXF
Summary: Demonstrates RESTful web services with CXF
Target Product: Fuse
Source: https://github.com/jboss-fuse/quickstarts

What is it?

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

In studying this quick start you will learn:

  • how to configure the JAX-RS web services by using the blueprint configuration file.
  • how to use JAX-RS annotations to map methods and classes to URIs
  • how to use JAXB annotations to define beans and output XML responses
  • how to use the JAX-RS API to create HTTP responses

For more information see:

System requirements

Before building and running this quick start you need:

  • Maven 3.0.4 or higher
  • JDK 1.6 or 1.7
  • JBoss Fuse 6

Build and Deploy the Quickstart

  1. Change your working directory to rest directory.
  2. Run mvn clean install to build the quickstart.
  3. Start JBoss Fuse 6 by running bin/fuse (on Linux) or bin\fuse.bat (on Windows).
  4. In the JBoss Fuse console, enter the following commands:

    features:addurl mvn:org.jboss.quickstarts.fuse/rest/${project.version}/xml/features
    features:install quickstart-rest
    
  • Fuse should give you an id when the bundle is deployed
  • You can check that everything is ok by issuing the command:

    osgi:list
    

    your bundle should be present at the end of the list

Use the bundle

Browsing Web service metadata

A full listing of all CXF web services is available at

http://localhost:8181/cxf

After you deployed this quick start, you will see the following endpoint address appear in the 'Available RESTful services' section:

http://localhost:8181/cxf/crm

Note:: Don't try to access this endpoint address from browser, as it's inaccessible by design

Just below it, you'll find a link to the WADL describing all the root resources:

http://localhost:8181/cxf/crm?_wadl

You can also look at the more specific WADL, the only that only lists information about 'customerservice' itself:

http://localhost:8181/cxf/crm/customerservice?_wadl&_type=xml

Access services using a web browser

You can use any browser to perform a HTTP GET. This allows you to very easily test a few of the RESTful services we defined:

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

http://localhost:8181/cxf/crm/customerservice/customers/123

You can also access the XML representation for order 223 ...

http://localhost:8181/cxf/crm/customerservice/orders/223

... or the XML representation of product 323 in order 223 with

http://localhost:8181/cxf/crm/customerservice/orders/223/products/323

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 the tests:

In this quick start project, we also provide integration tests which perform a few HTTP requests to test our Web services. We created a Maven test profile to allow us to run tests code with a simple Maven command after having deployed the bundle to Fuse:

  1. Change to the rest directory.
  2. Run the following command:

    mvn -Ptest
    

The tests in src/test/java/org.jboss.quickstarts.fuse.rest/CrmTest make a sequence of RESTful invocations and displays the results.

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 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://localhost:8181/cxf/crm/customerservice/customers
      
    • Retrieve the customer instance with id 123

      curl http://localhost:8181/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://localhost:8181/cxf/crm/customerservice/customers
      
    • Delete the customer instance with id 123

       curl -X DELETE http://localhost:8181/cxf/crm/customerservice/customers/123
      

Changing /cxf servlet alias

By default CXF Servlet is assigned a '/cxf' alias. You can change it in a couple of ways

  1. Add org.apache.cxf.osgi.cfg to the /etc directory and set the org.apache.cxf.servlet.context property, for example:

    org.apache.cxf.servlet.context=/custom
    
  2. Use shell config commands, for example:

    config:edit org.apache.cxf.osgi
    config:propset org.apache.cxf.servlet.context /custom
    config:update
    

Undeploy the Bundle

To stop and undeploy the bundle in Fuse:

  1. Enter osgi:list command to retrieve your bundle id
  2. To stop and uninstall the bundle enter

    osgi:uninstall <id>
    
Something went wrong with that request. Please try again.