com.isomorphic.servlet

## Class RESTHandler

- com.isomorphic.servlet.RESTHandler

-     public class RESTHandler

  This servlet handles built-in SmartClient datasource requests sent from REST clients. The `RestDataSource` provided with SmartClient is such a client, as is SmartGWT.mobile, but this handler will work with any REST client that encodes its data as JSON or XML, sends its requests as POST messages and conforms to the REST transfer protocol described in the client-side documentation for `RestDataSource`. Note that you must read these client-side documents in order to understand how to properly format a REST request for processing by this servlet.

  By default JSON responses will be wrapped into special markers so that code is not directly executable outside of your application. This is a preventive measure against javascript hijacking.

  The servlet accepts parameter "wrapJSONResponses": `true` - wrap JSON responses; `false` - send plain JSON reponses. The parameter can be set in your web.xml file either as a context parameter (for all servlets) or as a servlet initialization parameter.

  If JSON wrapping is on, you can also set the prefix and suffix strings that we use to wrap responses. Again, you do this by setting the parameters "jsonPrefix" and "jsonSuffix" in your web.xml file, either as a context parameter (for all servlets) or as a servlet initialization parameter. If these parameters are not set in web.xml, they default as follows:
  jsonPrefix: "<SCRIPT>//'\"]]>>isc_JSONResponseStart>>"
  jsonSuffix: "//isc_JSONResponseEnd"

  Note that these parameters can be overridden at the DataSource level, by providing a `.ds.xml` file for the DataSource, and specifying `jsonPrefix` and `jsonSuffix` in there.

  NOTE: The default settings shown above are also the defaults used by the client-side RestDataSource. If you choose to change the default prefix and/or suffix strings returned by the server, you must obviously also change the strings that the client expects to see. If you are using RestDataSource, you do this by overriding the `jsonPrefix` and `jsonSuffix` properties. See the client-side documentation for details.

  The servlet also accepts parameter "defaultDataFormat". This governs whether we expect requests to be encoded as XML or JSON, if no explicit dataFormat is provided with the request. Note that the dataFormat is explicitly sent with every request if you are using the Isomorphic `RestDataSource` (see below), so this parameter has no effect in that case; it is only used when no dataFormat is provided with the request, as would be the case if you are integrating with a third-party REST client.

  If you do not specify a defaultDataFormat, "xml" is assumed.

  The servlet also accepts parameter "dynamicDataFormatParamName". This governs the name of the dataFormat parameter we look for in incoming requests (as described above in the paragraph about "defaultDataFormat"). If you wish to send the dataFormat to use with each client request, you send an HTTP parameter with this name in the request, with a value of "xml" or "json". By default, the "dynamicDataFormatParamName" is the value used by the SmartClient RestDataSource: "isc_dataFormat".

  NOTE: This servlet is configured to automatically set character encoding on requests and responses to UTF-8. If you wish to force a different encoding, you can do so by specifying the `init-param` "encoding" in your web.xml file, as shown in the example below. If you wish to switch off explicit encoding altogether, use the `init-param` to set a value of "none".

  Please see the client-side documentation on Internationalization for a discussion of why this procedure is necessary.

  This snippet shows how you might change your `web.xml` file to configure the `RESTHandler` servlet:

         <servlet>
             <servlet-name>RESTHandler</servlet-name>
             <servlet-class>com.isomorphic.servlet.RESTHandler</servlet-class>
             <init-param>
                 <param-name>defaultDataFormat</param-name>
                 <param-value>json</param-value>
             </init-param>
             <init-param>
                 <param-name>dynamicDataFormatParamName</param-name>
                 <param-value>theDataFormat</param-value>
             </init-param>
             <init-param>
                 <param-name>wrapJSONResponses</param-name>
                 <param-value>false</param-value>
             </init-param>
             <init-param>
                 <param-name>encoding</param-name>
                 <param-value>some-other-encoding</param-value>
             </init-param>
         </servlet>
         <servlet-mapping>
             <servlet-name>RESTHandler</servlet-name>
             <url-pattern>/restapi/</url-pattern>
         </servlet-mapping>

  See Also:
    Serialized Form

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `processRequest(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)` Servlet entry point to process the request.

- - ### Method Detail

    - #### processRequest

          public void processRequest(javax.servlet.http.HttpServletRequest request,
                            javax.servlet.http.HttpServletResponse response)
                              throws javax.servlet.ServletException,
                                     java.io.IOException

      Servlet entry point to process the request. Default implementation instantiates an RPCManager, and invokes handleDSRequest() for each DataSource operation encoded in the HTTP request.
      Parameters:
        `request` - The HttpServletRequest
        `response` - The HttpServletResponse
      Throws:
        `javax.servlet.ServletException` - As per HttpServlet.service()
        `java.io.IOException` - As per HttpServlet.service()