uk.co.weft.domutil
Class DocPage

java.lang.Object
  javax.servlet.GenericServlet
      javax.servlet.http.HttpServlet
          uk.co.weft.maybeupload.MaybeUploadServlet
              uk.co.weft.htform.Servlet
                  uk.co.weft.htform.WithExceptionHandlerServlet
                      uk.co.weft.domutil.DocPage

All Implemented Interfaces:

ResourceConsumer, java.io.Serializable, javax.servlet.Servlet, javax.servlet.ServletConfig

Direct Known Subclasses:

TransformPage

public class DocPage

extends WithExceptionHandlerServlet

a DocPage is a servlet which generates a page from a Document. This class (and consequently all servlets which are subclasses of this class) know about the following configuration parameters, in addition to those handled by Servlet:

dom_implementation_class

String: the name of the org.w3c.dom.DOMImplementation class to use. The class named must obviously be in the Web app's classpath. Optional. Defaults to org.apache.xerces.dom.DOMImplementationImpl.

generator_chain

String: a apace delimited list of fully qualified class name of my generator classes in the order in which they are to be tried. If a generator class returns null from generate( Context), the next in the chain will be tried and so on. Each must implement uk.co.weft.domutil.DocumentGenerator. Optional, but either generator_class or generator_chain must be supplied. Note that if both are supplied, the value of generator_class will be appended to the value of generator_chain. No default.

generator_class

String: The fully qualified class name of my generator class. Must implement uk.co.weft.domutil.DocumentGenerator. Optional, but either generator_class or generator_chain must be supplied. No default.

xsl_stylesheet

URL: The url of the XSL stylesheet to use to transform my documents for presentation to the user. Optional. No default.

entities_file

String: the file-path to a file on the local file system formatted as a Java properties file, where the keys are SGML entities to be converted in the output, and the values the string to substitute for them. Optional. No default.

entify_syntax_chars

Boolean: whether or not to output XML syntax chars as entities. In principle one should, but there may be circumstances where it's convenient not to. Optional. Defaults to true.

pretty_print

Boolean: whether to pretty-print (neatly indent) output markup. Optional. Defaults to true.

In addition, the DOMStub which is used by this class is aware of the following configuration parameters:

dom_coalescing

Boolean. Set parsers obtained from this stub to be coalescing. Optional. Default depends on chosen dom_implementation.

dom_expand_entity_references

Boolean. Set parsers obtained from this stub to expand entity references. Optional. Default depends on chosen dom_implementation.

dom_ignore_comments

Boolean. Set parsers obtained from this stub to ignore comments. Optional. Default depends on chosen dom_implementation.

dom_ignore_whitespace

Boolean. Set parsers obtained from this stub to ignore 'ignorable whitespace' if validating. Optional. Default depends on chosen dom_implementation.

dom_implementation_class

String: fully qualified name of a class accessible on the classpath which implements org.w3c.dom.DOMImplementation. Optional. Defaults to org.apache.xerces.dom.DOMImplementationImpl.

dom_namespace_aware

Boolean. Set parsers obtained from this stub to be namespace aware. Optional. Default depends on chosen dom_implementation.

dom_validating

Boolean. Set parsers obtained from this stub to be validating. Optional. Default depends on chosen dom_implementation.

Note: only one DOMStub is started up per web application, so there is no point in setting the dom_ in individual servlet init_params; you should only configure these in global config_params.

Version:

$Revision: 1.36.4.10 $ This revision: $Author: simon $

Author:

Simon Brooke

See Also:

DOMImplementation, DocumentBuilderFactory.setCoalescing(boolean), DocumentBuilderFactory.setExpandEntityReferences(boolean), DocumentBuilderFactory.setIgnoringComments(boolean), DocumentBuilderFactory.setIgnoringElementContentWhitespace(boolean)., DocumentBuilderFactory.setNamespaceAware(boolean), DocumentBuilderFactory.setValidating(boolean), Serialized Form

Field Summary

static java.lang.String	ACCEPTHEADER the name of the Accept header
static java.lang.String	ACCEPTSXMLMAGICTOKEN a magic token on which I shall cache, in the context, whether or not the client accepts XML
static java.lang.String	AXMLMIMETYPE the mime type application/xml; see RFC 3023
protected Printer	caxton the DOM printer I'm going to use
static java.lang.String	chosenGeneratorMagicToken Deprecated. use CHOSENGENERATORMAGICTOKEN
static java.lang.String	CHOSENGENERATORMAGICTOKEN a magic token to hold the chosen generator in the context
protected java.lang.String	entitiesFileName the name of my entities properties file, if any
protected java.util.Vector	generators my document generators
protected boolean	processClientSide whether I seek to offload XSL processing to client side
static java.lang.String	PROCESSCLIENTSIDECONFIGTOKEN a token on which I shall look in my config for whether I should offload XSL processing to those clients which claim to be able to ahndle it
protected TransformerFactory	transformerFactory A factory class for XSL transformers; this is Xalan 2
static java.lang.String	TXMLMIMETYPE the mime type text/xml; see RFC 3023
protected Document	xslDocument the XSL stylesheet as a document object
protected java.lang.String	xslStylesheetName the name of the XSL stylesheet I am to use, if any
static java.lang.String	XSLTRANSFORMCONFIGTOKEN a magic token on which I shall seek my XSL transform in the config-time context

Fields inherited from class uk.co.weft.htform.WithExceptionHandlerServlet

EXCEPTIONHANDLERCLASSCONFIGTOKEN

Fields inherited from class uk.co.weft.htform.Servlet

calendar, conf, contentType, CONTENTTYPECONFIGTOKEN, cookieDomain, cookiePath, COOKIESCONFIGTOKEN, cookieTTL, dbPassword, dbUrl, dbUsername, debug, DEBUGCONFIGTOKEN, driverName, embedded, here, identity, localeMagicToken, LOCALEMAGICTOKEN, outputStreamMagicToken, OUTPUTSTREAMMAGICTOKEN, parsePathInfo, PATHINFOMAGICTOKEN, ready, redirectMagicToken, REDIRECTMAGICTOKEN, requestMagicToken, REQUESTMAGICTOKEN, resourceBundleName, responseMagicToken, RESPONSEMAGICTOKEN, servletMagicToken, SERVLETMAGICTOKEN, sessionMagicToken, SESSIONMAGICTOKEN, USEHTTPSCONFIGTOKEN, zone

Fields inherited from class uk.co.weft.maybeupload.MaybeUploadServlet

allowOverwrite, maxUpload, saveUploadedFilesToDisk, silentlyRename, uploadDir, uploadDirPath, uploadDirURL

Fields inherited from interface uk.co.weft.htform.ResourceConsumer

RESOURCEBUNDLEMAGICTOKEN

Constructor Summary

DocPage()

Method Summary

protected boolean	clientAcceptsXML(Context context) Check whether we allow clientside processing and, if so, whether the client for this service claims to accept XML, and, by implication, to be capable of XSL processing client-side.
void	destroy() Specialisation: A call to destroy me should tall all my generators first
protected void	generateContent(Context context) Create a document with my document generator and send it to the output stream, passing it by way of my XSL stylesheet if I have one.
protected void	generateContent(Context context, java.io.OutputStream out) Create a document with my document generator and send it to this output stream, passing it by way of my XSL stylesheet if I have one.
protected Document	generateDocument(Context context) Deprecated. obsolete, no longer called; specialisation is pointless.
protected java.lang.String	getContentType(Context context) Return my content type in this context.
protected Document	getXSLDocument(Context context) select an appropriate XSL transform for this context, and return it as a Document.
void	init(Context config) Initialisation: Set up my variables from my configuration.
protected void	printDocument(Document doc, java.io.OutputStream out) Print this document onto this ouput stream
protected Document	tryGenerators(Context context) try each of my generators in turn until one of them accepts the context and generates a document; cache the generator which accepted it on the service context

Methods inherited from class uk.co.weft.htform.WithExceptionHandlerServlet

whinge, whinge, whinge

Methods inherited from class uk.co.weft.htform.Servlet

addCookie, addCookie, coerceCookiesToContext, coerceToContext, coerceToContext, coerceToContext, coerceToContext, coerceToUrl, createContext, doGet, doPost, fixupMagicValues, getCalendar, getDebug, getLocale, getOutputStream, getResource, getResourceString, getServletInfo, grs, grs, handleAction, handleCookies, handleRedirect, init, makeReady, outputRedirectBlock, setCookieValues, storeOnSession

Methods inherited from class uk.co.weft.maybeupload.MaybeUploadServlet

doDelete, doHead, doOptions, doPut, doTrace, getUploadDir, getUploadURL, service

Methods inherited from class javax.servlet.http.HttpServlet

doDelete, doGet, doHead, doOptions, doPost, doPut, doTrace, getLastModified, service

Methods inherited from class javax.servlet.GenericServlet

getInitParameter, getInitParameterNames, getServletConfig, getServletContext, getServletName, init, log, log

Methods inherited from class java.lang.Object

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

Field Detail

PROCESSCLIENTSIDECONFIGTOKEN

public static final java.lang.String PROCESSCLIENTSIDECONFIGTOKEN

a token on which I shall look in my config for whether I should offload XSL processing to those clients which claim to be able to ahndle it

See Also:

Constant Field Values

CHOSENGENERATORMAGICTOKEN

public static final java.lang.String CHOSENGENERATORMAGICTOKEN

a magic token to hold the chosen generator in the context

See Also:

Constant Field Values

chosenGeneratorMagicToken

public static final java.lang.String chosenGeneratorMagicToken

Deprecated. use CHOSENGENERATORMAGICTOKEN

a magic token to hold the chosen generator in the context

See Also:

Constant Field Values

XSLTRANSFORMCONFIGTOKEN

public static final java.lang.String XSLTRANSFORMCONFIGTOKEN

a magic token on which I shall seek my XSL transform in the config-time context

See Also:

Constant Field Values

TXMLMIMETYPE

public static final java.lang.String TXMLMIMETYPE

the mime type text/xml; see RFC 3023

See Also:

Constant Field Values

AXMLMIMETYPE

public static final java.lang.String AXMLMIMETYPE

the mime type application/xml; see RFC 3023

See Also:

Constant Field Values

ACCEPTHEADER

public static final java.lang.String ACCEPTHEADER

the name of the Accept header

See Also:

Constant Field Values

ACCEPTSXMLMAGICTOKEN

public static final java.lang.String ACCEPTSXMLMAGICTOKEN

a magic token on which I shall cache, in the context, whether or not the client accepts XML

See Also:

Constant Field Values

xslDocument

protected Document xslDocument

the XSL stylesheet as a document object

caxton

protected Printer caxton

the DOM printer I'm going to use

entitiesFileName

protected java.lang.String entitiesFileName

the name of my entities properties file, if any

xslStylesheetName

protected java.lang.String xslStylesheetName

the name of the XSL stylesheet I am to use, if any

transformerFactory

protected TransformerFactory transformerFactory

A factory class for XSL transformers; this is Xalan 2

generators

protected java.util.Vector generators

my document generators

processClientSide

protected boolean processClientSide

whether I seek to offload XSL processing to client side

Constructor Detail

DocPage

public DocPage()

Method Detail

destroy

public void destroy()

Specialisation: A call to destroy me should tall all my generators first

init

public void init(Context config)
          throws InitialisationException

Initialisation: Set up my variables from my configuration.

Overrides:

init in class WithExceptionHandlerServlet

Throws:

InitialisationException

getContentType

protected java.lang.String getContentType(Context context)

Return my content type in this context. If client can transform, I want to advertise my content as application/xml, no matter what my config says. Otherwise, if I don't have a stylesheet I generate pure XML, but if I do have a stylesheet there's a lot of things I could be generating, and we have to hope that the user (in the sense of the user as the person configuring the server) has set up my configuration to give me a contentType compatible with the stylesheet (s)he has given me.

Overrides:

getContentType in class Servlet

Parameters:

context - the context for this service

Returns:

the MIME type of my content

getXSLDocument

protected Document getXSLDocument(Context context)
                           throws GenerationException

select an appropriate XSL transform for this context, and return it as a Document. Default returns the value of the xslDocument variable; specialise if you want other behaviour

Throws:

GenerationException

clientAcceptsXML

protected boolean clientAcceptsXML(Context context)

Check whether we allow clientside processing and, if so, whether the client for this service claims to accept XML, and, by implication, to be capable of XSL processing client-side. Cache the result on the service context, because it will be asked for again.

Parameters:

context - the service context

Returns:

true if the client has indicated that it can accept XML (and thus, by implication, process XSL), false otherwise.

generateContent

protected void generateContent(Context context)
                        throws GenerationException,
                               java.io.IOException,
                               javax.servlet.ServletException

Create a document with my document generator and send it to the output stream, passing it by way of my XSL stylesheet if I have one.

Specified by:

generateContent in class Servlet

Parameters:

context - the context for this service

Throws:

java.io.IOException - if anything goes wrong while printing.

GenerationException - if anything goes wrong while generating

javax.servlet.ServletException - if cannot generate for other reasons

generateContent

protected void generateContent(Context context,
                               java.io.OutputStream out)
                        throws GenerationException

Create a document with my document generator and send it to this output stream, passing it by way of my XSL stylesheet if I have one. This method, new in Jacquard 1.10.21, uses TRAX to serialize the output rather than relying on my own Printer class, which is now probably obsolete

Parameters:

context - the service context

out - the stream to print the result on

Throws:

GenerationException - if anything goes wrong

Since:

Jacquard 1.10.21

generateDocument

protected Document generateDocument(Context context)
                             throws java.lang.Exception

Deprecated. obsolete, no longer called; specialisation is pointless.

Create a document in this context with my document generator and (if relevent) XSL filter, and return it

Throws:

java.lang.Exception

printDocument

protected void printDocument(Document doc,
                             java.io.OutputStream out)
                      throws java.io.IOException

Print this document onto this ouput stream

Parameters:

doc - the Document to print

out - the stream to print it on

Throws:

java.io.IOException - if anything goes wrong while printing.

tryGenerators

protected Document tryGenerators(Context context)
                          throws java.lang.Exception

try each of my generators in turn until one of them accepts the context and generates a document; cache the generator which accepted it on the service context

Throws:

java.lang.Exception