Installing the REST data service

This topic describes how to install the WebSphere® 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 6 or later
Web servlet container, Version 2.3 or later, which includes one of the following:
- 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 wxsrestservice.war file. The wxsrestservice.war file includes a single servlet that acts as a gateway between your WCF Data Services client applications or any other HTTP REST client and a data grid.

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

When WebSphere eXtreme Scale 7.1 is installed or the eXtreme Scale Version 7.1 trial is extracted, the following directories and files are included:

restservice_home/lib
The lib directory contains these 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 file includes the wxsrestservice.war file and are both tightly coupled with the WebSphere WebSphere eXtreme Scale runtime. If WebSphere eXtreme Scale is upgraded to a new version or a fix pack applied, the wxsrestservice.war file or wxsrestservice.ear file will need to be manually upgraded to the version installed in this directory.
restservice_home/gettingstarted
The gettingstarted directory contains a simple sample that demonstrates how to use the WebSphere eXtreme Scale REST data service with a data grid.

Procedure

Package and deploy 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 WebSphere eXtreme Scale configuration files into a JAR file or directory. This application packaging is then referenced by the web container server runtime. The following diagram illustrates files used by the eXtreme Scale REST data service.

Figure 1. WebSphere eXtreme Scale REST Data Service Files

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 REST data service properties file.

The following ObjectGrid client files are optional:

META-INF/objectGridClient.xml: The ObjectGrid client override XML file is used to connect to the remote data grid. By default this file is not required. If this file is not present, the REST service uses 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. Any ObjectGrids that you want to expose to the REST data service.
2. Any 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.
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"/>
```