8
XSQL Pages Publishing Framework for Java

The XSQL Pages Publishing Framework is contained in the oracle.xml.xsql package, also known as Oracle XSQL Servlet.

This chapter describes the following sections:

• XSQLActionHandler Interface

• XSQLActionHandlerImpl Class

• XSQLPageRequest Interface

• XSQLParserHelper Class

• XSQLRequest Class

• XSQLRequestObjectListener Interface

• XSQLServletPageRequest Class

• XSQLStylesheetProcessor Class

• XSQLConnectionManager Interface

• XSQLConnectionManagerFactory Interface

• XSQLDocumentSerializer Interface

  See Also: Oracle Application Developer's Guide - XML

---

oracle.xml.xsql Package

The Oracle XSQL Pages Publishing Framework engine. Table 8-1 summarizes the classes and interfaces of this package.

Table 8-1  Summary of Classes and Interfaces of oracle.xml.xsql

Class/Interface	Description
XSQLActionHandler Interface	Interface that must be implemented by all XSQL Action Element Handlers
XSQLActionHandlerImpl Class	Base Implementation of XSQLActionHandler that can be extended to create your own custom handlers.
XSQLPageRequest Interface	Interface representing a request for an XSQL Page
XSQLParserHelper Class	Common XML Parsing Routines
XSQLRequest Class	Programmatically process a request for an XSQL Page.
XSQLRequestObjectListener Interface	Interface that an object created by an action handler. Can implement to be notified when the current page request processing is completed.
XSQLServletPageRequest Class	Implementation of XSQLPageRequest for Servlet-based XSQL Page requests.
XSQLStylesheetProcessor Class	XSLT Stylesheet Processing Engine
XSQLConnectionManager Interface	Must be implemented to override the built-in connection manager implementation.
XSQLConnectionManagerFactory Interface	Must be implemented to override the built-in connection manager implementation.
XSQLDocumentSerializer Interface	Must be implemented by all XSQL Serializers which serialize an XSQL data page as an XML Document to a PrintWriter.

---

XSQLActionHandler Interface

Implemented by all XSQL Action Element Handlers. Upon encountering an XSQL Action Element of the form <xsql:xxxx> in an XSQL page, the XSQL Page Processor invokes the associated XSQL Action Handler by constructing an instance of the handler using the no-args constructor, and invoking the XSQL Action Handler's handleAction() method.

Syntax

public interface XSQLActionHandler

Table 8-2 Summary of Methods of XSDLAction Handler

Method	Description
handleAction()	Handle the action.
init()	Initializes the Action Handler.

---

handleAction()

Handle the action by executing code and appending new child DOM nodes to the root. The XSQL Page Processor replaces the action element in the XSQL Page being processed with the document fragment of nodes.

Syntax

public void handleAction( oracle.xml.xsql.Node rootNode);

Parameter	Description
rootNode	Root node of generated document fragment.

---

init()

Initializes the Action Handler.

Syntax

public void init( XSQLPageRequest env, oracle.xml.xsql.Element e);

Parameter	Description
env	XSQLPageRequest object.
e	DOM element representing the Action Element being handled.

---

XSQLActionHandlerImpl Class

Base Implementation of XSQLActionHandler that creates custom handlers. Includes a set of useful helper methods. If there is an intent to extend this class and override the init() method, a call must be made to super.init(env,e).

Syntax

public abstract class XSQLActionHandlerImpl extends java.lang.Object implements 
XSQLActionHandler Interface
 

Table 8-3  Summary of Methods of XSQLActionHandlerImpl

Method	Description
XSQLActionHandlerImpl()	Class constructor.
init()	Initializes the action handler.

---

XSQLActionHandlerImpl()

Class constructor.

Syntax

public  XSQLActionHandlerImpl();

---

init()

Initializes the action handler.

Syntax

public void init( XSQLPageRequest env, oracle.xml.xsql.Element e);

Parameter	Description
env	The XSQLPageRequest context.
e	The action element

---

XSQLPageRequest Interface

Interface representing a request for an XSQL Page.

Syntax

public interface XSQLPageRequest

I

Table 8-4  Summary of Methods of XSQLPageRequest

Method	Description
createNestedRequest()	Returns an instance of a nested Request
getConnectionName()	Returns the name of the connection being used for this request May be null if no connection set/in-use.
getErrorWriter()	Returns a PrintWriter to print out errors processing this request
getJDBCConnection()	Gets the JDBC connection being used for this request (can be null)
getPageEncoding()	Returns encoding of source XSQL Page associated with this request
getParameter()	Returns the value of the requested parameter
getPostedDocument()	Returns the content of Posted XML for this request as an XML Document
getRequestParamsAsXMLDocument()	Returns the content of a Request parameters as an XML Document
getRequestType()	Returns a string identifying the type of page request being made.
getSourceDocumentURI()	Returns a String representation of the requested document's URI
getStylesheetParameter()	Gets a stylesheet parameter by name
getStylesheetParameters()	Gets an enumeration of stylesheet parameter names
getStylesheetURI()	Returns the URI of the stylesheet to be used to process the result.
getUserAgent()	Returns a String identifier of the requesting program
getWriter()	Returns a PrintWriter used for writing out the results of a page request
getXSQLConnection()	Gets the XSQLConnection Object being used for this request Might be null.
isIncludedRequest()	Returns true if this request is being included in another.
isOracleDriver()	Returns true if the current connection uses the Oracle JDBC Driver
printedErrorHeader()	Returns the state of whether an Error Header has been printed
requestProcessed()	Allows Page Request to Perform end-of-request processing
setConnectionName()	Sets the connection name to use for this request
setContentType()	Sets the content type of the resulting page
setIncludingRequest()	Sets the Including Page Request object for this request.
setPageEncoding()	Sets encoding of source XSQL page associated with this request.
setPageParam()	Sets a dynamic page parameter value.
setPostedDocument()	Allows programmatic setting of the Posted Document
setPrintedErrorHeader()	Sets whether an Error Header has been printed
setStylesheetParameter()	Sets the value of a parameter to be passed to the associated stylesheet
setStylesheetURI()	Sets the URI of the stylesheet to be used to process the result.
translateURL()	Returns a string representing an absolute URL resolved relative to the base URI for this request.
useConnectionPooling()	Returns true if connection pooling is desired for this request
useHTMLErrors()	Returns true if HTML-formatted error messages are desired for this request.
setRequestObject()	Sets a request-scope object.
getRequestObject()	Gets a request-scope object.

---

createNestedRequest()

Returns an instance of a nested Request.

Syntax

public XSQLPageRequest createNestedRequest(
                   java.net.URL pageurl,
                   java.util.Dictionary params);

Parameter	Description
pageurl	The URL of the nested request.
params	Optional dictionary of additional parameters.

---

getConnectionName()

Returns the name of the connection being used for this request May be null if no connection set/in-use.

Syntax

public java.lang.String getConnectionName();

---

getErrorWriter()

Returns a PrintWriter to print out errors processing this request.

Syntax

public java.io.PrintWriter getErrorWriter();

---

getJDBCConnection()

Gets the JDBC connection being used for this request (can be null).

Syntax

public java.sql.Connection getJDBCConnection();

---

getPageEncoding()

Returns encoding of source XSQL Page associated with this request.

Syntax

public java.lang.String getPageEncoding();

---

getParameter()

Returns the value of the requested parameter.

Syntax

public String getParameter( String name);

Parameter	Description
name	The name of the parameter.

---

getPostedDocument()

Returns the content of Posted XML for this request as an XML Document.

Syntax

public oracle.xml.xsql.Document getPostedDocument();

---

getRequestParamsAsXMLDocument()

Returns the content of a Request parameters as an XML Document.

Syntax

public oracle.xml.xsql.Document getRequestParamsAsXMLDocument();

---

getRequestType()

Returns a string identifying the type of page request being made.

Syntax

public String getRequestType();

---

getSourceDocumentURI()

Returns a String representation of the requested document's URI.

Syntax

public String getSourceDocumentURI();

---

getStylesheetParameter()

Gets a stylesheet parameter by name.

Syntax

public String getStylesheetParameter( String name);

Parameter	Description
name	The stylesheet parameter name.

---

getStylesheetParameters()

Gets an enumeration of stylesheet parameter names.

Syntax

public java.util.Enumeration getStylesheetParameters();

---

getStylesheetURI()

Returns the URI of the stylesheet to be used to process the result.

Syntax

public java.lang.String getStylesheetURI();

---

getUserAgent()

Returns a String identifier of the requesting program.

Syntax

public java.lang.String getUserAgent();

---

getWriter()

Returns a PrintWriter used for writing out the results of a page request.

Syntax

public java.io.PrintWriter getWriter();

---

getXSQLConnection()

Gets the XSQLConnection Object being used for this request Might be null.

Syntax

public oracle.xml.xsql.XSQLConnection getXSQLConnection();

---

isIncludedRequest()

Returns true if this request is being included in another.

Syntax

public boolean isIncludedRequest();

---

isOracleDriver()

Returns true if the current connection uses the Oracle JDBC Driver.

Syntax

public boolean isOracleDriver();

---

printedErrorHeader()

Returns the state of whether an Error Header has been printed.

Syntax

public boolean printedErrorHeader();

---

requestProcessed()

Allows Page Request to Perform end-of-request processing.

Syntax

public void requestProcessed();

---

setConnectionName()

Sets the connection name to use for this request.

Syntax

public void setConnectionName( String connName);

Parameter	Description
connName	The name of the connection.

---

setContentType()

Sets the content type of the resulting page.

Syntax

public void setContentType( String mimetype);

Parameter	Description
mimetype	The MIME type that describes the content of the resulting page.

---

setIncludingRequest()

Sets the Including Page Request object for this request.

Syntax

public void setIncludingRequest( XMLPageRequest includingEnv);

Parameter	Description
includingEnv	The XSQLPageRequest context of the including page.

---

setPageEncoding()

Sets encoding of source XSQL page associated with this request.

Syntax

public void setPageEncoding( String enc);

Parameter	Description
enc	The encoding of the current page.

---

setPageParam()

Sets encoding of source XSQL page associated with this request.

Syntax

public void setPageParam( String name, String value);

Parameter	Description
name	The name of the page-private parameter.
value	The value of the page-private parameter.

---

setPostedDocument()

Allows programmatic setting of the Posted Document.

Syntax

public void setPostedDocument( org.w3c.dom.Document doc);

Parameter	Description
doc	The XML document that has been posted as part of this request.

---

setPrintedErrorHeader()

Sets whether an Error Header has been printed.

Syntax

public void setPrintedErrorHeader( boolean yes);

Parameter	Description
yes	Sets whether the error header has been printed.

---

setStylesheetParameter()

Sets the value of a parameter to be passed to the associated stylesheet.

Syntax

public void setStylesheetParameter( java.lang.String name,
                                    java.lang.String value);

Parameter	Description
name	The name of the stylesheet parameter.
value	The value of the stylesheet parameter.

---

setStylesheetURI()

Sets the URI of the stylesheet to be used to process the result.

Syntax

public void setStylesheetURI( String uri);

Parameter	Description
uri	The uri of the stylesheet to be used to transform this request.

---

translateURL()

Returns a string representing an absolute URL resolved relative to the base URI for this request.

Syntax

public String translateURL( String url);

Parameter	Description
url	The url of the stylesheet to be used to translate this request.

---

useConnectionPooling()

Returns true if connection pooling is desired for this request.

Syntax

public boolean useConnectionPooling();

---

useHTMLErrors()

Returns true if HTML-formatted error messages are desired for this request.

Syntax

public boolean useHTMLErrors();

---

setRequestObject()

Sets a request-scope object.

Syntax

void setRequestObject( String name,
                       Object obj);

Parameter	Description
name	Name of the request-scope object to set.
obj	The request-scope object itself.

---

getRequestObject()

Gets a request-scope object.

Syntax

Object getRequestObject( String name);

Parameter	Description
name	Name of the request-scope object to retrieve.

---

XSQLParserHelper Class

Common XML Parsing Routines.

Syntax

public final class XSQLParserHelper extends java.lang.Object
 

Table 8-5  Summary of Methods of XSQLParserHelper

Method	Description
XSQLParserHelper()	Class constructor.
newDocument()	Returns a new, empty XML document.
parse()	Parses an XML document from a variety of sources.
parseFromString()	Parses an XML document from a string.
print()	Prints an XML document.

---

XSQLParserHelper()

Class constructor.

Syntax

public  XSQLParserHelper();

---

newDocument()

Returns a new, empty XML document.

Syntax

public static oracle.xml.xsql.Document newDocument();

---

parse()

Parses an XML document from a variety of sources. The options are described in the following table.

Syntax	Description
public static oracle.xml.xsql.Document parse( InputStream is, URL baseUrl, PrintWriter errorWriter);	Parses an XML document from an InputStream object.
public static oracle.xml.xsql.Document parse( Reader r, PrintWriter errorWriter);	Parses an XML document from a Reader object.
public static oracle.xml.xsql.Document parse( URL url, PrintWriter errorWriter);	Parses an XML document from a URL.

Parameter	Description
is	Input stream containing XML to parse.
baseUrl	The base URL of the XML document.
errorWriter	PrintWriter to receive any error messages.
r	Reader containing XML to parse.
url	URL of the XML document to parse.

---

parseFromString()

Parses an XML document from a string. The options are described in the following table.

Syntax	Description
public static oracle.xml.xsql.Document parseFromString( StringBuffer xmlString, PrintWriter errorWriter);	Parses from a StringBuffer.
public static oracle.xml.xsql.Document parseFromString( String xmlString, PrintWriter errorWriter);	Parses from a String.

Parameter	Description
xmlString	String containing XML to parser.
errorWriter	PrintWriter to receive any error messages.

---

print()

Prints an XML document.

Syntax

public static void print(  org.w3c.docm.Document doc,

                               java.io.PrintWriter out);

Parameter	Description
doc	The XML document to print.
out	The PrintWirter to use for serializing the document.

---

XSQLRequest Class

Programmatically process a request for an XSQL Page.

Syntax

public class XSQLRequest extends java.lang.Object
 

Table 8-6 Summary of Methods of XSQLRequest

Method	Description
XSQLRequest()	Class constructor. Create a Request for an XSQL Page
process()	Process the request, writing output/errors.
processToXML()	Process the request, writing output/errors.
setPostedDocument()	Programmatically set an XML Document to be treated the same as if it were posted as part of the request.

---

XSQLRequest()

Constructs an instance of XSQLRequest from various sources.

Syntax

public  XSQLRequest( java.lang.String url);

Parameter	Description
url	The URL for the XSQL Page source to process.

---

process()

Process the request, writing output/errors. The options are described in the following table.

Syntax	Description
public void process();	Process the request, writing output/errors to System.out/System.err.
public void process( Dictionary params);	Process the request, writing output/errors to System.out/System.err.
public void process( Dictionary params, PrintWriter out, PrintWriter err);	Process the request, writing output/errors to respective PrintWriters.
public void process( PrintWriter out, PrintWriter err);	Process the request, writing output/errors to respective PrintWriters.

Parameter	Description
params	Dictionary with XSQL Page parameters.
out	PrintWriter to use to write the resulting page results.
err	PrintWriter to use to write the resulting page errors.

---

processToXML()

Process the request, writing output/errors. The options are described in the following table.

Syntax	Description
public org.w3c.dom.Document processToXML()	Process the request, writing output/errors to System.out/System.err
public org.w3c.dom.Document processToXML( Dictionary params)	Process the request, writing output/errors to System.out/System.err
public org.w3c.dom.Document processToXML( Dictionary params, PrintWriter err)	Process the request, writing output/errors to respective PrintWriters
public org.w3c.dom.Document processToXML( PrintWriter err);	Process the request, writing errors to respective PrintWriters

Parameter	Description
params	Dictionary with XSQL Page parameters
err	PrintWriter to use to write the resulting page errors

---

setPostedDocument()

Programmatically set an XML Document to be treated the same as if it were posted as part of the request.

Syntax

public void setPostedDocument( org.w3c.dom.Document postedDoc)

Parameter	Description
postedDoc	DOM Document

---

XSQLRequestObjectListener Interface

Interface that an object created by an action handler. Can implement to be notified when the current page request processing is completed. Objects that implement this interface and which are added to the current request context using XSQLPageRequest::setRequestObject() will be notified when the page processing of the outermost page is completed.

---

pageProcessingCompleted()

Callback method that allows Request scope objects to be notified when the page processing is complete so they can clean up any allocated resources. Any request-scope object that implements the XSQLRequestObjectListener interface will be notified this manner.

Syntax

void pageProcessingCompleted();

---

XSQLServletPageRequest Class

Syntax

public final class XSQLServletPageRequest extends XSQLPageRequestImpl
 

Table 8-7  Summary of Methods of XSQLServletPageRequest

Method	Description
XSQLServletPageRequest()	Creates a Servlet-specific XSQL Page request.
createNestedRequest()	Returns an instance of a nested Request.
getCookie()	Gets a vale of an HTTP Request cookie.
getHttpServletRequest()	Get the HttpServletRequest that initiated this XSQL Page Request.
getHttpServletResponse()	Get the HttpServletResponse that is associated with this XSQL Page Request.
getParameter()	Use HTTP Parameters as the source of parameters instead.
getPostedDocument()	Retrieves a posted XML document for this request.
getRequestParamsAsXMLDocument()	Retrieves request parameters as an XML document.
getRequestType()	Returns the type of request.
getUserAgent()	Returns the user agent string passed in from the browser.
setContentType()	Sets the content type of the resulting page.
setPageEncoding()	Sets the page encoding.
translateURL()	Returns a string representing an absolute URL resolved relative to the base URI for this request.
useHTMLErrors()	Sets whether HTML-formatted errors should be used.

---

XSQLServletPageRequest()

Creates a Servlet-specific XSQL Page request.

Syntax

public XSQLServletPageRequest( 
                    oracle.xml.xsql.HttpServletRequest req,
                    oracle.xml.xsql.HttpServletResponse resp);

Parameter	Description
req	Request.
resp	Response.

---

createNestedRequest()

Returns an instance of a nested Request.

Syntax

public XSQLPageRequest createNestedRequest(
                    java.net.URL pageurl,
                    java.util.Dictionary params)

Parameter	Description
pageurl	Page URL.
prams	Parameters of the request.

---

getCookie()

Gets a vale of an HTTP Request cookie.

Syntax

public java.lang.String getCookie(   String name);

Parameter	Description
name	Name of the cookie to get.

---

getHttpServletRequest()

Get the HttpServletRequest that initiated this XSQL Page Request.

Syntax

public oracle.xml.xsql.HttpServletRequest getHttpServletRequest();

---

getHttpServletResponse()

Get the HttpServletResponse that is associated with this XSQL Page Request.

Syntax

public oracle.xml.xsql.HttpServletResponse getHttpServletResponse();

---

getParameter()

Use HTTP Parameters as the source of parameters instead.

Syntax

public java.lang.String getParameter( String name);

Parameter	Description
name	Name of the paramete4r whose value is to be retrieved.

---

getPostedDocument()

Retrieves a posted XML document for this request. Returns NULL if there is none.

Syntax

public oracle.xml.xsql.Document getPostedDocument();

---

getRequestParamsAsXMLDocument()

Retrieves request parameters as an XML document.

Syntax

public oracle.xml.xsql.Document getRequestParamsAsXMLDocument();

---

getRequestType()

Returns the type of request ("Servlet", "Programmatic", "Command Line", or "Custom").

Syntax

public java.lang.String getRequestType();

---

getUserAgent()

Returns the user agent string passed in from the browser.

Syntax

public java.lang.String getUserAgent();

---

setContentType()

Sets the content type of the resulting page.

Syntax

public void setContentType( String mimetype);

Parameter	Description
mimtype	The MIME type that describes the content of the resulting page.

---

setPageEncoding()

Sets the page encoding.

Syntax

public void setPageEncoding( String enc);

Parameter	Description
enc	The page encoding.

---

translateURL()

Returns a string representing an absolute URL resolved relative to the base URI for this request.

Syntax

public java.lang.String translateURL( String path);

Parameter	Description
path	The relative URL which will be translated to an absolute URL.

---

useHTMLErrors()

Sets whether HTML-formatted errors should be used.

Syntax

public boolean useHTMLErrors();

---

XSQLStylesheetProcessor Class

XSLT Stylesheet Processing Engine.

Syntax

public final class XSQLStylesheetProcessor extends java.lang.Object
 

Table 8-8  Summary of Methods of XSQLStylesheetProcessor

Method	Description
XSQLStylesheetProcessor()	Processes CSLT stylesheet transformations.
processToDocument()	Transforms an XML document by an XSLT stylesheet and returns the result as an XML document.
processToWriter()	Transforms an CML Document by an XSLT stylesheet and writes the result to a PrintWriter.
getServletContext()	Gets the Http Servlet Context.

---

XSQLStylesheetProcessor()

Processes CSLT stylesheet transformations.

Syntax

public  XSQLStylesheetProcessor();

---

processToDocument()

Transforms an XML document by an XSLT stylesheet and returns the result as an XML document.

Syntax

public static oracle.xml.xsql.Document processToDocument(
                org.w3c.dom.Document xml,  String xslURI, XSQLPageResuest env);

Parameter	Description
xml	The XML document.
xslURI	The XSL stylesheet URI.
env	The XSQLPageRequest context.

---

processToWriter()

Transforms an CML Document by an XSLT stylesheet and writes the result to a PrintWriter.

Syntax

public static void processToWriter( 
                    oracle.xml.xsql.Document xml,
                    String xslURI,
                    XSQLPageResuest env);

Parameter	Description
xml	The XML document.
xslURI	The XSL stylesheet URI.
env	The XSQLPageRequest context.

---

getServletContext()

Gets the Http Servlet Context.

Syntax

javax.servlet.ServletContext getServletContext();

---

XSQLConnectionManager Interface

One of two interfaces that must be implemented to override the built-in connection manager implementation. The XSQL Page Processor asks the XSQLConnectionManagerFactory associated with each request to create() an instance of an XSQLConnectionManager to service the current request.

In multithreaded environments, the implementation of XSQLConnectionManager must insure that an XSQLConnection instance returned by getConnection() is not used by another thread until it has been released by the XSQL Page Processor after the call to releaseConnection().

Syntax

public interface XSQLConnectionManager;

Table 8-9 Summary of Methods of XSQLConnectionManager

Method	Description
getConnection()	Gets a connection from the connection manager.
releaseConnection()	Releases the connection.

---

getConnection()

Gets a connection from the connection manager.

Syntax

XSQLConnection getConnection( String connName,
                              XSQLPageRequest env);

Parameter	Description
connName	The connection name.
env	The XSQLPageRequest context.

---

releaseConnection()

Releases the connection.

Syntax

void releaseConnection( XSQLConnection theConn,
                        XSQLPageRequest env);

Parameter	Description
theConn	The XSQL Connection object to be released.
env	The XSQLPageRequest context.

---

XSQLConnectionManagerFactory Interface

One of two interfaces that must be implemented to override the built-in connection manager implementation. The XSQL Page Processor asks the XSQLConnectionManagerFactory associated with each request to create() an instance of an XSQLConnectionManager to service the current request.

Syntax

public interface XSQLConnectionManagerFactory

---

create()

Returns an instance of an XSQLConnectionManager. Implementation can decide whether it is a new XSQLConnectionManager or a shared singleton.

Syntax

XSQLConnectionManager create();

---

XSQLDocumentSerializer Interface

Interface that must be implemented by all XSQL Serializers which serialize an XSQL data page as an XML Document to a PrintWriter.

Upon encountering a serializer="XXX" pseudo-attribute in an <?xml-stylesheet?> processing instruction, the XSQL Page Processor invokes the associated serializer by:

• Constructing an instance of the serializer using the no-args constructor

• Invoking the XSQL document serializer's serialize() method

An implementation of XSQLDocumentSerializer is expected to do the following actions.

• First, call env.setContentType() to set the content type

• Then, call env.getWriter() to get the Writer to write to

If the serializer throws an unhandled exception, the XSQL Page Processor will format the stacktrace.

See oracle.xml.xsql.src.serializers.XSQLSampleSerializer for an example.

Syntaxr

public interface XSQLDocumentSerializer

---

serialize()

Serializes the resulting XML document for the output writer.

Syntax

void serialize( org.w3c.dom.Document doc,
                XSQLPageRequest env);

Parameter	Description
doc	The XML document to serialize.
env	The XSQLPageRequest context.