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
Table of Contents
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:
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
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|
If you call the people service without the .json extension (http://localhost:8080/services/api/people), you'll likely get the following error:
To fix it, add the @XmlRootElement annotation to your
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.
i. Remove the @WebService from the service interface class (i.e PersonManager)
ii. Remove the endpoint attribute in the service implementation class (i.e PersonManagerImpl) so that it now look like this
@WebService(serviceName = "PersonService")
iii. 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)
iv. Add @WebMethod on each public method that you would like to expose as a webservice.