atg.droplet.xml

Class XMLTransform

java.lang.Object

atg.nucleus.logging.VariableArgumentApplicationLoggingImpl

atg.nucleus.GenericService

atg.nucleus.TimedOperationService

atg.nucleus.servlet.ServletService

atg.nucleus.servlet.HttpServletService

atg.servlet.DynamoServlet

atg.droplet.xml.XMLTransform

All Implemented Interfaces:

atg.core.logging.Logging, atg.core.logging.TraceLogging, atg.naming.AbsoluteNameable, NameContextBindingListener, NameContextElement, atg.naming.NameContextParentable, NameResolver, AdminableService, atg.nucleus.Configured, ApplicationLogging, atg.nucleus.logging.ApplicationLoggingSender, atg.nucleus.logging.TraceApplicationLogging, VariableArgumentApplicationLogging, ComponentNameResolver, Service, ServiceListener, ParameterServlet, java.util.EventListener, javax.servlet.Servlet

public class XMLTransform
extends DynamoServlet

Transform XML documents using a template.
The template can be a JHTML page or an XSLT stylesheet.

The input parameter specifies the XML document to be transformed.
The template for the transformation is located according to the following order of precedence:

• A DOM document bound to the template parameter.
• The document referenced by the URI string bound to the template parameter.
• Then when the template parameter is unset:
  • A match derived from the XMLTemplateMap component:
    • A specific match on the input document URI.
    • A specific match on the type suffix of the input document URI.
    • A default template defined in the XMLTemplateMap component.
  • The template defined by the XML document itself, using an embedded
    <?xml-stylesheet?> processing instruction.

In the case of a JHTML template, the XMLTransform droplet will pass a DOM document as a local parameter to the execution of the JHTML page. The name of this parameter can be controlled by the optional documentParameterName parameter. The default is inputDocument.

The DOM object that is the result of the transformation will be bound to the documentOutputName output parameter, for further processing or rendering in the output oparam.

If the output parameter is not specified, the transformed document will be serialized directly into the page. If the transform is XSL, the result will conform to the <xsl:output> top-level element.

These are the parameters for the XMLTransform droplet:

Input Paramaters

input (required)

The XML document to be transformed. This can be a DOM Document object, a SAX InputSource, a text InputStream, or a URL for an XML document. This parameter is required. If it is not supplied, the unset open parameter will be rendered.

template (optional)

The template to be used to transform the XML document. This can be either a URL for a template, or a DOM document object. This parameter is optional. If it is not supplied, a match will be sought in the XMLTemplateMap, and finally from an <?xml-stylesheet?> directive embedded in the XML document itself. If no template is found, it is an error. If logging is enabled, the reason will be logged, then the failure open parameter will be rendered.

templateContext (optional)

If the template is a JSP template, AND is in a separate web-application, specify templateContext to the context root of the target web-application. Note this option does not apply to JHTML pages.

validate (optional)

Determine how the XML document specified by the input parameter should be validated against a DTD specified in its DOCTYPE declaration. Validation will be slower, but may help prevent problems later when accessing parts of the XML document. The legal values are:

• true
  Read the DTD, validate the document, and apply all information from the DTD.



• false (default)
  Read the DTD, do not validate the document, but substitute default attributes, and apply other information from the DTD at the parser's discretion (Apache Xerces does support this mode).



• nodtd
  Do not read the DTD, do not validate the document, do not apply any defaults or other information. Use this mode when you do not want the parser to try and resolve the DTD location, perhaps because the remote URL location is temporarily unreachable. Note that the resulting document may be incomplete, have incorrect attibute values, and will not have subsitution of external entities. (Apache Xerces does support this mode, but it may not be available for every parser).

This parameter is optional, the default value is false. If there is no DOCTYPE declaration, this parameter has no effect.

passParams (optional)

If the template is an XSL stylesheet: a flag to control the passing of parameters from the request and droplet environment, to top-level <xsl:param> elements in the XSL stylesheet. Legal values are:

• none: no params are passed (default).
• query: URL query params from a GET request.
• post: form params from a POST request.
• local: only params in this droplet scope.
• all: params from all droplet and request scopes.

If more than one parameter exists for a given name, only the first is passed. The order of parameter scopes is from local (within the XMLTransform droplet), up through other enclosing scopes, and eventually to the request query or post parameters. See DynamoHttpServletRequest for more details on the query, post, and local parameter scope definitions.

documentParameterName (optional)

If the template is JHTML: the name of the parameter to bind the input DOM document object. The default name is inputDocument.

Outut Paramaters

documentOutputName (optional)

This parameter will be bound to the DOM document which results from the transformation. This object can be further processed or rendered in the output oparam. The default name is document.

errors (optional)

This parameter will be bound to an Enumeration of Exceptions if there were failures when transforming the XML document.

Open Paramaters

unset (optional)

The oparam to render if the input parameter is not set.

output (optional)

This oparam is used when the XML document was successfully transformed. The result of the transformation is available as a DOM document in the parameter specified by the documentOutputName. If the output oparam is not specified, then the document is automatically serialized to the output page.

failure (optional)

This oparam will be used to format output when there was a failure to transform the XML document. If error logging is enabled, then the reason for the failure will be logged. Exceptions are also bound to the errors output parameter.

For more details about XSLT, see XSL Transformations (W3C Recommendation 1999-11-19). In particular, see this section on Top-level Variables and Parameters, which mentions passing parameters to stylesheets using <xsl:param> elements. For more details about embedded references to XSL stylesheets, see Associating Stylesheets with XML Documents (W3C Recommendation 1999-06-26).

When embedded XSL directives are used, the stylesheets from multiple processing instructions are concatenated together, as if they were imported into a common stylesheet. There is no iteration over multiple stylesheets in the source document, and no recursion over directives in the output of the first transform. The type pseudo-attribute must be present, with one of these values: text/xml (official XSLT 1.0 MIME type), text/xsl (incorrect, but frequently used by analogy with text/css), or application/xslt+xml (newly suggested for XSLT by RFC 3023 XML Media Types, but due to a typo in Xalan, you may need to use application/xml+xslt instead).

If the output open parameter is not specified for an XSL transform, the serialized output will generally conform to the attributes of the <xsl:output> top-level element.

The MIME type is written to the HTTP response Content-type header. The MIME type is determined by an explicit media-type attribute on the <xsl:output> element. If this is not present, then the MIME type is taken from the Dynamo servlet pipeline, typically derived with the MIMETyper from the filetype suffix of the page. The default media-type usually depends on the output method attribute: text/xml for method xml, and text/html for the html, but in Dynamo this will always get overwritten with the value from the pipeline.

The default method for Dynamo is html, not the standard XSL default value of xml. If XML output is required, it must be explicitly requested in the <xsl:output> element. Since the MIME type can be derived from the Dynamo servlet pipeline, it is possible to get an inconsistent method in XSL (e.g. a WML type from the servlet pipeline, but a default html output method). Care should be taken to ensure that the MIME type and the output method are consistent.

An encoding is used to serialize the result to the response stream, and the encoding name is set in the Content-type HTTP header using the charset flag. The encoding is determined by an explicit encoding attribute on the <xsl:output> element. If this is not present, then the encoding is taken from the Dynamo servlet pipeline, typically derived with the EncodingTyper from the path of the compiled page. Note that the encoding does not default to the standard XSL value of UTF-8, and it is completely independent of the actual encoding of the XSL stylesheet itself, as specified in the <?xml?> declaration. If an output encoding of UTF-8 is required, it must be explicitly requested in the <xsl:output> element.

See Also:

XMLTemplateMap

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	CLASS_VERSION
protected static java.lang.String	DEFAULT_IN_DOC_NAME The default input document parameter name for JHTML
protected static java.lang.String	DEFAULT_OUT_DOC_NAME The default output document parameter name
protected static int	DEFAULT_PASS
protected static int	ENUM_PASS_ALL
protected static int	ENUM_PASS_LOCAL
protected static int	ENUM_PASS_NONE
protected static int	ENUM_PASS_POST
protected static int	ENUM_PASS_QUERY
protected static java.lang.String	ERRORS_PARAM The name of the errors paramameter
protected static java.lang.String	FAILURE_PARAM The name of the failure paramameter
protected static java.lang.String	IN_DOC_NAME_PARAM The name of the parameter used to configure the document
protected static java.lang.String	INPUT_PARAM The name of the input paramameter
protected static java.lang.String	OUT_DOC_NAME_PARAM The name of the default document parameter
protected static java.lang.String	OUTPUT_PARAM The name of the output paramameter
protected static java.lang.String	PASS_ALL
protected static java.lang.String	PASS_LOCAL
protected static java.lang.String	PASS_NONE
protected static java.lang.String	PASS_PARAM The name of the args paramameter
protected static java.lang.String	PASS_POST
protected static java.lang.String	PASS_QUERY
protected static java.lang.String	TEMPLATE_CONTEXT_PARAM The context path of the target template page (only applies to JSP).
protected static java.lang.String	TEMPLATE_PARAM The name of the template paramameter
protected static java.lang.String	UNSET_PARAM The name of the unset paramameter
protected static java.lang.String	VALIDATE_PARAM The name of the validate paramameter

Fields inherited from class atg.servlet.DynamoServlet

mAllowCleanupRequest, mParameters

Fields inherited from class atg.nucleus.servlet.ServletService

SERVLET_INFO_KEY

Fields inherited from class atg.nucleus.GenericService

SERVICE_INFO_KEY

Fields inherited from interface atg.nucleus.logging.TraceApplicationLogging

DEFAULT_LOG_TRACE_STATUS

Fields inherited from interface atg.nucleus.logging.ApplicationLogging

DEFAULT_LOG_DEBUG_STATUS, DEFAULT_LOG_ERROR_STATUS, DEFAULT_LOG_INFO_STATUS, DEFAULT_LOG_WARNING_STATUS

Constructor Summary

Constructors

Constructor and Description
XMLTransform()

Method Summary

Modifier and Type	Method and Description
DocumentCache	getDocumentCache() The DocumentCache used by this component.
DocumentCache	getStylesheetCache() The StylesheetCache used by this component.
atg.xml.service.XMLTemplateMap	getXmlTemplateMap() The XMLTemplateMap used by this component.
atg.xml.tools.XMLToolsFactory	getXmlToolsFactory() The XMLToolsFactory used by this component.
protected void	processJHTMLTemplate(DynamoHttpServletRequest pReq, DynamoHttpServletResponse pRes, org.w3c.dom.Document pInput, java.lang.String pTemplateURI, java.lang.String pInputDocParamName) Process a JHTML template.
protected org.w3c.dom.Document	processXSLTemplate(DynamoHttpServletRequest pReq, DynamoHttpServletResponse pRes, org.w3c.dom.Document pInput, boolean output, java.util.Map pParams, javax.xml.transform.ErrorListener pErr) Process with any embedded XSL template.
protected org.w3c.dom.Document	processXSLTemplate(DynamoHttpServletRequest pReq, DynamoHttpServletResponse pRes, org.w3c.dom.Document pInput, org.w3c.dom.Document pStylesheet, boolean output, java.util.Map pParams, javax.xml.transform.ErrorListener pErr) Process an XSL template from a DOM document.
protected org.w3c.dom.Document	processXSLTemplate(DynamoHttpServletRequest pReq, DynamoHttpServletResponse pRes, org.w3c.dom.Document pInput, java.lang.Object pXform, boolean output, java.util.Map pParams, javax.xml.transform.ErrorListener pErr) Process an XSL template with a pre-compiled template.
void	service(DynamoHttpServletRequest pReq, DynamoHttpServletResponse pRes) The service method for this droplet.
void	setDocumentCache(DocumentCache pDocumentCache) The DocumentCache used by this component
void	setStylesheetCache(DocumentCache pStylesheetCache) The StylesheetCache used by this component
void	setXmlTemplateMap(atg.xml.service.XMLTemplateMap pXMLTemplateMap) The XMLTemplateMap used by this component
void	setXmlToolsFactory(atg.xml.tools.XMLToolsFactory pXMLToolsFactory) The XMLToolsFactory used by this component.

Methods inherited from class atg.servlet.DynamoServlet

doDelete, doGet, doPost, doPut, getParameter, getParameters, getServletContext, init, service, service, setParameter

Methods inherited from class atg.nucleus.servlet.ServletService

destroy, getServletConfig, getServletInfo, setServletInfo

Methods inherited from class atg.nucleus.TimedOperationService

getAverageRequestHandlingTime, getHandledRequestCount, getRequestStartTime, getTotalRequestHandlingTime, isKeepingStatistics, notifyHandledRequest, resetStatistics, setKeepingStatistics

Methods inherited from class atg.nucleus.GenericService

addLogListener, createAdminServlet, doStartService, doStopService, getAbsoluteName, getAdminServlet, getAdminServletOutputStreamEncoding, getLoggingForVlogging, getLogListenerCount, getLogListeners, getName, getNameContext, getNucleus, getRoot, getServiceConfiguration, getServiceInfo, isAdminServletUseServletOutputStream, isLoggingDebug, isLoggingError, isLoggingInfo, isLoggingTrace, isLoggingWarning, isRunning, logDebug, logDebug, logDebug, logError, logError, logError, logInfo, logInfo, logInfo, logTrace, logTrace, logTrace, logWarning, logWarning, logWarning, nameContextElementBound, nameContextElementUnbound, removeLogListener, reResolveThis, resolveName, resolveName, resolveName, resolveName, sendLogEvent, setAdminServletOutputStreamEncoding, setAdminServletUseServletOutputStream, setLoggingDebug, setLoggingError, setLoggingInfo, setLoggingTrace, setLoggingWarning, setNucleus, setServiceInfo, startService, stopService, toString

Methods inherited from class atg.nucleus.logging.VariableArgumentApplicationLoggingImpl

vlogDebug, vlogDebug, vlogDebug, vlogDebug, vlogDebugTrace, vlogError, vlogError, vlogError, vlogError, vlogInfo, vlogInfo, vlogInfo, vlogInfo, vlogTrace, vlogTrace, vlogTrace, vlogTrace, vlogWarning, vlogWarning, vlogWarning, vlogWarning

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

CLASS_VERSION

public static java.lang.String CLASS_VERSION

INPUT_PARAM

protected static final java.lang.String INPUT_PARAM

The name of the input paramameter

See Also:

Constant Field Values

OUT_DOC_NAME_PARAM

protected static final java.lang.String OUT_DOC_NAME_PARAM

The name of the default document parameter

See Also:

Constant Field Values

IN_DOC_NAME_PARAM

protected static final java.lang.String IN_DOC_NAME_PARAM

The name of the parameter used to configure the document

See Also:

Constant Field Values

OUTPUT_PARAM

protected static final java.lang.String OUTPUT_PARAM

The name of the output paramameter

See Also:

Constant Field Values

UNSET_PARAM

protected static final java.lang.String UNSET_PARAM

The name of the unset paramameter

See Also:

Constant Field Values

VALIDATE_PARAM

protected static final java.lang.String VALIDATE_PARAM

The name of the validate paramameter

See Also:

Constant Field Values

PASS_PARAM

protected static final java.lang.String PASS_PARAM

The name of the args paramameter

See Also:

Constant Field Values

TEMPLATE_PARAM

protected static final java.lang.String TEMPLATE_PARAM

The name of the template paramameter

See Also:

Constant Field Values

TEMPLATE_CONTEXT_PARAM

protected static final java.lang.String TEMPLATE_CONTEXT_PARAM

The context path of the target template page (only applies to JSP).

See Also:

Constant Field Values

ERRORS_PARAM

protected static final java.lang.String ERRORS_PARAM

The name of the errors paramameter

See Also:

Constant Field Values

FAILURE_PARAM

protected static final java.lang.String FAILURE_PARAM

The name of the failure paramameter

See Also:

Constant Field Values

DEFAULT_IN_DOC_NAME

protected static final java.lang.String DEFAULT_IN_DOC_NAME

The default input document parameter name for JHTML

See Also:

Constant Field Values

DEFAULT_OUT_DOC_NAME

protected static final java.lang.String DEFAULT_OUT_DOC_NAME

The default output document parameter name

See Also:

Constant Field Values

PASS_NONE

protected static final java.lang.String PASS_NONE

See Also:

Constant Field Values

PASS_LOCAL

protected static final java.lang.String PASS_LOCAL

See Also:

Constant Field Values

PASS_QUERY

protected static final java.lang.String PASS_QUERY

See Also:

Constant Field Values

PASS_POST

protected static final java.lang.String PASS_POST

See Also:

Constant Field Values

PASS_ALL

protected static final java.lang.String PASS_ALL

See Also:

Constant Field Values

ENUM_PASS_NONE

protected static final int ENUM_PASS_NONE

See Also:

Constant Field Values

ENUM_PASS_LOCAL

protected static final int ENUM_PASS_LOCAL

See Also:

Constant Field Values

ENUM_PASS_QUERY

protected static final int ENUM_PASS_QUERY

See Also:

Constant Field Values

ENUM_PASS_POST

protected static final int ENUM_PASS_POST

See Also:

Constant Field Values

ENUM_PASS_ALL

protected static final int ENUM_PASS_ALL

See Also:

Constant Field Values

DEFAULT_PASS

protected static final int DEFAULT_PASS

See Also:

Constant Field Values

Constructor Detail

XMLTransform

public XMLTransform()

Method Detail

setDocumentCache

public void setDocumentCache(DocumentCache pDocumentCache)

The DocumentCache used by this component

getDocumentCache

public DocumentCache getDocumentCache()

The DocumentCache used by this component.

setStylesheetCache

public void setStylesheetCache(DocumentCache pStylesheetCache)

The StylesheetCache used by this component

getStylesheetCache

public DocumentCache getStylesheetCache()

The StylesheetCache used by this component.

setXmlToolsFactory

public void setXmlToolsFactory(atg.xml.tools.XMLToolsFactory pXMLToolsFactory)

The XMLToolsFactory used by this component.

getXmlToolsFactory

public atg.xml.tools.XMLToolsFactory getXmlToolsFactory()

The XMLToolsFactory used by this component.

setXmlTemplateMap

public void setXmlTemplateMap(atg.xml.service.XMLTemplateMap pXMLTemplateMap)

The XMLTemplateMap used by this component

getXmlTemplateMap

public atg.xml.service.XMLTemplateMap getXmlTemplateMap()

The XMLTemplateMap used by this component.

service

public void service(DynamoHttpServletRequest pReq,
                    DynamoHttpServletResponse pRes)
             throws javax.servlet.ServletException,
                    java.io.IOException

The service method for this droplet.

Overrides:

service in class DynamoServlet

Parameters:

pReq - the request to be processed

pRes - the response object for this request

Throws:

javax.servlet.ServletException - an application specific error occurred processing this request

java.io.IOException - an error occurred reading data from the request or writing data to the response.

processXSLTemplate

protected org.w3c.dom.Document processXSLTemplate(DynamoHttpServletRequest pReq,
                                                  DynamoHttpServletResponse pRes,
                                                  org.w3c.dom.Document pInput,
                                                  org.w3c.dom.Document pStylesheet,
                                                  boolean output,
                                                  java.util.Map pParams,
                                                  javax.xml.transform.ErrorListener pErr)
                                           throws java.lang.Exception

Process an XSL template from a DOM document.

Throws:

java.lang.Exception

processXSLTemplate

protected org.w3c.dom.Document processXSLTemplate(DynamoHttpServletRequest pReq,
                                                  DynamoHttpServletResponse pRes,
                                                  org.w3c.dom.Document pInput,
                                                  java.lang.Object pXform,
                                                  boolean output,
                                                  java.util.Map pParams,
                                                  javax.xml.transform.ErrorListener pErr)
                                           throws java.lang.Exception

Process an XSL template with a pre-compiled template.

Throws:

java.lang.Exception

processXSLTemplate

protected org.w3c.dom.Document processXSLTemplate(DynamoHttpServletRequest pReq,
                                                  DynamoHttpServletResponse pRes,
                                                  org.w3c.dom.Document pInput,
                                                  boolean output,
                                                  java.util.Map pParams,
                                                  javax.xml.transform.ErrorListener pErr)
                                           throws java.lang.Exception

Process with any embedded XSL template.

Throws:

java.lang.Exception

processJHTMLTemplate

protected void processJHTMLTemplate(DynamoHttpServletRequest pReq,
                                    DynamoHttpServletResponse pRes,
                                    org.w3c.dom.Document pInput,
                                    java.lang.String pTemplateURI,
                                    java.lang.String pInputDocParamName)
                             throws java.lang.Exception

Process a JHTML template.

Throws:

java.lang.Exception