XML Administration

 

The following sections describe XML administration with WebLogic Server:

• Introduction to XML Administration

• Using the XML Registry

• XML Registry Configuration Tasks

For additional information about using the XML Registry to configure WebLogic Server for XML applications, see the Administration Guide and the Administration Console Online Help.

Introduction to XML Administration

You use the XML Registry, which is accessed through the Administration Console, to configure WebLogic Server for XML applications.

By default, WebLogic Server is configured to use the built-in parser to parse XML documents. As long as you use the default configuration, you do not have to perform any configuration tasks for your XML applications. If you want to use a parser or parsers other than the built-in parser, you must use the XML Registry to configure them.

Note: To use the XML Registry to configure WebLogic Server for an XML application, you must use the Java API for XML Parsing (JAXP). If you use a parser through the parser's own proprietary API, the XML Registry has no effect on the behavior of your XML application.

Using the XML Registry

You create, configure, and use the XML Registry through the Administration Console. You can configure as many XML Registries in a domain as there are servers in a domain, but you can only configure one XML Registry or zero for a particular server.

The benefits of using the Administration Console XML Registry are as follows:

• Configuration changes take effect automatically at run time, provided you use JAXP API.

• When you make changes using the XML Registry, it is not necessary to change the XML application code.

• Entity resolution is done locally. You can use the XML Registry to define a local copy of an entity. This means that the parser does not have to go to the Web site to parse. Instead, the parser downloads the entity from the Administration Server and then caches it.

You can use the XML Registry to specify the following:

• Specify an alternative default XML parser to use instead of the built-in parser included in this version of WebLogic Server.

• Specify an XML parser to be used to process a particular document type (including custom-generated parsers).

• Specify external entities that are to be resolved using local copies. Once these entities are specified, the Administration Server stores local copies of them in the file system and automatically distributes them to the server's parser at parse time. This feature eliminates the need to construct and set SAX EntityResolvers.

• The advantage of using local copies of external entities is that the parser does not have to consult an external Web site, which improves parser performance.

All of the above capabilities are automatically enabled if your application uses the standard Java API for XML Parsing (JAXP), which is included in this version of WebLogic Server. These capabilities are for use on the server side only.

Example of an XML Registry

Use the Administration Console to access and edit contents of the XML Registry. Figure 3-1 shows an example of an XML Registry configured through the Administration Console.

Figure 3-1 Sample XML Registry Code Displayed in Administration Console

Relationship Between JAXP and the XML Registry

The XML registry is automatically consulted whenever you use the JAXP API to write your XML applications. The WebLogic Server JAXP implementation can inspect the content of the XML document and delegate to an appropriate parser based on the XML Registry configuration. If no parser is registered for the document type, the JAXP implementation delegates to the default parsers specified in the XML Registry. If no default parsers are registered, the built-in parser is registered for the document type. Additionally, when WebLogic Server starts, a SAX entity resolver is automatically set so that it can resolve entities that are declared in the registry. As a result, users are not required to modify their XML application code to control the parsers used, or to set the location of local copies of external entities. All of this is controlled by the XML Registry.

Note: If you elect to use an API provided by a parser instead of the JAXP API, the XML Registry has no effect on the processing of XML documents.

XML Registry Configuration Tasks

You can use the XML Registry to perform the following tasks:

• Configuring a Parser Other Than the Built-In Parser

  In this configuration, WebLogic Server uses parsers other than the built-in parser. For example, you can configure WebLogic Server to use the bundled version of the Apache Xerces parser, the Sun parser, and other available parsers.

• Configuring a Custom-Generated Parser

  In this configuration, WebLogic Server uses custom parsers generated using the WebLogic Parser Generator.

• Configuring Local Entity Resolution

  In this configuration, WebLogic Server uses local copies of external entities for entity resolution.

Using the Built-In Parser

WebLogic Server uses the built-in parser to parse XML documents by default. You do not have to perform any configuration tasks. You simply write and build your XML application using the JAXP API.

Configuring a Parser Other Than the Built-In Parser

To use a parser other than the built-in parser, use the following procedure:

1. Start the server, open the Administration Console.

2. Right-click the XML node and select Create a new XML Registry from the drop-down menu. The XML Registries>Create window is displayed (see Figure 3-2).

   Figure 3-2 XML Registries Create Window

   

3. Enter a unique registry name in the Name field and set the DocumentBuilderFactory and the SaxParserFactory fields to the appropriate parser classes.

   For example, to use the Sun parser, enter the following in the XML Registries>Create window (see Figure 3-3):

   Name: Sun Parser Registry
   DocumentBuilderFactory: com.sun.xml.parser.DocumentBuilderFactoryImpl
   SAXParserFactory: com.sun.xml.parser.SAXParserFactoryImpl

   To use the bundled Apache Xerces parser from the XML Module, enter the following in the XML Registries>Create window.

   Name: Xerces parer Registry
   DocumentBuilderFactory: "org.apache.xerces.jaxp.DocumentBuilderFactoryImpl"
   SAXParserFactory:  "org.apache.xerces.jaxp.SAXParserFactoryImpl"

   Figure 3-3 Configured Sun Parser Registry

   

4. Click the Create button. The XML Registry is created and listed under the XML node.

5. Click the Servers node in the left pane. The Servers table displays in the right pane showing all the servers defined in the domain (see Figure 3-4).

   Figure 3-4 Servers Table Window

   

6. Click the Create a New Server text link. A dialog is displayed in the right pane showing the tabs associated with configuring a new server (see Figure 3-5).

   Figure 3-5 Server Configuration Window

   

7. Enter values in the Name, Machine, and System Password attribute fields.

8. Click the Create button in the lower right corner to create a server instance with the name you specified in the Name field. The new instance is added under the Servers node in the left pane.

9. Click the Services tab. The XML Registry folder window is displayed (see Figure 3-6).

   Figure 3-6 XML Registry Folder Window

   

10. Select the Sun Parser Registry in the XML Registry field and click the Apply button.

11. Restart your server so the new settings to take effect.

Configuring a Custom-Generated Parser

You can generate a custom parser based on a specific DTD. For instructions about how to generate a custom parser, see Using the WebLogic Parser Generator to Generate Custom Parsers.

To use a generated parser to parse XML documents based on a particular DTD, perform the following steps:

1. Start the server and open the Administration Console.

2. Right-click the XML node and select Create a New XML Registry from the drop-down menu. The XML Registries>Create window is displayed (see Figure 3-2).

3. Enter a unique name (for example: Generated Parser Registry) for the new XML Registry and click the Create button. The XML Registries>Generated Parser Registry window is displayed (see Figure 3-7).

   Figure 3-7 XML Registries Generated Parser Registry Window

   

4. Click Edit Entries. The XML Registry Entries window is displayed (see Figure 3-8).

   Figure 3-8 XML Registry Entries Window

   

5. Click Create a new XML Registry Entry. A blank XML Registries>Create window is displayed (see Figure 3-9).

   Figure 3-9 XML Registries Create Window

   

6. Enter the doctype in one of the following ways:

   1. Use either the Public Id or the System Id field to specify the doctype. For example, for the car.dtd (see Listing 3-1), enter -//BEA Systems, Inc.//DTD for cars//EN in the Public Id field.

   2. Specify the Root Element Tag name of the document.

      Listing 3-1 car.xml File

      ---

      <?xml version="1.0"?> 
      <!-- This XML document describes a car --> 
      <!DOCTYPE CAR PUBLIC "-//BEA Systems, Inc.//DTD for cars//EN" 
      "http://dev/null"> 
      <CAR> 
      <MAKE>Toyota</MAKE> 
      <MODEL>Corrolla</MODEL> 
      <YEAR>1998</YEAR> 
      <ENGINE>1.5L</ENGINE> 
      <HP>149</HP> 
      </CAR>

      ---

7. Enter the parser name in the Parser Class Name field. For example, for the CarParser generated parser, enter com.foo.myapp.parsers.CarParser.

8. Click the Create button. The XML Registry is created and listed under the XML node.

   Note: Using URLs is not desirable because both reliability and performance may suffer.

9. Click the Servers node in the left pane to display the Servers table in the right pane, showing all the servers defined in the domain (see Figure 3-4).

10. Click the Create a New Server text link. A dialog is displayed in the right pane showing the tabs associated with configuring a new server (see Figure 3-5).

11. Enter values in the Name, Machine, and System Password attribute fields.

12. Click the Create button in the lower right corner to create a server instance with the name you specified in the Name field. The new instance is added under the Servers node in the left pane.

13. Click the Services tab. The XML Registry folder window is displayed (see Figure 3-6).

14. Select the Generated Parser Registry in the XML Registry field and click the Apply button.

15. Restart your server to make the new settings take effect.

Configuring Local Entity Resolution

You can use the XML Registry to define local copies of external entities. These entities can then be copied to a local area for resolution so that WebLogic Server does not have to access a remote Web site to resolve them.

To configure local entity resolution, perform the following steps:

1. Start the server, open the Administration Console, and click the XML node. The XML Registries window is displayed (see Figure 3-8).

2. Click Create a new XML Registry. The XML Registries>Create window is displayed (see Figure 3-2).

3. Enter a name for the XML Registry and click the Create button. The named window is displayed (see Figure 3-7).

4. Click Edit Entries. The XML Registry> Entries window is displayed (see Figure 3-8).

5. Click Create a new XML Registry Entry. A blank XML Registry Entries>Create window is displayed (see Figure 3-10).

   Figure 3-10 XML Registry Entries Create Window for Entity Resolution

   

6. Enter the system Id. For example, for the car.dtd entity (see Listing 3-2), enter http://www.bea.com/dtd/car.dtd.

7. In the Entity Path field, enter the pathname of the local copy of the entity file in the Administration Server. This pathname must be relative to the registries entity directory. The entity directory is the directory
   c:/BEA Home/wlserver6.0/config/examples/xml/registries/reg_name in the domain configuration directory, where BEA Home is the top-level directory in which the WebLogic Server software is installed. The reg_name is the name of the new XML Registry. For example, for the car.dtd, enter dtd/car.dtd in the Entity Path field.

8. Click the Create button. The XML Registry is created and listed under the XML node.

9. Copy the entity file into the entity directory. For example, you would copy the car.dtd file to xml/registry/myregistry/dtd/car.dtd.

10. Restart your server so the new settings to take effect.