com.isomorphic.servlet

## Class IDACall

- java.lang.Object
- - javax.servlet.GenericServlet
  - - javax.servlet.http.HttpServlet
    - - com.isomorphic.servlet.BaseServlet
      - - com.isomorphic.servlet.IDACall

-     public class IDACall
      extends BaseServlet

  This servlet handles built-in SmartClient datasource operations by default. It is configured as the default actionURL for the RPCManager on the client-side. You can extend this class and use the API hooks provided here to do something custom, like Authentication/Authorization checks.

  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 an `init-param` in your web.xml file, like so:

       <servlet>
         <servlet-name>IDACall</servlet-name>
         <servlet-class>com.isomorphic.servlet.IDACall</servlet-class>
         <init-param>
           <param-name>encoding</param-name>
           <param-value>some-other-encoding</param-value>
         </init-param>
       </servlet>

  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.

  See Also:
    Serialized Form

- - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `DSResponse` | `handleDSRequest(DSRequest dsRequest, RPCManager rpc, RequestContext context)` This method is called by processRPCTransaction() to handle a DSRequest sent from the client.
    `DSResponse` | `handleDSRequestError(DSRequest dsRequest, RPCManager rpc, RequestContext context, java.lang.Throwable t)` This method is called by handleDSRequest() to handle an Exception thrown by execution.
    `RPCResponse` | `handleRPCRequest(RPCRequest rpcRequest, RPCManager rpc, RequestContext context)` This method is called by processRPCTransaction() to handle a RPCRequest sent from the client.
    `RPCResponse` | `handleRPCRequestError(RPCRequest rpcRequest, RPCManager rpc, RequestContext context, java.lang.Throwable t)` This method is called by handleRPCRequest() to handle an Exception thrown by execution.
    `void` | `prepareRPCTransaction(RPCManager rpc, RequestContext context)` Override point to allow the `RPCManager` or `DSTransaction` to be configured prior to `processRPCTransaction()` being called.
    `void` | `processRequest(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)` Servlet entry point to process the request.
    `void` | `processRPCTransaction(RPCManager rpc, RequestContext context)` Process an RPC transaction.

    - ### Methods inherited from class com.isomorphic.servlet.BaseServlet

      `handleError, handleError`

- - ### 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 RequestContext, and calls `IDACall.processRPCTransaction(RPCManager, RequestContext)` to handle each RPC encoded in this HTTP request.
      Parameters:
        `request` - The HttpServletRequest
        `response` - The HttpServletResponse
      Throws:
        `javax.servlet.ServletException` - As per HttpServlet.service()
        `java.io.IOException` - As per HttpServlet.service()

    - #### prepareRPCTransaction

          public void prepareRPCTransaction(RPCManager rpc,
                                            RequestContext context)

      Override point to allow the `RPCManager` or `DSTransaction` to be configured prior to `processRPCTransaction()` being called.

      For example, you can call `RPCManager.setUserId(java.lang.String)`. or `RPCManager.setTenantId(java.lang.String)`.

      See the client-side Multi-Tenacy documentation for major concepts and how to implement authorization.

      Parameters:
        `rpc` - The RPCManager for this HTTP request
        `context` - RequestContext class provides accessors to Servlet basics like HttpServletRequest, HttpServletResponse

    - #### processRPCTransaction

          public void processRPCTransaction(RPCManager rpc,
                                            RequestContext context)
                                     throws java.lang.Exception

      Process an RPC transaction. This method is called by processRequest() and iterates through each RPC in the transaction and executes them by calling `IDACall.handleRPCRequest(RPCRequest, RPCManager, RequestContext)` or `IDACall.handleDSRequest(DSRequest, RPCManager, RequestContext)` depending on the request type.
      Parameters:
        `rpc` - The RPCManager for this HTTP request
        `context` - RequestContext class provides accessors to Servlet basics like HttpServletRequest, HttpServletResponse
      Throws:
        `java.lang.Exception` - For backwards compatibility this method is still declared as throwing an exception, but the default implementation logic traps and handles all Exceptions.

    - #### handleDSRequest

          public DSResponse handleDSRequest(DSRequest dsRequest,
                                            RPCManager rpc,
                                            RequestContext context)
                                     throws java.lang.Exception

      This method is called by processRPCTransaction() to handle a DSRequest sent from the client. This method may be called multiple times while processing a single HTTP request (if the client sent multiple requests in a batch via RPCManager.startQueue()).

      The default implementation of this method simply does this:

             try {
                 return dsRequest.execute();
             } catch (Throwable t1) {
                 return handleDSRequestError(dsRequest, rpc, context, t);
             }

      Parameters:
        `dsRequest` - The DSRequest to process
        `rpc` - The RPCManager that was used to demultiplex the DSRequest
        `context` - RequestContext class provides accessors to Servlet basics like HttpServletRequest, HttpServletResponse
      Throws:
        `java.lang.Exception` - For backwards compatibility this method is still declared as throwing an exception, but the default implementation logic (as shown above) traps and handles all Exceptions. DSResponse with an error status code and handle it on the client.

    - #### handleDSRequestError

          public DSResponse handleDSRequestError(DSRequest dsRequest,
                                                 RPCManager rpc,
                                                 RequestContext context,
                                                 java.lang.Throwable t)

      This method is called by handleDSRequest() to handle an Exception thrown by execution. This method may be called multiple times while processing a single HTTP request (if the client sent multiple requests in a batch via RPCManager.startQueue()).

      Note that if you want to provide your own custom handling, the recommended way to do this is to override this method to handle your specific cases and to then fall through to a call to `super.handleDSRequestError()`to allow the default error handling logic to handle various builtin features of the server.``

      Parameters:
        `dsRequest` - The DSRequest that resulted in an Exception being thrown
        `rpc` - The RPCManager that was used to demultiplex the DSRequest
        `context` - RequestContext class provides accessors to Servlet basics like HttpServletRequest, HttpServletResponse
        `t` - The Throwable that was thrown. Declared as a Throwable to trap both Exceptions and Errors. DSResponse with an error status code and handle it on the client.

    - #### handleRPCRequest

          public RPCResponse handleRPCRequest(RPCRequest rpcRequest,
                                              RPCManager rpc,
                                              RequestContext context)
                                       throws java.lang.Exception

      This method is called by processRPCTransaction() to handle a RPCRequest sent from the client. This method may be called multiple times while processing a single HTTP request (if the client sent multiple requests in a batch via RPCManager.startQueue()).

      The default implementation of this method simply does this:

             try {
                 return rpcRequest.execute();
             } catch (Throwable t) {
                 return handleRPCRequestError(rpcRequest, rpc, context, t)
             }

      Parameters:
        `rpcRequest` - The RPCRequest to process
        `rpc` - The RPCManager that was used to demultiplex the DSRequest
        `context` - RequestContext class provides access to Servlet basics like HttpServletRequest, HttpServletResponse
      Throws:
        `java.lang.Exception` - For backwards compatibility this method is still declared as throwing an exception, but the default implementation logic (as shown above) traps and handles all Exceptions.

    - #### handleRPCRequestError

          public RPCResponse handleRPCRequestError(RPCRequest rpcRequest,
                                                   RPCManager rpc,
                                                   RequestContext context,
                                                   java.lang.Throwable t)

      This method is called by handleRPCRequest() to handle an Exception thrown by execution. This method may be called multiple times while processing a single HTTP request (if the client sent multiple requests in a batch via RPCManager.startQueue()).

      Note that if you want to provide your own custom handling, the recommended way to do this is to override this method to handle your specific cases and to then fall through to a call to `super.handleRPCRequestError()`to allow the default error handling logic to handle various builtin features of the server.``

      Parameters:
        `rpcRequest` - The RPCRequest that resulted in an Exception being thrown
        `rpc` - The RPCManager that was used to demultiplex the RPCRequest
        `context` - RequestContext class provides accessors to Servlet basics like HttpServletRequest, HttpServletResponse
        `t` - The Throwable that was thrown. Declared as a Throwable to trap both Exceptions and Errors.