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>