Installing the REST data service

This topic describes how to install the eXtreme Scale REST data service into a Web server.

Before you begin

Software requirements

The WebSphere eXtreme Scale REST data service is a Java Web application that can be deployed to any application server that supports Java servlet specification, Version 2.3 and a Java runtime environment, Version 5 or later.

The following software is required:
  • Java Standard Edition 5 or later
    Restriction: Although WebSphere eXtreme Scale supports Java Standard Edition 1.4 or later, the REST data service requires Java Standard Edition 5 or later.
  • Web servlet container, Version 2.3 or later, which includes one of the following:
    • WebSphere Application Server Version 6.1.0.25 or later
    • WebSphere Application Server Version 7.0.0.5 or later
    • WebSphere Community Edition Version 2.1.1.3 or later
    • Apache Tomcat Version 5.5 or later
  • WebSphere eXtreme Scale, Version 7.1 or later (including the trial)

About this task

The WebSphere eXtreme Scale REST data service includes a single WAR file wxsrestservice.war. The wxsrestservice.war includes a single servlet that acts as a gateway between your WCF Data Services client applications or any other HTTP REST client and an eXtreme Scale grid.

The REST data service includes a sample that allows you to quickly create an eXtreme Scale grid and interact with it using an eXtreme Scale client or the REST data service. See the topic, section for details on using the sample.

When WebSphere eXtreme Scale 7.0.0.0 with cumulative fix 2 is installed or the WebSphere eXtreme Scale Version 7.0 trial is extracted, the following directories and files are included:
  • /lib
    The lib directory contains the following files:
    • wxsrestservice.ear – The REST data service enterprise application archive for use with WebSphere Application Server and WebSphere Application Server CE.
    • wxsrestservice.war – The REST data service web module for use with Apache Tomcat.

    The wxsrestservice.ear includes the wxsrestservice.war and are both tightly coupled with the WebSphere eXtreme Scale runtime. If eXtreme Scale is upgraded to a new version or a fix pack applied, the wxsrestservice.war or wxsrestservice.ear will need to be manually upgraded to the version installed in this directory.

  • /gettingstarted

    The gettingstarted directory contains a simple sample that demonstrates how to use the eXtreme Scale REST data service with an eXtreme Scale grid.

Packaging and deploying the REST data service

The REST data service is designed as a self-contained WAR module. To configure the REST data service, you must first package the REST data service configuration and optional eXtreme Scale configuration files into a JAR file or directory. This application packaging is then referenced by the web container server runtime. Figure 7 illustrates files used by the eXtreme Scale REST data service.

The REST service configuration JAR or directory must contain the following file:

wxsRestService.properties: The wxsRestService.properties file includes the configuration options for the REST data service. This includes the catalog service endpoints, ObjectGrid names to expose, trace options and more. See section : for details.

The following ObjectGrid client files are optional:
  • META-INF/objectGridClient.xml: The ObjectGrid client override XML file is used to connect to the remote eXtreme Scale grid. By default this file is not required. If not present, the REST service will use the server configuration, disabling the near cache.
    The name of the file can be overridden using the objectGridClientXML REST data service configuration property. If provided, this XML file should include:
    1. Include any ObjectGrids that you want to expose to the REST data service.
    2. Include a reference to the entity descriptor xml file associated with each ObjectGrid configuration.
  • META-INF/<entity descriptor xml files>: One or more entity descriptor XML files are required only if the client needs to override the entity definition of the client. The entity descriptor XML file must be used in conjunction with the ObjectGrid client override XML descriptor file. For details on the eXtreme Scale configuration files, see the eXtreme Scale Administration Guide.
  • Entity classes Annotated entity classes or an entity descriptor XML file can be used to describe the entity metadata. The REST service only requires entity classes in the classpath if the eXtreme Scale servers are configured with entity metadata classes and a client override entity XML descriptor is not used.

    An example with the minimum required configuration file, where the entities are defined in XML on the servers:

    restserviceconfig.jar:
    wxsRestService.properties
    The property file contains:
    catalogServiceEndPoints=localhost:2809
    objectGridNames=NorthwindGrid

    An example with one entity, override XML files and entity classes:

    restserviceconfig.jar:
    wxsRestService.properties
    The property file contains:
    catalogServiceEndPoints=localhost:2809
    objectGridNames=NorthwindGrid
    com/acme/entities/Customer.class
    META-INF/objectGridClient.xml
    The client ObjectGrid descriptor XML file contains:
    <objectGrid name="CustomerGrid" entityMetadataXMLFile="emd.xml"/>
    META-INF/emd.xml
    The entity metadata descriptor XML file contains:
    <entity class-name="com.acme.entities.Customer" name="Customer"/>

    For details on the EntityManager API and configuring an eXtreme Scale client and server, see the WebSphere eXtreme Scale Administration Guide.