Customizing XSQL Action Handlers

See Figure 19-8, "XSQL Page Processor in Action" and Figure 19-9, "XSQL Page Processor: Processing Actions". XSQL Page Processor processes XSQL Pages by carrying out the following actions:

• Looks for Action Elements from the XSQL namespace.

• For each Action Element found, it invokes an appropriate action element handler class to process the element

Built-in XSQL Action Elements and Action Handler Classes

Table 19-6 shows the built-in action handlers provided with XSQL Pages for the following basic XSQL action elements.

Table 19-6 Built-In XSQL Elements and Action Handler Classes

XSQL Action Element	Handler Class in oracle.xml.xsql.actions
<xsql:query>	XSQLQueryHandler
<xsql:dml>	XSQLDMLHandler
<xsql:set-stylesheet-param>	XSQLStylesheetParameterHandler
<xsql:insert-request>	XSQLInsertRequestHandler
<xsql:include-xml>	XSQLIncludeXMLHandler
<xsql:include-request-params/>	XSQLIncludeRequestHandler
<xsql:include-xsql>	XSQLIncludeXSQLHandler
<xsql:include-owa>	XSQLIncludeOWAHandler
<xsql:action>	XSQLExtensionActionHandler
<xsql:ref-cursor-function>	XSQLRefCursorFunctionHandler
<xsql:include-param>	XSQLGetParameterHandler
<xsql:set-session-param>	XSQLSetSessionParamHandler
<xsql:set-page-param>	XSQLSetPageParamHandler
<xsql:set-cookie>	XSQLSetCookieHandler
<xsql:insert-param>	XSQLInsertParameterHandler

• Action Handlers are initialized by getting passed the XSQLPageRequest object for context and the root node of a DOM DocumentFragment to which the action handler should append any dynamically created elements or other DOM Nodes. The XSQL Page Processor replaces the action element in the template page with content of the DocumentFragment created by the appropriate Action Handler for the element.

• To create a custom Action Handler, you need to provide a class that implements the oracle.xml.xsql.XSQLActionHandler interface.

For convenience, you can save time by extending the base implementation class named oracle.xml.xsql.XSQLActionHandlerImpl that provides a default implementation of the init() method and offers a set of useful helper methods that should prove useful.

See Also: The XSQL Servlet Release Notes on OTN.

The following example shows a custom action handler MyIncludeXSQLHandler that leverages one of the built-in action handlers and then uses arbitrary Java code to modify the resulting XML fragment returned by that handler before appending its result to the XSQL page:

    import oracle.xml.xsql.*;
    import oracle.xml.xsql.actions.XSQLIncludeXSQLHandler;
    import org.w3c.dom.*;
    import java.sql.SQLException;
    public class MyIncludeXSQLHandler extends XSQLActionHandlerImpl {
      XSQLActionHandler nestedHandler = null;
      public void init(XSQLPageRequest req, Element action) {
        super.init(req, action);
        // Create an instance of an XSQLIncludeXSQLHandler
        // and init() the handler by passing the current request/action
        // This assumes the XSQLIncludeXSQLHandler will pick up its
        // href="xxx.xsql" attribute from the current action element.
        nestedHandler = new XSQLIncludeXSQLHandler();
        nestedHandler.init(req,action);
      }
      public void handleAction(Node result) throws SQLException {
        DocumentFragment df = 
result.getOwnerDocument().createDocumentFragment();
        nestedHandler.handleAction(df);
        // Custom Java code here can work on the returned document fragment
        // before appending the final, modified document to the result node.
        // For example, add an attribute to the first child
        Element e = (Element)df.getFirstChild();
        if (e != null) {
          e.setAttribute("ExtraAttribute","SomeValue");
        }
        result.appendChild(df);
      }
    }

Lastly, note that if you create custom action handlers that need to work differently based on whether the page is being requested through the XSQL Servlet, or the XSQL Command Line Utility, or programmatically through the XSQLRequest class, then in your Action Handler implementation you can call getPageRequest() to get a reference to the XSQLPageRequest interface for the current page request.

By calling getRequestType()on the XSQLPageRequest object, you can see if the request is coming from the "Servlet", "Command Line", or "Programmatic" routes respectively. If the return value is "Servlet", then you can get access to the HTTP Servlet's request and response objects by:

XSQLServletPageRequest xspr = (XSQLServletPageRequest)getPageRequest();
     if (xspr.getRequestType().equals("Servlet")) {
       HttpServletRequest     req  = xspr.getHttpServletRequest();
       HttpServletResponse   resp  = xspr.getHttpServletResponse();
         // do something fun here with req and resp, however
         // writing to the response directly from a handler will
         // produce unexpected results. Allow the XSQL Servlet
         // to write to the servlet's response output stream
         // at the write moment later when all action elements
         // have been processed.
     }