com.lotus.xsl.server
Class DefaultApplyXSL

com.lotus.xsl.server.ApplyXSL
  |
  +--com.lotus.xsl.server.DefaultApplyXSL

public class DefaultApplyXSL
extends ApplyXSL

DefaultApplyXSL extends the ApplyXSL abstract class. It's primary function is to provide a baseline servlet to let you apply XSL stylesheets to XML data at the server. Why do you want to apply XSL stylesheets to XML data at the server? Because you can maximize the sharability of your data without regard to the XML/XSL processing capabilities of your clients.

Attempts will be made to create an XML document DOM from the following sources:

  1. A relative URL specified in the HTTP request's path information. This capability is intended for use by servlet engines that map some or all XML data to be processed at the server.
  2. A URL specified in the HTTP request's URL= parameter. This capability is intended for clients wishing to selectively process XML data at the server. For security reasons, this URL will be forced to the local IP host.
  3. The HTTP request's XML input stream. This capability is intended for use by chained servlets.

Attempts will be made to create an XSL stylesheet DOM from the following sources:

  1. A URL specified in the HTTP request's xslURL= parameter. This capability is intended for clients wishing to selectively override the server algorithm for applying XSL stylesheets. For security reasons, this URL will be forced to the local IP host.
  2. The HTTP request's XSL input stream. This capability is intended for use by chained servlets.
  3. XML association. XML documents may contain references to one or more stylesheets using this W3C proposed recommendation. If the XML document does contain such references, a best match will be chosen based on the browser type making the request and the default association. This capability enables relationships to be defined between client capabilities and stylesheets capable of acting on these capabilities.
  4. A configured default stylesheet URL

This servlet requires the following software:


If you are running WebSphere Application Server v2.03 or later, this servlet is already installed. Otherwise, install this servlet by:

  1. Ensure that your servlet engine meets the system requirements.
  2. Install the xml4j.jar and lotusxsl.jar files in your servlet engine's class path. Unfortunately, the servlet specification does not yet define a standard way to install servlets. Please refer to your servlet engine's operational instructions; for IBM WebSphere Application Server, the instructions are here.
  3. Copy the lotusxsl/examples/servlet/mime.properties and media.properties files to a servlet-accessible location in your servlet engine's directory tree. These files provide configuration information to this servlet.
  4. Configure this servlet to your servlet engine. Once again, the servlet specification defines no standard servlet configuration procedure, so you must consult the operational instructions for your servlet engine.
    Default Apply XSL Servlet Base Configuration
    Parm Name Parm Value Required?
    Servlet Name DefaultApplyXSL Yes
    Description Apply XSL to XML No
    Servlet Class com.lotus.xsl.server.DefaultApplyXSL Yes
    Default Apply XSL Servlet Initialization Properties
    Description Parm Name Parm Value Required? Default Value
    Location of result-ns/MIME mapping rules file mimeURL a full URL or path relative to the System's server.root / servlets directory No None
    Location of user-Agent/media mapping rules file mediaURL a full URL or path relative to the System's server.root / servlets directory No None
    XSL stylesheet URL xslURL http://localhost/localpath/yourDefault.xsl No None
    Run in debug mode? debug true or false No true
    Strip whitespace from XML+XSL result stripWhiteSpace true or false No false
    Generate warning messages from XSL processor noConflictWarnings true or false No false
  5. If you wish to configure your servlet engine to automatically process some or all XML data at the server, you should follow your servlet engine's operational instructions on how to route these files to the default apply XSL servlet.
  6. Restart your servlet engine.
  7. Access an XML document using one of the techniques outlined in the examples

The following examples serve to illustrate the use of this servlet:

http://localhost/servlet/DefaultApplyXSL?URL=/data.xml&xslURL=/style.xsl
...will apply the style.xsl stylesheet to the data.xml data. Both files will be served from the Web server's HTTP document root.
http://localhost/servlet/DefaultApplyXSL?URL=/data.xml&xslURL=/style.xsl&debug=true
...will ensure that XML and XSL processor messages will be returned in the event of problems applying style.xsl to data.xml
http://localhost/servlet/DefaultApplyXSL/data.xml&xslURL=/style.xsl
...will apply the style.xsl stylesheet to the data.xml data, just like the first example. This is an alternative way of specifying the XML document by utilizing the HTTP request's path information.
http://localhost/servlet/DefaultApplyXSL/data.xml
...will examine data.xml for an associated XSL stylesheet. If multiple XSLs are associated with the data, the stylesheet whose media attribute maps to your browser type will be chosen. If no mapping is successful, the primary associated stylesheet will be used.
http://localhost/data.xml
...will provide the exact same function as the previous example, but this example assumes that /data.xml has been mapped to be executed by this servlet. The servlet engine may be configured to map all or some *.xml files to this servlet through the use of servlet aliases or filters.

The following usage notes may prove...well...useful:


Constructor Summary
DefaultApplyXSL()
           
 
Method Summary
 java.lang.String getMedia(com.lotus.xsl.server.HttpServletRequest request)
          Returns a media name mapped from the specified request's user-Agent header.
static java.lang.String getXSLURLfromDoc(com.lotus.xsl.server.Document xmlDoc, java.lang.String attributeName, java.lang.String attributeValue)
          Returns the XSL stylesheet URL associated with the specified XML document.
 void init(com.lotus.xsl.server.ServletConfig config)
          Initialize operational parameters from the configuration.
 com.lotus.xsl.server.Document makeDocument(com.lotus.xsl.server.HttpServletRequest request, java.io.InputStream ins, com.lotus.xsl.server.ErrorHandler listener)
          Returns a DOM from the specified input stream.
 
Methods inherited from class com.lotus.xsl.server.ApplyXSL
doGet, getContentType, process
 

Constructor Detail

DefaultApplyXSL

public DefaultApplyXSL()
Method Detail

init

public void init(com.lotus.xsl.server.ServletConfig config)
          throws com.lotus.xsl.server.ServletException
Initialize operational parameters from the configuration.
Parameters:
config - Configuration
Throws:
com.lotus.xsl.server.ServletException - Never thrown
Overrides:
init in class ApplyXSL

makeDocument

public com.lotus.xsl.server.Document makeDocument(com.lotus.xsl.server.HttpServletRequest request,
                                                  java.io.InputStream ins,
                                                  com.lotus.xsl.server.ErrorHandler listener)
                                           throws java.lang.Exception
Returns a DOM from the specified input stream.
Parameters:
request - Could contain the URL for catalog
ins - Input stream to parse
listener - To record detailed parsing messages for a possible return to requestor
Returns:
The DOM
Throws:
java.io.IOException - Thrown when input stream cannot be opened for parsing
org.xml.sax.SAXException - Thrown by parser if stream not document compliant
XSLProcessorException - Thrown when stream cannot be parsed

getMedia

public java.lang.String getMedia(com.lotus.xsl.server.HttpServletRequest request)
Returns a media name mapped from the specified request's user-Agent header. This mapping enables relationships to be defined between client capabilities and stylesheets capable of acting on these capabilities.

Refer to the mime.properties file for details.

Parameters:
request - Contains the user-Agent header
Returns:
The media name that corresponds to the user-Agent, or "unknown"
See Also:
#getStylesheet

getXSLURLfromDoc

public static java.lang.String getXSLURLfromDoc(com.lotus.xsl.server.Document xmlDoc,
                                                java.lang.String attributeName,
                                                java.lang.String attributeValue)
Returns the XSL stylesheet URL associated with the specified XML document. If multiple XSL stylesheets are associated with the XML document, preference will be given to the stylesheet which contains an attribute name/value pair that corresponds to the specified attributeName and attributeValue.
Parameters:
xmlDoc - XML Document to be searched for associated XSL stylesheets
attributeName - Attribute name to provide preferential matching
atrributeValue - Attribute value to provide preferential matching
Returns:
The preferred XSL stylesheet URL, or null if no XSL stylesheet association is found
See Also:
#getStylesheet