bea.com | products | dev2dev | support | askBEA

Download Docs | Site Map | Glossary
Search

Programming WebLogic XML

Developing XML Applications with WebLogic Server

The following sections describe how to use the Java programming language and WebLogic Server to develop XML applications. It is assumed that you know how to use Java Servlets and Java Server Pages (JSPs) to write Java applications. For information about how to write servlet and JSP applications, see Programming WebLogic HTTP Servlets and Programming WebLogic JSP.

- Developing XML Applications: Main Steps

- Parsing XML Documents

- Generating New XML Documents

- Transforming XML Documents

Developing XML Applications: Main Steps

Programmers using the WebLogic Server XML subsystem typically perform some or all of the following programming tasks when developing XML applications:

1. Parse an XML document.

   The XML document can originate from a number of sources. For example, a programmer might develop a servlet to receive an XML document from a client, write an EJB to receive an XML document from a Servlet or another EJB, and so on. In each instance, the XML document may have to be parsed so that its data can be manipulated.

   For more information on this task, refer to Parsing XML Documents.

2. Generate a new XML document.

   After a servlet or EJB has received and parsed an XML document and possibly manipulated the data in some way, the Servlet or EJB might need to generate a new XML document to send back to the client or to pass on to another EJB.

   For more information on this task, refer to Generating New XML Documents.

3. Transform XML data into another format.

   After parsing an XML document or generating a new one, the Servlet or EJB may need to transform it into another format, such as HTML, WML, or plain text.

   For more information on this task, refer to Using JAXP to Transform XML Data.

Parsing XML Documents

This section describes how to parse XML documents using JAXP in both DOM and SAX mode and how to parse XML documents from a servlet.

Note: For detailed instructions on using the WebLogic XML Streaming API to parse XML documents, see Using the WebLogic XML Streaming API.

As mentioned previously, you use the Administration Console XML Registry to configure the following:

- Per-doctype parsers, which supersede the built-in parser for the specified doctype

- External entity resolution, or the process that an XML parser goes through when requested to find an external file in the course of parsing an XML document

For detailed information on how to use the Administration Console for these tasks, refer to Administering WebLogic Server XML.

For a complete example of parsing an XML document in SAX mode, see the WL_HOME\samples\server\src\examples\xml\sax directory, where WL_HOME refers to the top-level WebLogic Platform directory.

Parsing XML Documents Using JAXP in SAX Mode

The following code example shows how to configure a SAX parser factory to create a validating parser. The example also shows how to register the MyHandler class with the parser. The MyHandler class can override any method of the DefaultHandler class to provide custom behavior for SAX parsing events or errors.

>     import javax.xml.parsers.SAXParser;
>     import javax.xml.parsers.SAXParserFactory;

>     ...
>     MyHandler handler = new MyHandler();
>     // MyHandler extends org.xml.sax.helpers.DefaultHandler.

>       //Obtain an instance of SAXParserFactory.
>       SAXParserFactory spf = SAXParserFactory.newInstance();
>       //Specify a validating parser.
>       spf.setValidating(true); // Requires loading the DTD.
>       //Obtain an instance of a SAX parser from the factory.
>       SAXParser sp = spf.newSAXParser();
>       //Parse the documnt.
>       sp.parse("http://server/file.xml", handler);
>     ...

Note: If you want to use a parser other than the built-in parser, you must use the WebLogic Server Administration Console to specify the parser in the XML Registry; otherwise the SaxParserFactory.newInstance method returns the built-in parser. For instructions about configuring WebLogic Server to use a parser other than the built-in parser, see Configuring a Parser or Transformer Other Than the Built-In.

For a complete example of parsing an XML document in SAX mode, see the WL_HOME\samples\server\src\examples\xml\sax directory, where WL_HOME refers to the top-level WebLogic Platform directory.

Parsing XML Documents Using JAXP in DOM Mode

The following code example shows how to parse an XML document and create an org.w3c.dom.Document tree from a DocumentBuilder object:

>     import javax.xml.parsers.DocumentBuilder;
>     import javax.xml.parsers.DocumentBuilderFactory;

>     import org.w3c.dom.Document;

>     ...
>     //Obtain an instance of DocumentBuilderFactory.
>     DocumentBuilderFactory dbf =
>                      DocumentBuilderFactory.newInstance();
>     //Specify a validating parser.
>     dbf.setValidating(true); // Requires loading the DTD.
>     //Obtain an instance of a DocumentBuilder from the factory.
>     DocumentBuilder db = dbf.newDocumentBuilder();
>     //Parse the document.
>     Document doc = db.parse(inputFile);
>     ...

Note: If you want to use a parser other than the built-in parser, you must use the WebLogic Server Administration Console to specify it; otherwise the DocumentBuilderFactory.newInstance method returns the built-in parser. For instructions about configuring WebLogic Server to use a parser other than the built-in parser, see Configuring a Parser or Transformer Other Than the Built-In.

For a complete example of parsing an XML document in DOM mode, see the WL_HOME\samples\server\src\examples\xml\dom directory, where WL_HOME refers to the top-level WebLogic Platform directory.

Parsing XML Documents in a Servlet

Support for the setAttribute and getAttribute methods was added to version 2.2 of the Java Servlet Specification. Attributes are objects associated with a request. The request object encapsulates all information from the client request. In the HTTP protocol, this information is transmitted from the client to the server by the HTTP headers and message body of the request.

With WebLogic Server, you can use the setAttribute and getAttribute methods to parse XML documents. Use the setAttribute method for SAX mode parsing and the getAttribute method for DOM mode parsing.

Using the org.xml.sax.DefaultHandler Attribute to Parse a Document

The following code example shows how to use the setAttribute method:

>     import weblogic.servlet.XMLProcessingException;
>     import org.xml.sax.helpers.DefaultHandler;
>     ...
>     public void doPost(HttpServletRequest request,
>                                  HttpServletResponse response)
>        throws ServletException, IOException  {
>        try {
>           request.setAttribute("org.xml.sax.helpers.DefaultHandler",
>                                new DefaultHandler());
>         } catch(XMLProcessingException xpe) {
>           System.out.println("Error in processing XML");
>           xpe.printStackTrace();
>           return;
>         }
>     ...

You can also use the org.xml.sax.HandlerBase attribute to parse an XML document, although it is deprecated:

>     request.setAttribute("org.xml.sax.HandlerBase",
>                           new HandlerBase());

Note: This code example shows a simple way to parse a document using SAX and the setAttribute method. This method of parsing a document is a WebLogic Server convenience feature, and it is not supported by other servlet vendors. Therefore, if you plan to run your application on other servlet platforms, do not use this feature.

Using the org.w3c.dom.Document Attribute to Parse a Document

The following code example shows how to use the getAttribute method.

>     import org.w3c.dom.Document;
>     import weblogic.servlet.XMLProcessingException;

>     ...

>     public void doPost(HttpServletRequest request,
>                                 HttpServletResponse response)
>     throws ServletException, IOException  {

>     try {
>        Document doc = request.getAttribute("org.w3c.dom.Document");
>      } catch(XMLProcessingException xpe) {
>        System.out.println("Error in processing XML");
>        xpe.printStackTrace();
>        return;
>      }
>     ...

Note: This code example shows a simple way to parse a document using DOM and the getAttribute method. This method of parsing a document is a WebLogic Server convenience feature, and it is not supported by other servlet vendors. Therefore, if you plan to run your application on other servlet platforms, do not use this feature.

Validating and Non-Validating Parsers

As previously discussed, a well-formed document is one that is syntactically correct according to the rules outlined in the W3C Recommendation for XML 1.0. A valid document is one that follows the constraints specified by its DTD or schema.

A non-validating parser verifies that a document is well-formed, but does not verify that it is valid. The WebLogic FastParser, described in Using the WebLogic FastParser, is non-validating.

To turn on validation while parsing a document (assuming you are using a validating parser), you must:

- Set the SAXParserFactory.setValidating() method to true, as shown in the following example:

  >     SAXParserFactory factory = SAXParserFactory.newInstance();
  >     factory.setValidating(true);

- Ensure that the XML document you are parsing includes (either in-line or by reference) a DTD or a schema.

Handling Entity Resolution While Parsing an XML Document

This section provides general information about external entities; how they are identified and resolved by an XML parser; and the features provided by WebLogic Server to improve the performance of external entity resolution in your XML applications.

For a complete example of resolving an external entity while parsing an XML document, see the WL_HOME\samples\server\src\examples\xml\entityresolution directory, where WL_HOME refers to the top-level WebLogic Platform directory.

General Information About External Entities

External entities are chunks of text that are not literally part of an XML document, but are referenced inside the XML document. The actual text might reside anywhere - in another file on the same computer or even somewhere on the Web. While parsing a document, if the parser encounters an external entity reference, it fetches the referenced chunk of text, places the text into the XML document, then continues parsing. An example of an external entity is a DTD; rather than including the full text of the DTD in the XML document, the XML document has a reference to the DTD that is stored in a separate file.

There are two ways to identify an external entity: a system identifier and a public identifier. System identifiers use URIs to reference an external entity based on its location. Public identifiers use a publicly declared name to refer the information.

The following example shows how a public identifier is used to reference the DTD for the application.xml file that describes a J2EE application archive (*.ear file):

>     <!DOCTYPE application PUBLIC "-//Sun Microsystems,
>     Inc.//DTD J2EE Application 1.2//EN">

The following example shows a reference to an external DTD by a system identifier only:

>     <!DOCTYPE application SYSTEM "http://java.sun.com/j2ee/dtds/application_1_2.dtd">

Here is a reference that uses both the public and system identifier; note that the keyword SYSTEM is omitted:

>     <!DOCTYPE application
>     PUBLIC "-//Sun Microsystems, Inc.//DTD J2EE Application 1.2//EN"
>     "http://java.sun.com/j2ee/dtds/application_1_2.dtd">

Using the WebLogic Server Entity Resolution Features

Use the following WebLogic Server features to improve the performance of external entity resolution in your XML applications:

- Permanently store a copy of an external entity on the computer that hosts the WebLogic Administration Server.

- Specify that WebLogic Server automatically retrieve and cache an external entity that resides in an external repository that supports an HTTP interface, such as a URL. You can specify that WebLogic Server cache the entity either in memory or on disk and specify when the cached entry becomes stale, at which point WebLogic Server automatically updates the cached entry.

  Using the retrieve-and-cache feature, you do not have to actually copy the external entity to the local computer. The XML application refers to the actual external entity only at specified time intervals, rather than each time the document is parsed, thus potentially greatly improving the performance of your application while also keeping as up to date with the latest external entity as desired.

You use the XML Registry to create entity resolution entries to identify where the external entry is located (locally or at a URL) and what the caching options are for entities on the Web. You identify the external entity entry using a system or public identifier. Then, in your XML document, when you reference this external entity, WebLogic Server fetches the local copy or the cached copy (whichever you have configured) when parsing the document.

For detailed information on creating external entity registries with the XML Registry, refer to External Entity Configuration Tasks.

Using Parsers Other Than the Built-In Parser

If you use JAXP to parse your XML documents, the WebLogic Server XML Registry (which is configured through the Administration Console) offers the following options:

- Accept the built-in parser as the server-wide parser.

- Configure the WebLogic FastParser as the server-wide parser.

- Configure another parser of your choice (such as a different version of the Apache Xerces parser) as the server-wide parser.

- Configure a parser for a particular DTD based on its system or public identifier, or its root tag.

For instructions on how to use the XML Registry to configure parsing options, see XML Parser and Transformer Configuration Tasks.

Using the WebLogic FastParser

WebLogic Server includes a high-performance non-validating XML parser (called WebLogic FastParser) specifically designed to parse small to medium (up to 10,000 elements) XML documents. For larger documents, the performance of this parser is comparable to that of other standard parsers, such as Apache Xerces.

Note: WebLogic FastParser supports only SAX-style parsing.

You can specify that WebLogic FastParser be used as the WebLogic Server-wide parser, or just for a particular DOCTYPE by using the XML Registry as described in XML Parser and Transformer Configuration Tasks. Set the SAXParserFactory field to weblogic.xml.babel.jaxp.SAXParserFactoryImpl.

Generating New XML Documents

This section describes how to generate XML documents from a DOM document tree and by using JSP.

Note: For detailed instructions on using the WebLogic XML Streaming API to generate XML documents, see Using the WebLogic XML Streaming API.

Generating XML from a DOM Document Tree

This section describes two ways to create an XML document from a DOM document tree:

- Using the Apache serialize classes

- Using the JAXP Transformer classes

Using the Apache Serialize Class

To generate an XML document from a DOM document tree, you can use the class weblogic.apache.xml.serialize to convert a DOM document tree to XML text. For a description of this class, see Javadoc for weblogic.apache.xml.serialize.

The following code example shows how to use this class.

Note: The following example does not use JAXP but rather the Apache proprietary API directly.

>     package test;

>     import java.io.OutputStreamWriter;
>     import java.util.Date;
>     import java.text.DateFormat;

>     import org.w3c.dom.Document;
>     import org.w3c.dom.Element;

>     import weblogic.apache.xerces.dom.DocumentImpl;
>     import weblogic.apache.xml.serialize.DOMSerializer;
>     import weblogic.apache.xml.serialize.XMLSerializer;

>     public class WriteXML {

>       public static void main(String[] args) throws Exception {

>         // Create a DOM tree.
>         Document doc= new DocumentImpl();
>         Element message = doc.createElement("message");
>         doc.appendChild(message);
>         Element text = doc.createElement("text");
>         text.appendChild(doc.createTextNode("Hello world."));
>         message.appendChild(text);
>         Element timestamp = doc.createElement("timestamp");
>         timestamp.appendChild(
>           doc.createTextNode(
>                    DateFormat.getDateInstance().format(new Date()))
>         );
>         message.appendChild(timestamp);

>         // Serialize the DOM to XML text and output to stdout.
>         DOMSerializer xmlSer =
>           new XMLSerializer(new OutputStreamWriter(System.out),null);
>         xmlSer.serialize(doc);
>       }
>     }

Using the JAXP Transformer Class

You can use the javax.xml.transform.Transformer class to serialize a DOM object into an XML stream, as shown in the following example segment:

>     import javax.xml.parsers.DocumentBuilder;
>     import javax.xml.parsers.DocumentBuilderFactory;

>     import org.w3c.dom.Document;

>     import javax.xml.transform.Transformer;
>     import javax.xml.transform.TransformerFactory;
>     import javax.xml.transform.dom.DOMSource;
>     import javax.xml.transform.stream.StreamResult;

>     import java.io.*;

>     ...

>     TransformerFactory trans_factory = TransformerFactory.newInstance();
>     Transformer xml_out = trans_factory.newTransformer();
>     Properties props = new Properties();
>     props.put("method", "xml");
>     xml_out.setOutputProperties(props);
>     xml_out.transform(new DOMSource(doc), new StreamResult(System.out));

In the example, the Transformer.transform() method does the work of converting a DOM object into an XML stream. The transform() method takes as input a javax.xml.transform.dom.DOMSource object, created from the DOM tree stored in the doc variable, and converts it into a javax.xml.transform.stream.StreamResult object and writes the resulting XML document to the standard output.

Generating XML Documents in a JSP

You typically use JSPs to generate HTML, but you can also use a JSP to generate an XML document.

Using JSPs to generate XML requires that you set the content type of the JSP page as follows:

>     <%@ page contentType="text/xml"%>
>         ... XML document

The following code shows an example of how to use JSP to generate an XML document:

>     <?xml version="1.0">

>     <%@ page contentType="text/xml" import="java.text.DateFormat,java.util.Date" %>

>     <message>
>       <text>
>         Hello World.
>       </text>
>       <timestamp>
>     <%
>     out.print(DateFormat.getDateInstance().format(new Date()));
>     %>
>       </timestamp>
>     </message>

For more information about using JSP to generate XML, see http://java.sun.com/products/jsp/html/JSPXML.html.

Transforming XML Documents

Transformation refers to converting an XML document (the source of the transformation) into another format, typically a different XML document, HTML, Wireless Markup Language (WML) (the result of the transformation.) This section describes how to transform XML documents using JAXP and from within a JSP using JSP tags.

Using JAXP to Transform XML Data

Version 1.1 of JAXP provides pluggable transformation, which means that you can use any JAXP-compliant transformer engine.

JAXP provides the following interfaces to transform XML data into a variety of formats:

- javax.xml.transform: This package contains the generic APIs for transforming documents. This package does not have any dependencies on SAX or DOM and makes the fewest possible assumptions about the format of the source and result.

- javax.xml.transform.stream: This package implements stream- and URI-specific transformation APIs. In particular, it defines the StreamSource and StreamResult classes that enable you to specify InputStreams and URLs as the source of a transformation and OutputStreams and URLs as the results, respectively.

- javax.xml.transform.dom: This package implements DOM-specific transformation APIs. In particular, it defines the DOMSource and DOMResult classes that enable you to specify a DOM tree as either the source or result, or both, of a transformation.

- javax.xml.transform.sax: This package implements SAX-specific transformation APIs. In particular, it defines the SAXSource and SAXResult classes that enable you to specify org.xml.sax.ContentHandler events as either the source or result, or both, of a transformation.

Transformation encompasses many possible combinations of inputs and outputs.

For a complete example of transforming an XML document, see the WL_HOME\samples\server\src\examples\xml\xslt directory, where WL_HOME refers to the top-level WebLogic Platform directory.

Example of Transforming an XML Document Using JAXP

The following example snippet shows how to use JAXP to transform myXMLdoc.xml into a different XML document using the mystylesheet.xsl stylesheet:

>     import javax.xml.transform.Transformer;
>     import javax.xml.transform.TransformerFactory;
>     import javax.xml.transform.stream.StreamSource;
>     import javax.xml.transform.stream.StreamResult;

>     Transformer trans;
>     TransformerFactory factory = TransformerFactory.newInstance();
>     String stylesheet = "file://stylesheets/mystylesheet.xsl";
>     String xml_doc = "file://xml_docs/myXMLdoc.xml";

>     trans = factory.newTransformer(new StreamSource(stylesheet));
>     trans.transform(new StreamSource(xml_doc),
>                      new StreamResult(System.out));

For an example of how to transform a DOM document into an XML stream, see Using the JAXP Transformer Class.

Converting Your XML Code From Using the Xalan API to JAXP 1.1 API

If your application contain Xalan-specific code, BEA recommends that you modify it to use JAXP instead.

This section briefly describes the changes you must make to your XML application in order to convert from using the Xalan API to JAXP. The section compares two code segments that perform a similar transformation task: one code segment uses the Xalan API directly and the other uses JAXP.

The following Java code segment uses JAXP:

>     import javax.xml.transform.Transformer;
>     import javax.xml.transform.TransformerFactory;
>     import javax.xml.transform.stream.StreamSource;
>     import javax.xml.transform.stream.StreamResult;

>     ...

>     Transformer trans;
>     TransformerFactory factory = TransformerFactory.newInstance();
>     String stylesheet = "file://stylesheets/mystylesheet.xsl";
>     String xml_doc = "file://xml_docs/myXMLdoc.xml";

>     trans = factory.newTransformer(new StreamSource(stylesheet));
>     trans.transform(new StreamSource(xml_doc),
>                      new StreamResult(System.out));

The following Java code segment uses the Xalan API directly:

>      /*
>      * This code example was taken from code examples provided by the
>      * Apache Software Foundation. It consists of voluntary
>      * contributions made by many individuals on behalf of the Apache
>      * Software Foundation and was originally based on software
>      * copyright (c) 1999, Lotus Development Corporation.,
>      * http://www.lotus.com. For more information on the Apache
>      * Software Foundation, please see <http://www.apache.org/>.
>      */

>     import org.apache.xalan.xslt.XSLTProcessorFactory;
>     import org.apache.xalan.xslt.XSLTInputSource;
>     import org.apache.xalan.xslt.XSLTResultTarget;
>     import org.apache.xalan.xslt.XSLTProcessor;

>     ...

>     XSLTProcessor processor = XSLTProcessorFactory.getProcessor();

>     String stylesheet = "file://stylesheets/mystylesheet.xsl";
>     String xml_doc = "file://xml_docs/myXMLdoc.xml";

>     processor.process(new XSLTInputSource(xml_doc),
>                           new XSLTInputSource(stylesheet),
>                           new XSLTResultTarget(System.out));

The following table summarizes the names of the Xalan and JAXP interfaces and methods used in the preceding examples to transform XML documents; use this table as a first step toward converting your existing Xalan application to a full JAXP application.

Note: This table does not include an entire mapping between Xalan and JAXP, but rather covers only the main classes and methods used in the preceding examples. Refer to the Apache and Sun Web sites at http://www.apache.org and http://java.sun.com/xml/index.html for more detailed information on each API.

Table 2-1 Equivalent Xalan and JAXP Classes and Interfaces

Description of Class or Interface | Xalan 1.X | JAXP 1.1
--- | --- | ---
Main class used to transform XML documents | XSLTProcessor | Transformer
Factory class used to create the transformer objects | XSLTProcessorFactory | TransformerFactory
Method used to create a new instance of the factory | n/a | TransformerFactory.newInstance()
Method used to create a new transformer object | XSLTProcessorFactory.getProcessor() | TransformerFactory.newTransformer()
Class that holds the source of the transformation, such as the XML document or an XSL stylesheet | XSLTInputSource | StreamSource
Class that holds the result of the transformation | XSLTResultTarget | StreamResult
Method that performs the transformation | XSLTProcessor.process() | Transformer.transform()

Using the JSP Tag to Transform XML Data

WebLogic Server provides a small JSP tag library for convenient access to an XSLT transformer from within a JSP. You can use this tag to transform XML documents into HTML, WML, and so on, but it is not required.

The JSP tag library consists of one main tag, x:xslt, and two subtags you can use within the x:xslt tag: x:stylesheet and x:xml.

XSLT JSP Tag Syntax

The XSLT JSP tag syntax is based on XML. A JSP tag consists of a start tag, an optional body, and a matching end tag. The start tag includes the element name and optional attributes.

The following syntax describes how to use the three XSLT JSP tags provided by WebLogic Server in a JSP. The attributes are optional, as are the subtags x:stylesheet and x:xml. The tables following the syntax describe the attributes of the x:xslt and x:stylesheet tags; the x:xml tag does not have any attributes.

>     <x:xslt  [xml="uri of XML file"]
>              [media="media type to determine stylesheet"]
>              [stylesheet="uri of stylesheet"]
>         <x:xml>In-line XML goes here
>         </x:xml>
>         <x:stylesheet [media="media type to determine stylesheet"]
>                       [uri="uri of stylesheet"]
>         </x:stylesheet>
>     </x:xslt>

The following table describes the attributes of the x:xslt tag.

Table 2-2 x:xslt JSP Tag Attributes

x:xslt Tag Attribute | Required | Data Type | Description
--- | --- | --- | ---
xml | No | String | Specifies the location of the XML file that you want to transform. The location is relative to the document root of the Web application in which the tag is used.
media | No | String | Defines the document output type, such as HTML or WML, that determines which stylesheet to use when transforming the XML document. This attribute can be used in conjunction with the media attribute of any enclosed x:stylesheet tags within the body of the x:xslt tag. The value of the media attribute of the x:xslt tag is compared to the value of the media attribute of any enclosed x:stylesheet tags. If the values are equal, then the stylesheet specified by the uri attribute of the x:stylesheet tag is applied to the XML document. NOTE: It is an error to set both the media and stylesheet attributes within the same x:xslt tag.
stylesheet | No | String | Specifies the location of the stylesheet to use to transform the XML document. The location is relative to the document root of the Web application in which the tag is used. NOTE: It is an error to set both the media and stylesheet attributes within the same x:xslt tag.

The following table describes the attributes of the x:stylesheet tag.

Table 2-3 x:stylesheet JSP Tag Attributes

x:stylesheet Tag Attribute | Required | Data Type | Description
--- | --- | --- | ---
media | No | String | Defines the document output type, such as HTML or WML, that determines which stylesheet to use when transforming the XML document. Use this attribute in conjunction with the media attribute of enveloping x:xslt tag. The value of the media attribute of the x:xslt tag is compared to the value of the media attribute of the enclosed x:stylesheet tags. If the values are equal, then the stylesheet specified by the uri attribute of the x:stylesheet tag is applied to the XML document.
uri | No | String | Specifies the location of the stylesheet to use when the value of the media attribute matches the value of the media attribute of the enveloping x:xslt tag. The location is relative to the document root of the Web application in which the tag is used.

XSLT JSP Tag Usage

The x:xslt tag can be used with or without a body, and its attributes are optional. This section describes the rules that dictate how the tag behaves depending on whether you specify a body or one or more attributes.

If the x:xslt JSP tag is an empty tag (no body), the following statements apply:

- If no attributes are set, the XML document is processed using the servlet path and the default media stylesheet. You specify the default media stylesheet in your XML file with the <?xml-stylesheet> processing instruction; the default stylesheet is the one that does not have a media attribute.

  This type of processing allows you to register the JSP page that contains the tag extension as a file servlet that performs XSLT processing.

- If only the media attribute is set, the XML document is processed using the servlet path and the specified media type. The value of the media type attribute of the x:xslt tag is compared to the value of the media attribute of any <?xml-stylesheet> processing instructions in your XML document; if any match then the corresponding stylesheet is applied. If none match then the default media stylesheet is used. The media type attribute is used to define the document output type (for example, XML, HTML, postscript, or WML). This feature enables you to organize stylesheets by document output type.

- If only the xml attribute is set, the specified XML document is processed using the default media stylesheet.

- If the media and xml attributes are set, the specified XML document is processed using the specified media type.

- If the stylesheet attribute is defined, the XML document is processed using the specified stylesheet.

Caution: It is an error to set both the media and stylesheet attributes within the same x:xslt tag.

An XSLT JSP tag that has a body may contain <x:xml> tags and/or <x:stylesheet> tags. The following statements apply:

- The <x:xml> tag allows you specify an XML document for inline processing. This tag has no attributes.

- The <x:stylesheet> tag, when used without any attributes, allows you specify the default stylesheet inline.

- Use the uri attribute of the <x:stylesheet> tag to specify the location of the default stylesheet.

- If you want to specify different stylesheets for different media types, you can use multiple <x:stylesheet> tags with different values for the media attribute. You can specify a stylesheet for each media type in the body of the tag, or specify the location of the stylesheet with the uri attribute.

Transforming XML Documents Using an XSLT JSP Tag

To use an XSLT JSP tag to transform XML documents, perform the following steps:

1. Open the xmlx.zip file in the WL_HOME\server\ext directory; extract the xmlx-tags.jar file; and put it in the /lib directory of your Web application, where BEA Home is the top-level directory in which you installed the WebLogic Server distribution.

2. Add a <taglib> entry to the web.xml file. For example:

   >     <taglib>
   >       <taglib-uri>xmlx.tld</taglib-uri>
   >       <taglib-location>/WEB-INF/lib/xmlx-tags.jar</taglib-location>
   >     </taglib>

3. To use the tags, add the following line to your JSP page:

   >     <%@ taglib uri="xmlx.tld" prefix="x"%>

4. Configure the transformer. The following procedure shows a generic way to configure the transformer:

   1. Enter the following code line to create an xslt.jsp file:

      >     <%@ taglib uri="xmlx.tld" prefix="x"%><x:xslt/>

   2. Register the xslt.jsp file in your web.xml file, as follows:

      >     <servlet>
      >        <servlet-name>myxsltinterceptor</servlet-name>
      >        <jsp-file>xslt.jsp</jsp-file>
      >     </servlet>
      >     <servlet-mapping>
      >        <servlet-name>myxsltinterceptor</servlet-name>
      >        <url-pattern>/xslt/*</url-pattern>
      >     </servlet-mapping>

   3. Put your XML, DTD, and XSL documents or servlets in your Web application.

   4. Add an xslt prefix to the pathname for the XML document (for example, change docs/fred.xml to xslt/docs/fred.xml) and then access the document. Because of the <url-pattern> entry in the web.xml file, WebLogic Server automatically runs the XSLT transformer on the XML document and sets the default stylesheet in the document.

   5. To define media type, add code to the JSP to determine the media type for the XML document and the content type for the output.

   6. Pass the media type into the xslt tag and then set the content type of the response object.

Note: The other forms of the XSLT JSP tag are used when stylesheets are not specified in the XML document or your XML stylesheet can be generated inline.

Example of Using the XSLT JSP Tag in a JSP

The following snippet of code from a JSP shows how to use the XSLT JSP tag to transform XML into HTML or WML, depending on the type of client that is requesting the JSP. If the client is a browser, the JSP returns HTML; if the client is a wireless device, the JSP returns WML.

First the JSP uses the getHeader() method of the HttpServletRequest object to determine the type of client that is requesting the JSP and sets the myMedia variable to wml or html appropriately. If the JSP set the myMedia variable to html, then it applies the html.xsl stylesheet to the XML document contained in the content variable. Similarly, if the JSP set the myMedia variable to wml, then it applies the wml.xsl stylesheet.

>     <%
>        String clientType = request.getHeader("User-Agent");
>        // default to WML client
>        String myMedia = "wml";

>        // if client is an HTML browser

>        if (clientType.indexOf("Mozilla") != -1) {
>           myMedia = "http"
>        }
>     %>

>     <x:xslt media="<%=myMedia%>">
>       <x:xml><%=content%></x:xml>
>       <x:stylesheet media="html" uri="html.xsl"/>
>       <x:stylesheet media="wml"  uri="wml.xsl"/>
>     </x:xslt>

Using Transformers Other Than the Built-In Transformer

The WebLogic Server XML Registry (which you configure using the Administration Console) offers the following options:

- Accept the built-in transformer as the server-wide transformer.

- Configure a transformer other than the built-in transformer as the server-wide transformer. The transformer must be JAXP-compliant.

For instructions on how to use the XML Registry to configure transforming options, see XML Parser and Transformer Configuration Tasks.