73 WEM Framework: Developing Custom REST Resources

This chapter contains the following sections:

73.1 The Recommendations Sample Application

The "Recommendations" sample application demonstrates how to create REST resources for WebCenter Sites and Satellite Server. The application registers a new REST resource sample/recommendations/<id> with GET and POST operations, which allow for retrieval and modification of static list recommendations. The application also demonstrates how it is possible to leverage the Satellite Server caching system.

This section contains the following topics:

73.1.1 Building and Deploying the Application

  1. The "Recommendations" sample application is located in the Misc/Samples folder under your WebCenter Sites installation directory. Navigate to recommendations and edit the build.properties file. Specify the correct paths for cs.webapp.dir and ss.webapp.dir properties.

  2. Run Apache ant while in the recommendations folder. This will build and deploy your sample application.

  3. Launch the catalogmover application. Use the Server, Connect menu to connect to WebCenter Sites. Go to Catalog, then Auto Import Catalog(s) and select src\main\schema\elements.zip file. Append xceladmin, xceleditor when specifying the list of ACLs.

  4. Go to the WebCenter Sites web application folder. Edit the WEB-INF/classes/custom/RestResource.xml file. Uncomment recommendationService, recommendationConfig and resourceConfigs beans.

  5. Go to the Satellite Server web application folder. Edit WEB-INF/classes/custom/RestResource.xml file. Uncomment recommendationService, recommendationConfig, and resourceConfigs beans.

  6. Restart both WebCenter Sites and Satellite Server.

73.1.2 Testing the Application

Use the existing static list recommendation id (or create a new recommendation) for the URL http://<hostname>:<port>/<contextpath>/REST/sample/recommendations/<recommendationid>. Use the same URL for both WebCenter Sites and Satellite Server installations. For example, use http://localhost:8080/cs/REST/sample/recommendations/1266874492697. See the XML response for both WebCenter Sites and Satellite Server.

73.2 Creating REST Resources

This section contains the following topics:

73.2.1 Application Structure

The "Recommendations" sample application was created to guide you through the process of creating your own REST resources.

Figure 73-1 Recommendations" Sample Application

Description of Figure 73-1 follows
Description of "Figure 73-1 Recommendations" Sample Application"

  • Schema files: src/main/schema

    • elements.zip contains a sample element, which is used by Satellite Server for caching purposes.

    • jaxb.binding is a customization for the default JAXB bindings used during the bean generation process.

    • recommendation.xsd is an XML schema for the RecommendationService beans.

  • Java source files: src/main/java/ ... /sample

    • RecommendationResource contains the REST resource implementation. It is used on both WebCenter Sites and Satellite Server.

    • RecommendationService is an interface that provides the functionality for the RecommendationResource class. It is implemented differently, depending on where the resource is hosted: locally (on WebCenter Sites) or remotely (on Satellite Server).

    • beans/* classes are generated using Java xjc compiler. They are pre-packaged with the application. If you want to regenerate beans (i.e., when changing the recommendation.xsd file) you can run "generate" ant's task from build.xml.

    • LocalRecommendationService is a local (WebCenter Sites) implementation for the RecommendationService interface.

    • RemoteRecommendationService is a remote (Satellite Server) implementation for the RecommendationService interface.

73.2.2 Steps for Implementing Custom REST Resources

  1. Write your XSD file describing your REST service (recommendations.xsd file).

  2. Generate beans using the JAXB xjc utility ("generate" ant's task).

  3. Create your REST interface, which will be implemented differently for WebCenter Sites and Satellite Server.

  4. Implement the REST interface by extending the following classes: com.fatwire.rest.BaseLocalService com.fatwire.rest.BaseRemoteService

  5. This step is optional in case you decide to leverage Satellite Server caching:

    Create elements on the WebCenter Sites side, which load the same assets as the local implementation does.

  6. Create your REST resource class by extending the com.fatwire.rest.BaseResource class.

  7. Register your REST service and configuration in WEB-INF/classes/custom/RestResources.xml file on both WebCenter Sites and Satellite Server sides.

    The custom/RestResources.xml file contains the following components:

    • The only mandatory bean is the bean with resourceConfigs id. The resourceConfigs property contains references to all REST configurations used.

      Note:

      If custom resourceConfigs is uncommented, then bean should be referenced. Otherwise, the default REST resource, which is provided with the WEM installation will not be registered.

    • Resource configurations must be of type com.fatwire.rest.ResourceConfig. Typically only one instance of this class is registered (multiple services can be registered per configuration.

      Note:

      For multiple services, create a new configuration for each disjoint group of your REST services, usually identified by separate XSD files.

    • The resourceClasses property contains the list of all resources used.

    • beanPackage contains the Java package name specified for the output beans when running the xjc utility.

    • schemaLocation is the xsi:schemaLocation attribute to be put in all output XML files produced by your REST service.