60 Developing Custom REST Resources with WEM Framework

Within the WEM Framework, you can develop custom REST resources as the Recommendation sample application demonstrate.

Topics:

60.1 Creating REST Resources for WebCenter Sites and Satellite Server: Example

Through the Recommendation sample application you can learn how you can 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.

Topics:

60.1.1 Building and Deploying the Recommendations Sample 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.

60.1.2 Testing the Recommendations Sample Application

You can test the Recommendations sample application as follows:

  • 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.

60.2 Creating REST Resources

This section includes the following topics:

60.2.1 About the Recommendations Sample Application's Structure

The Recommendations sample application (Figure 60-1) was created to guide you through the process of creating your own REST resources.

Figure 60-1 Recommendations Sample Application

Description of Figure 60-1 follows
Description of "Figure 60-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. To regenerate beans (that is, when changing the recommendation.xsd file), 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.

60.2.2 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 is not 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.