Oracle9i XML API Reference - XDK and Oracle XML DB Release 2 (9.2) Part Number A96616-01 |
|
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:
The Oracle XSQL Pages Publishing Framework engine. Table 9-1 summarizes the classes and interfaces of this package.
Interface that must be 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:
NOTE: conn parameter can be null if no connection specified for the XSQL page being processed.
public interface XSQLActionHandler
XSQLActionHandlerImpl Class
Method | Description |
---|---|
Handle the action, typically by executing some code and appending new child DOM nodes to the rootNode. |
|
Initializes the Action Handler. |
Handle the action, typically by executing some code and appending new child DOM nodes to the rootNode.
The XSQL Page Processor replaces the action element in the XSQL Page being processed with the document fragment of nodes that your handleAction method appends to the rootNode.
public void handleAction( oracle.xml.xsql.Node rootNode);
Parameter | Description |
---|---|
rootNode |
Root node of generated document fragment. |
Initializes the Action Handler
public void init( XSQLPageRequest env, oracle.xml.xsql.Element e);
Parameter | Description |
---|---|
env |
XSQLPageRequest object. |
e |
DOM element representing the Action Element being handled. |
Base Implementation of XSQLActionHandler that can be extended to create 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)
.
public abstract class XSQLActionHandlerImpl extends java.lang.Object implements XSQLActionHandler Interface java.lang.Object | +--oracle.xml.xsql.XSQLActionHandlerImpl
XSQLActionHandler Interface
Method | Description |
---|---|
Class constructor. |
|
Initializes the action handler. |
Class constructor.
public XSQLActionHandlerImpl();
Initializes the action handler.
public void init( XSQLPageRequest env, oracle.xml.xsql.Element e);
Parameter | Description |
---|---|
env |
The XSQLPageRequest context. |
e |
The action element |
Interface representing a request for an XSQL Page.
public interface XSQLPageRequest
XSQLPageRequestImpl Class
Returns an instance of a nested Request.
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. |
Returns the name of the connection being used for this request May be null if no connection set/in-use.
public java.lang.String getConnectionName();
Returns a PrintWriter to print out errors processing this request.
public java.io.PrintWriter getErrorWriter();
Gets the JDBC connection being used for this request (can be null).
public java.sql.Connection getJDBCConnection();
Returns encoding of source XSQL Page associated with this request.
public java.lang.String getPageEncoding();
Returns the value of the requested parameter.
public String getParameter( String name);
Parameter | Description |
---|---|
name |
The name of the parameter. |
Returns the content of Posted XML for this request as an XML Document.
public oracle.xml.xsql.Document getPostedDocument();
Returns the content of a Request parameters as an XML Document.
public oracle.xml.xsql.Document getRequestParamsAsXMLDocument();
Returns a string identifying the type of page request being made.
public String getRequestType();
Returns a String representation of the requested document's URI.
public String getSourceDocumentURI();
Gets a stylesheet parameter by name.
public String getStylesheetParameter( String name);
Parameter | Description |
---|---|
name |
The stylesheet parameter name. |
Gets an enumeration of stylesheet parameter names.
public java.util.Enumeration getStylesheetParameters();
Returns the URI of the stylesheet to be used to process the result.
public java.lang.String getStylesheetURI();
Returns a String identifier of the requesting program.
public java.lang.String getUserAgent();
Returns a PrintWriter used for writing out the results of a page request.
public java.io.PrintWriter getWriter();
Gets the XSQLConnection Object being used for this request Might be null.
public oracle.xml.xsql.XSQLConnection getXSQLConnection();
Returns true if this request is being included in another.
public boolean isIncludedRequest();
Returns true if the current connection uses the Oracle JDBC Driver.
public boolean isOracleDriver();
Returns the state of whether an Error Header has been printed.
public boolean printedErrorHeader();
Allows Page Request to Perform end-of-request processing.
public void requestProcessed();
Sets the connection name to use for this request.
public void setConnectionName( String connName);
Parameter | Description |
---|---|
connName |
The name of the connection. |
Sets the content type of the resulting page.
public void setContentType( String mimetype);
Parameter | Description |
---|---|
mimetype |
The |
Sets the Including Page Request object for this request.
public void setIncludingRequest( XMLPageRequest includingEnv);
Parameter | Description |
---|---|
includingEnv |
The XSQLPageRequest context of the including page. |
Sets encoding of source XSQL page associated with this request.
public void setPageEncoding( String enc);
Parameter | Description |
---|---|
enc |
The encoding of the current page. |
Sets encoding of source XSQL page associated with this request.
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. |
Allows programmatic setting of the Posted Document.
public void setPostedDocument( org.w3c.dom.Document doc);
Parameter | Description |
---|---|
doc |
The XML document that has been posted as part of this request. |
Sets whether an Error Header has been printed.
public void setPrintedErrorHeader( boolean yes);
Parameter | Description |
---|---|
yes |
Sets whether the error header has been printed. |
Sets the value of a parameter to be passed to the associated stylesheet.
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. |
Sets the URI of the stylesheet to be used to process the result.
public void setStylesheetURI( String uri);
Parameter | Description |
---|---|
uri |
The uri of the stylesheet to be used to transform this request. |
Returns a string representing an absolute URL resolved relative to the base URI for this request.
public String translateURL( String url);
Parameter | Description |
---|---|
url |
The url of the stylesheet to be used to translate this request. |
Returns true if connection pooling is desired for this request.
public boolean useConnectionPooling();
Returns true if HTML-formatted error messages are desired for this request.
public boolean useHTMLErrors();
Sets a request-scope object.
void setRequestObject( String name, Object obj);
Parameter | Description |
---|---|
name |
Name of the request-scope object to set. |
obj |
The request-scope object itself. |
Gets a request-scope object.
Object getRequestObject( String name);
Parameter | Description |
---|---|
name |
Name of the request-scope object to retrieve. |
Common XML Parsing Routines.
public final class XSQLParserHelper extends java.lang.Object java.lang.Object | +--oracle.xml.xsql.XSQLParserHelper
Method | Description |
---|---|
Class constructor. |
|
Returns a new, empty XML document. |
|
Parses an XML document from a variety of sources. |
|
Parses an XML document from a string. |
|
Prints an XML document. |
Class constructor.
public XSQLParserHelper();
Returns a new, empty XML document.
public static oracle.xml.xsql.Document newDocument();
Parses an XML document from a variety of sources. The options are described in the following table.
Parses an XML document from a string. The options are described in the following table.
Parameter | Description |
---|---|
xmlString |
String containing XML to parser. |
errorWriter |
PrintWriter to receive any error messages. |
Prints an XML document.
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. |
Programmatically process a request for an XSQL Page.
public class XSQLRequest extends java.lang.Object java.lang.Object | +--oracle.xml.xsql.XSQLRequest
Constructs an instance of XSQLRequest
from various sources.
public XSQLRequest( java.lang.String url);
Parameter | Description |
---|---|
url |
The URL for the XSQL Page source to process. |
Process the request, writing output/errors. The options are described in the following table.
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. |
Process the request, writing output/errors. The options are described in the following table.
Parameter | Description |
---|---|
params |
Dictionary with XSQL Page parameters |
err |
PrintWriter to use to write the resulting page errors |
Programmatically set an XML Document to be treated the same as if it were posted as part of the request.
public void setPostedDocument( org.w3c.dom.Document postedDoc)
Parameter | Description |
---|---|
postedDoc |
DOM Document |
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.
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.
void pageProcessingCompleted();
public final class XSQLServletPageRequest extends XSQLPageRequestImpl java.lang.Object | +--XSQLPageRequestImpl | +--oracle.xml.xsql.XSQLServletPageRequest
XSQLPageRequest Interface
Creates a Servlet-specific XSQL Page request.
public XSQLServletPageRequest( oracle.xml.xsql.HttpServletRequest req, oracle.xml.xsql.HttpServletResponse resp);
Parameter | Description |
---|---|
req |
Request. |
resp |
Response. |
Returns an instance of a nested Request.
public XSQLPageRequest createNestedRequest( java.net.URL pageurl, java.util.Dictionary params)
Parameter | Description |
---|---|
pageurl |
Page URL. |
prams |
Parameters of the request. |
Gets a vale of an HTTP Request cookie.
public java.lang.String getCookie( String name);
Parameter | Description |
---|---|
name |
Name of the cookie to get. |
Get the HttpServletRequest that initiated this XSQL Page Request.
public oracle.xml.xsql.HttpServletRequest getHttpServletRequest();
Get the HttpServletResponse that is associated with this XSQL Page Request.
public oracle.xml.xsql.HttpServletResponse getHttpServletResponse();
Use HTTP Parameters as the source of parameters instead.
public java.lang.String getParameter( String name);
Parameter | Description |
---|---|
name |
Name of the paramete4r whose value is to be retrieved. |
Retrieves a posted XML document for this request. Returns NULL
if there is none.
public oracle.xml.xsql.Document getPostedDocument();
Retrieves request parameters as an XML document.
public oracle.xml.xsql.Document getRequestParamsAsXMLDocument();
Returns the type of request ("Servlet", "Programmatic", "Command Line", or "Custorm").
public java.lang.String getRequestType();
Returns the user agent string passed in from the browser.
public java.lang.String getUserAgent();
Sets the content type of the resulting page.
public void setContentType( String mimetype);
Parameter | Description |
---|---|
mimtype |
The |
Sets the page encoding.
public void setPageEncoding( String enc);
Parameter | Description |
---|---|
enc |
The page encoding. |
Returns a string representing an absolute URL resolved relative to the base URI for this request.
public java.lang.String translateURL( String path);
Parameter | Description |
---|---|
path |
The relative URL which will be translated to an absolute URL. |
Sets whether HTML-formatted errors should be used.
public boolean useHTMLErrors();
XSLT Stylesheet Processing Engine
public final class XSQLStylesheetProcessor extends java.lang.Object java.lang.Object | +--oracle.xml.xsql.XSQLStylesheetProcessor
Processes CSLT stylesheet transformations.
public XSQLStylesheetProcessor();
Transforms an XML document by an XSLT stylesheet and returns the result as an XML document.
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. |
Transforms an CML Document by an XSLT stylesheet and writes the result to a PrintWriter.
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. |
Gets the Http Servlet Context.
javax.servlet.ServletContext getServletContext();
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()
.
public interface XSQLConnectionManager;
Method | Description |
---|---|
Gets a connection from the connection manager. |
|
Releases the connection. |
Gets a connection from the connection manager.
XSQLConnection getConnection( String connName, XSQLPageRequest env);
Parameter | Description |
---|---|
connName |
The connection name. |
env |
The XSQLPageRequest context. |
Releases the connection.
void releaseConnection( XSQLConnection theConn, XSQLPageRequest env);
Parameter | Description |
---|---|
theConn |
The XSQL Connection object to be released. |
env |
The XSQLPageRequest context. |
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.
public interface XSQLConnectionManagerFactory
Returns an instance of an XSQLConnectionManager. Implementation can decide whether it is a new XSQLConnectionManager or a shared singleton.
XSQLConnectionManager create();
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:
serialize()
methodNOTE: An implementation of XSQLDocumentSerializer is expected to do the following actions.
env.setContentType()
to set the content typeenv.getWriter()
to get the Writer to write toIf the serializer throws an unhandled exception, the XSQL Page Processor will format the stacktrace.
See oracle.xml.xsql.src.serializers.XSQLSampleSerializer for an example.
public interface XSQLDocumentSerializer
Serializes the resulting XML document for the output writer.
void serialize( org.w3c.dom.Document doc, XSQLPageRequest env);
Parameter | Description |
---|---|
doc |
The XML document to serialize. |
env |
The XSQLPageRequest context. |
|
Copyright © 2001, 2002 Oracle Corporation. All Rights Reserved. |
|