Page tree
Skip to end of metadata
Go to start of metadata

About this Tutorial

This tutorial exposes your Manager classes (or any other classes) as a web service with Apache CXF, a proven Open-Source Services Framework. It assumes you completed the Services tutorial and wrote a custom PersonManager class and PersonManagerImpl implementation.

Table of Contents

  1. Expose your Manager as a Web Service
    1. SOAP
    2. REST
  2. Securing your Web Service

Source Code

Icon

The code for this tutorial is located in the "tutorial-service" module of the appfuse-demos project on GitHub. Use the following command to check it out from Subversion:

svn co https://github.com/appfuse/appfuse-demos/trunk/tutorial-service

Expose your Manager as a Web Service

Thanks to annotations, it's very easy to expose your existing classes as web services. In fact, there are a couple of services that are already exposed in your AppFuse application. For the SOAP-based UserService, you can see the WSDL by running mvn jetty:run and navigating to http://localhost:8080/services/UserService?wsdl. You can view the REST equivalent (a WADL file) at http://localhost:8080/services/api?_wadl&_type=xml. All web services can be viewed at http://localhost:8080/services/.

Exposing a SOAP Service 

To expose your PersonManager (and its implementation) as a SOAP service, add a @WebService annotation to the interface.

Then add the same annotation to your PersonManagerImpl, specifying the service name and endpointInterface. You'll also need to add a public, no-args constructor to satisfy JAX-WS.

Open your src/main/webapp/WEB-INF/cxf-servlet.xml file and add the following declaration to tell CXF about your web service endpoint:

After making these changes, you should be able to run mvn jetty:run and view the WSDL for your PersonManager at http://localhost:8080/services/PersonService?wsdl.

Exposing a REST Service 

To expose your PersonManager (and its implementation) as a REST service, add a @PATH annotation to the interface and annotations to the method to indicate its path and supported methods. NOTE: This example includes the aforementioned @WebService annotation because it's perfectly acceptable to use both in the same files.

With JAX-RS, you don't need any additional annotations on your implementation. However, you'll still need to add the implementation of the getPeople() method and to tell CXF about your implementation class.

Add the getPeople() implementation to your PersonManagerImpl.

Next, open your src/main/webapp/WEB-INF/cxf-servlet.xml file and add the following XML in the <jaxrs:serviceBeans> section:

After making these changes, you should be able to run mvn jetty:run and view all the people in your database at http://localhost:8080/services/api/people.json.

XmlRootElement for XML

Icon

If you call the people service without the .json extension (http://localhost:8080/services/api/people), you'll likely get the following error:

No message body writer has been found for response class List.

To fix it, add the @XmlRootElement annotation to your Person.java class.

To continue creating your web application, please see the web tutorials.

Securing your Web Service

Web Services in AppFuse are unsecure by default. To secure them, the easiest thing to do is add /services/**=ROLE_NAME to your WEB-INF/security.xml file. For more information, see Securing a RESTful Web Service with Spring Security 3.1.

Limit exposed methods

When you add the annotations to your service classes, by default all public methods are exposed as web services. This might not be ideal. If you would like to limit the methods that are exposed, then do the following.

  1. Remove the @WebService from the service interface class (i.e PersonManager)
  2. Remove the endpoint attribute in the service implementation class (i.e PersonManagerImpl) so it only contains @WebService.
  3. Add @WebMethod(exclude=true) for each public method in the implemented class (i.e PersonManagerImpl) that you would not like exposed as a web service. This includes methods defined in parent classes as well (i.e GenericManagerImpl)
  4. Add @WebMethod on each public method that you would like to expose as a web service.