project
Class XmlRpcServlet

java.lang.Object
  |
  +--javax.servlet.GenericServlet
        |
        +--javax.servlet.http.HttpServlet
              |
              +--project.XmlRpcServlet
Direct Known Subclasses:
ExampleServlet

public abstract class XmlRpcServlet
extends javax.servlet.http.HttpServlet
implements javax.servlet.SingleThreadModel

This servlet facilitates development of HTTP/HTTPS based XML messaging services, which add application-specific behaviours and handle specific kinds of request and response documents. It is only "RPC" in the sense that it is a synchronous exchange of structured messages, directed at a specific object (identified by the target of the POST).

See Also:
Serialized Form

Constructor Summary
protected XmlRpcServlet()
          The default constructor does nothing.
 
Method Summary
protected  void customizeDocument(com.sun.xml.tree.SimpleElementFactory factory, boolean trustDocuments)
          The request document that's built from the request can be customized, so that the generic DOM functionality can be augmented with behaviour specific to each element type.
protected  void customizeResolver(org.xml.sax.EntityResolver r)
          Subclasses can provide a customized entity resolver to be used when resolving external entities such as DTDs.
 void doPost(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
          The POST input and output are normally both XML documents.
 boolean getCheckTypes()
          Returns true (the default) if client messages are validated to ensure that certain basic content errors are not made.
protected  com.sun.xml.tree.XmlDocument getRequestDocument(javax.servlet.http.HttpServletRequest request)
          Returns the XML document sent in the request.
protected abstract  com.sun.xml.tree.XmlDocument rpc(java.lang.String pathInfo, com.sun.xml.tree.XmlDocument request)
          This method must be overridden in a subclass in order to handle the XML messaging request.
protected  void sendResponseDocument(com.sun.xml.tree.XmlDocument doc, javax.servlet.http.HttpServletResponse response)
          Sends the given XML document as the response to this request.
 void setCheckTypes(boolean value)
          This method is used to control whether client messages are type checked (validated).
 
Methods inherited from class javax.servlet.http.HttpServlet
doDelete, doGet, doOptions, doPut, doTrace, getLastModified, service, service
 
Methods inherited from class javax.servlet.GenericServlet
destroy, getInitParameter, getInitParameterNames, getServletConfig, getServletContext, getServletInfo, init, log
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

XmlRpcServlet

protected XmlRpcServlet()
The default constructor does nothing. Subclasses should override it to do whatever generic initialization they need, and should use the Servlet.init(ServletConfig config) method to perform any initialization that is substantial, or that is dependent on the Application environment in which the servlet runs (exposed through the ServletConfig interface).

Since this servlet implements the single thread model, it won't handle more than one request at a time.

Method Detail

rpc

protected abstract com.sun.xml.tree.XmlDocument rpc(java.lang.String pathInfo,
                                                    com.sun.xml.tree.XmlDocument request)
This method must be overridden in a subclass in order to handle the XML messaging request.

A more functional version would provide session context to the message handling code.

Parameters:
pathInfo - identifes the object being addressed, within the scope of the URIs handled by this servlet.
request - XML Document describing the request
Returns:
XML document describing the response

setCheckTypes

public void setCheckTypes(boolean value)
This method is used to control whether client messages are type checked (validated). By default, they are checked, since weak type checking is a major source of errors in larger systems. Even if validation isn't needed, errors in the well formedness of the XML response document will always cause fatal errors in the POST.

getCheckTypes

public boolean getCheckTypes()
Returns true (the default) if client messages are validated to ensure that certain basic content errors are not made.

customizeDocument

protected void customizeDocument(com.sun.xml.tree.SimpleElementFactory factory,
                                 boolean trustDocuments)
The request document that's built from the request can be customized, so that the generic DOM functionality can be augmented with behaviour specific to each element type. This method lets you describe the basic customizations to be performed, and optionally enable documents themselves to specify further customizations. This method MUST be re-invoked if the servlet is deserialized.
Parameters:
factory - used to acquire customized element nodes
trustDocuments - if true, the document can add its own mappings from element names to Java element node classes

customizeResolver

protected void customizeResolver(org.xml.sax.EntityResolver r)
Subclasses can provide a customized entity resolver to be used when resolving external entities such as DTDs. Typically, DTDs will be cached locally (perhaps as Java resources or files). In some cases, this handler may know how to handle other sorts of URI; for example, URIs which indicate the XML-formatted results of a database query.

getRequestDocument

protected com.sun.xml.tree.XmlDocument getRequestDocument(javax.servlet.http.HttpServletRequest request)
                                                   throws java.io.IOException,
                                                          org.xml.sax.SAXException
Returns the XML document sent in the request.

sendResponseDocument

protected void sendResponseDocument(com.sun.xml.tree.XmlDocument doc,
                                    javax.servlet.http.HttpServletResponse response)
                             throws java.io.IOException
Sends the given XML document as the response to this request.

doPost

public void doPost(javax.servlet.http.HttpServletRequest request,
                   javax.servlet.http.HttpServletResponse response)
            throws java.io.IOException
The POST input and output are normally both XML documents. However, a subclass might override this method if it needed flexibility in this area: perhaps dispatching on the request type, or needing request or response to not be XML.
Overrides:
doPost in class javax.servlet.http.HttpServlet