Corporate Info | News | Solutions | Products | Partners | Services | Events | Download | How To Buy

# Using XML With WebLogic Server Introduction Overview Why Use XML? XML API SAX DOM Implementing XML with WebLogic Server Generating XML documents Explicitly writing documents to an output stream Using DOM API Passing XML documents between applications Using JSPs/servlets Using JMS Parsing XML documents Using SAX API Using DOM API Validating XML documents Resolving external entities Using the system identifier Implementing EntityResolver Creating wrapper classes for XML documents XML and Enterprise JavaBeans Extensible Style Language Additional resources # Introduction This document provides a foundation for using XML with WebLogic Server. It focuses primarily on how XML interfaces with the various services of WebLogic Server. For more information on XML and related technologies, please refer to the Additional resources section. ## Overview Extensible Markup Language (XML) is a markup language for documents containing structured information. It is a simplified version of Standard Generalized Markup Language (SGML) and has become an industry standard for delivering content on the Internet. Like HTML, XML uses tags to describe content. However, rather than focusing on the presentation of content, the tags in XML describe the meaning and hierarchical structure of the data. This allows for sophisticated data types, as required for efficient data interchange between different programs and systems. By providing a facility to define new tags, XML is also extensible. The XML syntax uses matching start and end tags to mark up information. Information delimited by tags is called an element. Elements may have attributes in the form of name-value pairs. The syntactic meaning associated with the tags of an XML document can be defined in a Document Type Definition (DTD). A DTD describes what elements and attributes are valid in an XML document, and in what context they are valid. In other words, a DTD specifies which tags are allowed within certain other tags, and which tags and attributes are optional. ## Why use XML? Each industry typically has one or more methods for exchanging data meaningful and specific to that industry. With the advent of E-Commerce, many businesses have an increasing number of relationships with a variety of industries requiring expert knowledge of each of the associated protocols used for electronic communication. Because of XML's extensibility, it is a very effective tool for normalizing the format of data interchange between vertical industries. A typical scenario involves message brokers and workflow engines responsible for coordinating transactions that involve multiple industries or departments within an enterprise. XML can be used to combine data from disparate sources into format that is understandable by all parties. ## XML API Two standard APIs have emerged providing programmatic access to XML data. First, the SAX (Simple API for XML) interfaces define handlers containing methods that are called as the various parts of an XML document are parsed. Second, the DOM (Document Object Model) interfaces define a logical tree representing the XML document after parsing. Both APIs are platform-independent and language-neutral. ### SAX SAX is a standard interface for event-based XML parsing developed collaboratively by the members of the XML-DEV mailing list. SAX applications process an XML document by creating a parser object and associating handlers for XML events. The parser reads through the document handing events to the handler as they occur. Events represent the entities within the document such as start of document, end of document, and start of element. The SAX interface provides a very simple coding model and is useful for processing XML documents with a relatively simple hierarchical structure. We will discuss the SAX API in more detail in Parsing XML documents. For the Javadocs of the SAX API, please refer to Additional resources. ### DOM The Document Object Model (DOM) is a platform- and language-neutral interface that allows programs and scripts to dynamically access and update the content, structure and style of XML documents. DOM gives you access to the information stored in your XML document as a hierarchical object model, much like a tree with the document's root element as the tree's root node. Using the DOM interface, you can access different parts of XML documents, navigate through them, and make changes and additions to them. When an application invokes a DOM parser, the parser processes the entire document, creating an in-memory object model which the application can process in any fashion it chooses. The DOM approach is most useful for more complex documents since it does not require the developer to interpret every element. We will discuss the DOM API in more detail in Generating XML documents and Parsing XML documents. For the Javadocs of the DOM API, please refer to Additional resources. # Implementing XML with WebLogic Server How does this all work with WebLogic Server? As with any data format, to use XML in an application, you need tools and methods for generating, passing, and processing XML documents. In the following sections, we will discuss some of these methods, and how they apply to WebLogic Server. Generating XML documents Explicitly writing documents to an output stream Using DOM API Passing XML documents between applications Using JSPs/servlets Using JMS Parsing XML documents Using SAX API Using DOM API Validating XML documents Resolving external entities Using the system identifier Implementing EntityResolver Creating wrapper classes for XML documents XML and Enterprise JavaBeans ## Generating XML documents In this section, we will briefly discuss methods for programmatically generating XML documents. This discussion does not include the delivery of static XML documents or what makes an XML document well-formed or valid. For information on these topics, please see the Additional resources section. ### Explicitly writing documents to an output stream In the XML over HTTP example, StockClient and StockServlet explicitly write XML documents to the appropriate output stream. In the code segment below StockClient generates XML based on user input that defines a stock trade transaction. The document includes an XML declaration, a document type declaration, and the XML content. Note how the buy, webl, and line variables are used to programmatically determine the content of the document.
      // send xml to servlet
      pw.println("<?xml version='1.0'?>");

      // set document type declaration
      pw.println("<!DOCTYPE stocktrade SYSTEM '"+serverURL
        +"stocktrade.dtd'>");

      // set stock trade instructions
      pw.print("<stocktrade ");
      pw.print("action = "+ (buy ? "'buy' " : "'sell' "));
      pw.print("symbol = "+ (webl ? "'WEBL' " : "'INTL' "));
      pw.print("numShares = '"+ line +"'");
      pw.println(" />");
### Using DOM API The DOM API provides methods for building and modifying entire XML documents in memory. Once a document has been generated, you simply write the document to the appropriate output stream. This will be discussed further in Passing XML documents between applications. In the XML via JMS example, Client creates an XML document using the DOM API as shown below.
      // create a new XML document
      XmlDocument xmlDoc = new XmlDocument();

      // set the document type declaration
      xmlDoc.setDoctype(
        "weblogic-examples-xml-jms-dtd",
        "http://www.weblogic.com/docs51/examples/xml/jms/workflow.dtd",
        "");

      // assign elements and attributes
      Element root = xmlDoc.createElement("workflow");
      root.setAttribute("message", message);
      root.setAttribute("sender", username);
      root.setAttribute("status", status);
      xmlDoc.appendChild(root);
Since the DOM API allows you to work with an entire XML document in memory, it is easy to modify and re-use the document. In the XML via JMS example, AdminClient receives the document sent from Client, modifies a couple of the element atttributes, then re-sends the document back to Client. ## Passing XML documents between applications One of the more powerful features of XML in web-based applications is its use as a message format for communication between applications. Java Server Pages (JSP), servlets, and Java clients can use XML to pass structured data over a variety of protocols. When considering the different methods for passing XML documents, the main difference in implementation is in how you obtain the input/output streams for reading/writing the XML documents. This section discusses two common methods of passing an XML document between applications: Using JSPs/Servlets and Using JMS. ### Using JSPs/servlets XML documents can easily be transfered over HTTP via the POST method of a JSP page or servlet. In the XML over HTTP example, StockClient and StockServlet pass XML documents to each other via an HTTP POST as shown in the diagram below. StockClient connects to the StockServlet and sends an XML document via the POST method. The following code segment from StockClient obtains the URL to the servlet from the argument list, opens a URL connection, obtains the output stream from the connection, and prints the first couple of lines of the XML document to the output stream.
      URL url = new URL(args[0]);
      .
      .
      .
      URLConnection urlc = url.openConnection();
      urlc.setDoOutput(true);
      urlc.setDoInput(true);
      PrintWriter pw = new PrintWriter(new
        OutputStreamWriter(urlc.getOutputStream()), true);

      // send xml to servlet
      pw.println("<?xml version='1.0'?>");

      // set document type declaration
      pw.println("<!DOCTYPE stocktrade SYSTEM '"+serverURL
        +"stocktrade.dtd'>");
StockServlet processes the XML sent from StockClient and returns the results in another XML document. The following code from StockClient reads the resulting XML document from the URL connection's input stream and parses it. For more information on parsing an XML document see Parsing XML documents.
      parser.parse(new InputSource(new BufferedReader(
        new InputStreamReader(urlc.getInputStream()))));
Now lets look at how StockServlet reads in the XML document sent from StockClient. As mentioned above, StockClient sends an XML document within the HTTP request header (the POST method). Within StockServlet's doPost method, the following code obtains a BufferedReader from the request and passes to a RequestHandler object to be parsed. For more information on parsing an XML document see Parsing XML documents.
      RequestHandler rh = new RequestHandler();
      try {
        rh.parseXML(request.getReader(), parserClass);
      }
After processing the request, StockServlet returns an XML document to StockClient by using a PrintWriter obtained from the HTTP response as shown below.
      PrintWriter responseWriter = response.getWriter();
      responseWriter.println("<?xml version='1.0'?>");
      responseWriter.println("<!DOCTYPE traderesult SYSTEM '"
        +serverURL+"traderesult.dtd'>");
      .
      .
      .
### Using JMS In the XML via JMS example, the Client and AdminClient applications send XML documents to each other as JMS TextMessages as shown in the diagram below. In Using DOM API, we discussed how an entire XML can be created in memory. Once Client has generated the document, it writes the document to a String which is used to set the message text prior to sending the message to the JMS queue as shown below.
      // write document to a String and send as a JMS text message
      StringWriter sw = new StringWriter();
      try {
        xmlDoc.write(sw);
        msg.setText(sw.toString());
        msg.setStringProperty("messageTo", sendTo);
        qsender.send(msg);
      } catch (Exception e) {
        e.printStackTrace();
      }
When a message is received, the text is extracted from the message then parsed as shown below. For more information on parsing an XML document see Parsing XML documents.
      // get the message and parse
      String msgText = ((TextMessage) message).getText();
      parser.parse(new InputSource(new StringReader(msgText)));
## Parsing XML documents In order to use XML within any application, you need a mechanism for processing XML. This includes the ability to parse the document and expose the data stored within. In this section, we will discuss parsing XML documents Using SAX API and Using DOM API. ### Using SAX API SAX parsers must have an associated handler class to handle parsing events. The org.xml.sax.HandlerBase class is the default base class for handlers. This class contains methods that are called by the parser as a document is parsed. By default, these methods do nothing. In the XML over HTTP example, StockServlet receives XML documents via the POST method. The helper class RequestHandler extends HandlerBase and is used to handle all parsing events. After a document has been parsed, RequestHandler returns an object that is used by StockServlet to access the document data and finish processing the request. As an XML document is parsed, the event handling methods of RequestHandler are used to build a Hashtable named trade that contains all of the document data in name-value pairs. The following method from RequestHandler is called whenever a new element is encountered by the parser.
      public void startElement(String name, AttributeList attrs)
        throws SAXException {
          if (attrs != null) {
              int len = attrs.getLength();
              for (int i = 0; i < len; i++) {
                trade.put(attrs.getName(i), attrs.getValue(i));
              }
          }
      }
After the document is parsed, the getData method is called on RequestHandler to obtain the Hashtable as can be seen in this code segment from StockServlet.
      RequestHandler rh = new RequestHandler();

      try {
        rh.parseXML(request.getReader(), parserClass);
      }
      .
      .
      .
      java.util.Hashtable trade = rh.getData();
After obtaining the Hashtable, StockServlet uses the data to operate on TraderBean and fulfill the stock trade request. ### Using DOM API Parsing an XML document with a DOM parser results in a org.w3c.dom.Document object. This is a hierarchical object model of the document that can be traversed, read, and modified using the DOM API. The XML over HTTP example uses the Project X parser from Sun. This DOM implementation uses a SAX parser with a special document handler, XMLDocumentBuilder that builds the Document object when the document is parsed. The following code from Client creates a parser, sets an EntityResolver (this will be discussed in Implementing EntityResolver), sets the document handler, and obtains and parses the document.
      // obtain a DOM parser and associate the
      // resolver and document builder
      Parser parser = new com.sun.xml.parser.Parser();

      // use custom entity resolver to locate the DTD when parsing
      ResourceEntityResolver rer = new ResourceEntityResolver();
      rer.addEntityResource(
        "weblogic-examples-xml-jms-dtd",
        "workflow.dtd",
        getClass());
      parser.setEntityResolver(rer);

      XmlDocumentBuilder builder = new XmlDocumentBuilder();
      builder.setDisableNamespaces(true);
      builder.setParser(parser);

      // get the message and parse
      String msgText = ((TextMessage) message).getText();
      parser.parse(new InputSource(new StringReader(msgText)));

      // get document data and display results to console
      Document doc =  builder.getDocument();
## Validating XML documents As mentioned earlier, an XML DTD contains markup declarations that provide a grammar for a class of documents. An XML document is considered valid if it has an associated DTD, and the document complies with the constraints expressed within it. Validation is a powerful tool for ensuring that an XML document contains all of the necessary information required by your application. XML parsers will automatically check a document to ensure that it is well-formed, however to validate a document, you must include a DTD within your document. This is handled within the document type declaration which was introduced in Generating XML documents. Document type declarations take the general form:
      <!DOCTYPE NAME SYSTEM "file"[]>
The use of the document type declaration varies depending on the subsets used to house the DTD. For external subsets, the SYSTEM term is used to indicate that the following system identifier URI, "file", must be read and resolved. For internal subsets, the DTD must be contained explicitly within the [ and ]. NAME defines the name of the document type. When using an external subset to house a DTD, you must consider how the parser will resolve the external entity. This is discussed in Resolving external entities ## Resolving external entities For applications that piece together XML documents from multiple sources or include DTDs within XML documents as external subsets, external entity resolution must be addressed. org.xml.sax.EntityResolver defines an interface for an object that works with the parser to manage and locate external entities. If the resolver fails to locate an entity, the parser will use the system identifier URI to attempt to locate entity. This is the default behavior for most parser implementations. In the following sections, we will briefly discuss resolving external entities by Using the system identifier and by Implementing EntityResolver. ### Using the system identifier The parser's default behavior for resolving external entities is to use the system identifier URI. In the XML over HTTP example, the DTDs are housed within external subsets. To make them accessible to both the client and the servlet, the DTDs are copied to the server's document root and the system identifer within the document type declaration is set to the URL of the DTDs served up by the server. The document root is the root directory for files that are publicly available on your WebLogic Server. For more details, see Setting up a document root. In the example, both the client and servlet programatically determine the URL of the server as shown in the following code segment from StockClient.
      String serverURL = args[0];
      // Remove the servlet name from this String
      // This will be used to locate the dtd
      serverURL = serverURL.substring(0, serverURL.indexOf("StockServlet"));
After StockClient connects to the servlet, the name of the servlet is stripped off of the URL resulting in the URL to the server. The server URL is then used to locate the stocktrade.dtd in the following line that generates the document type declaration.
      pw.println("<!DOCTYPE stocktrade SYSTEM '"
        +serverURL+"stocktrade.dtd'>");
As a result of including the DTD within the document type declaration, the parser validates the XML document and notifies the document handler if any problems are encountered. ### Implementing EntityResolver Some applications will require customized handling for external entities. By implementing EntityResolver, your application will have the ability to locate and/or modify the external entity before it is included within the document by the parser. In the XML via JMS example, the DTDs are housed in external subsets. ResourceEntityResolver implements EntityResolver and uses the classloader to locate the DTDs. This is done by first establishing a unique public identifier for the DTD. This identifier is included in the document type declaration and is used by ResourceEntityResolver to determine which resource is being requested. ResourceEntityResolver also associates the DTDs with the client class that uses them (see the code segment presented in Using DOM API). Prior to running the example, the DTDs are copied to the directory containing the client class. When the parser reads the document type declaration, it passes the public identifier to ResourceEntityResolver through the resolveEntity method as shown below.
      public InputSource resolveEntity(String publicId, String systemId)
        throws SAXException, IOException
      {

        InputSource ins = null;

        EntityResource resource =
          (EntityResource) entityCatalog.get(publicId);

        InputStream resin = resource.getResourceAsStream();

        if (resin == null) {
          // we didn't find the local resource, so we return null to
          // signal the parser that it must resolve the entity itself.
          return null;
        }

        ins = new InputSource(resin);
        ins.setPublicId(publicId);
        return ins;
      }
The getResourceAsStream method utilizes the classloader to locate the associated class (and therefore the DTD). It then converts the DTD to an InputStream to be handed off to the parser. If the entity is not resolved, ResourceEntityResolver returns a null indicating to the parser that it must use the system identifier to resolve the entity. ## Creating wrapper classes for XML documents Once your application has received an XML document, it may be necessary to pass the document to multiple server-side objects for processing. Obviously, it is inefficient to require each object that uses the document to parse it in order to access that data stored within. To make the document information excessible to multiple objects, it is often useful to create a wrapper class that can read in a document, parse it, set private variables representing the document elements and attributes, and provide accessor methods for the element and attribute values. To create these wrapper classes you must have knowledge document's structure, or DTD, in order to provide the appropriate variables and accessor methods. Additionaly, wrapper classes can be useful to provide an easy way to generate an XML document. In the BizTalk server example, DOMIncomingMessage is a wrapper class for BizTalk documents and provides efficient access to data stored in incoming documents. DOMOutgoingMessage provides an easy way to generate BizTalk documents. ## XML and Enterprise Java Beans In Passing XML documents, we discussed various methods for getting XML documents from one place to another. This ability to communicate complex data structures over the wire, allows us to easily establish a mediator for working with EJBeans. For example by passing documents over HTTP, data can be sent to a servlet from anything that supports that ability to write to an HTTP connection. Once the document is parsed by the servlet, the data can be used by the servlet to operate on an EJBean on behalf of the client. Results can then be returned to the client in the form of an XML document. Within this architecture, the servlet acts as a mediator between the client and the EJBean, and XML is the serialization format for communication between the client and servlet. This promotes loose coupling of the client and EJBean by keeping the objects from referring to each other explicitly, and it allows you to vary their interaction independently. The client does not need to know anything about the EJBean interfaces. In fact, the only requirements for the client application are a knowledge of the DTD governing the XML structure, and the ability to read and write to an HTTP connection. Since these requirements are platform- and language-neutral, this greatly reduces client dependency and increases inter-operability of the system. In the XML over HTTP example, StockServlet acts as the mediator between StockClient and TraderBean. StockClient has no knowledge of the TraderBean interfaces. However, by connecting to StockServlet and passing XML documents that are valid with respect to the stocktrade.dtd, the trade is executed on behalf of StockClient. ## Extensible Stylesheet Language (XSL) The Extensible Stylesheet Language (XSL) includes both a transformation language (XLST) and a formatting language. These two languages function independently of each other. In this section, we will discuss XLST and how it can be used to transform a well-formed XML document into another XML document or fragment. XSL is an XML-based language that is understood by an XSL processor. It provides elements that define rules for how one XML document is transformed into another XML document. An XSL processor accepts as input an XML document and an XSL document. The template rules contained in an XSL document have patterns specifying the XML tree to which the rule applies. The XSL processor scans the XML document for patterns that match the rule, then applies the template to the appropriate section of the original XML document. Some XSL processors also support output as HTML and/or raw text, though the standard does not required them to do so. A common use of XSL transformation is in applications that support multiple client types. For example, suppose you have an web-based application that supports both browser-based clients and Wireless Application Protocol (WAP) clients. Since these clients understand different markup languages (HTML and WML respectively), your application must be able to deliver content that is appropriate for the given user. The most efficient way to handle this is to have your application produce an XML document when responding to a client. Prior to sending the response back to the client, the XML document can then be transformed into HTML or WML depending on the client's browser type. The browser type can be determined by examining the User-Agent request header of an HTTP request. See the SnoopServlet example included in the examples/servlets subdirectory of your WebLogic distribution for an example of accessing this type of header information. This architecture helps to concentrate the effort required to support multiple client types into the development of the appropriate XSL stylesheets. Additionally, it allows your application to easily adapt to other clients types if required. For additional information on XSL, see Additional resources. # Additional resources Code examples XML examples Related WebLogic Services BEA WebLogic Server Enterpise JavaBeans Using WebLogic JMS Using WebLogic JSP Using WebLogic HTTP Servlet Using WAP with WebLogic Server General XML information W3C (World Wide Web Consortium) XML.com XML FAQ XML.org, The XML Industry Portal W3C: Extensible Stylesheet Language Tutorials and online courses A Technical Introduction to XML XML Authoring Tutorial Working with XML and Java Tutorials for using the Java 2 platform and XML technology XML, Java, and the Future of the Web Chapter 14 of the XML Bible: XSL Transformations XSL Tutorial by Miloslav Nic XML APIs SAX (Simple API for XML) DOM (Document Object Model) XML Specifications Extensible Markup Language (XML) 1.0 Specification Extensible Style Language (XSL) 1.0 Specification JSR-000031 XML Data Binding Specification XML Path Language (XPath) Version 1.0 Specification XML Linking Language (XLink) Specification XML Pointer Language (XPointer) Specification Namespaces in XML Specification XML Schema Part 1: Structures Specification XML Schema Part 2: Datatypes Specification

application
Copyright © 2000 BEA Systems, Inc. All rights reserved. Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher.