Administering WebLogic Server XML

The following sections describe XML administration with WebLogic Server:

• Overview of Administering WebLogic Server XML
• XML Parser and Transformer Configuration Tasks
• External Entity Configuration Tasks

 

---

Overview of Administering WebLogic Server XML

You access the XML Registry through the Administration Console and use it to configure WebLogic Server for XML applications.

To invoke the Administration Console in your browser, enter the following URL:

http://host:port/console

where

• host refers to the computer on which the WebLogic Administration Server is running.
• port refers to the port number where WebLogic Administration Server is listening for connection requests. The default port number for WebLogic Administration Server is 7001.

XML Administration Tasks

You create, configure, and use the XML Registry through the Administration Console. Using the Administration Console XML Registry has several benefits:

• Configuration of XML Registry changes take effect automatically at run time, provided you use JAXP in your XML applications.
• When you make changes to the XML Registry, it is not necessary to change your XML application code.
• Entity resolution is done locally. You can use the XML Registry either to define a local copy of an entity or to specify that WebLogic Server cache an entity from the Web for a specified duration and use the cached copy rather than the one out on the Web.

You can use the XML Registry to specify:

• An alternative server-wide XML parser instead of the built-in parser.
• An XML parser per document type.
• An alternative server-wide transformer instead of the built-in transformer.
• External entities that are to be resolved by using local copies of the entities. Once you specify these entities, 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.
• External entities to be cached by WebLogic Server after retrieval from the Web. You specify how long these external entities should be cached before WebLogic Server re-retrieves them and when WebLogic should first retrieve the entities, either at application run time or when WebLogic Server starts.

These capabilities are for use on the server side only.

How the XML Registry Works

You can create as many XML Registries as you like; however, you can associate only one XML Registry with a particular instance of WebLogic Server.

If an instance of WebLogic Server does not have an XML Registry associated with it, then the built-in parser and transformer are used when parsing or transforming documents.

Once you associate an XML Registry with an instance of WebLogic Server, all XML configuration options are available for XML applications that use that server.

You can make the following types of entries for a given XML registry:

• Configure parsers and transformers
• Configure external entity resolution

Note: The XML Registry is case sensitive. For example, if you are configuring a parser for an XML document type whose root element is <CAR>, you must enter CAR in the Root Element Tag field and not car or Car.

 

Parser Selection Within the XML Registry

The XML Registry is automatically consulted whenever you use JAXP to write your XML applications. WebLogic Server follows an ordered lookup when determining which parser class to load:

1. Use the parser defined for a particular document type.
2. Use the alternative server-wide parser defined in the XML Registry associated with the WebLogic Server instance.
3. Use the built-in Xerces parser.

The process is also true for transformers, except for the first step, because you cannot define a transformer for a particular 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. The parser being used and the location of the external entity is controlled by the XML Registry.

Note: If you elect to use an API provided by a parser instead of JAXP, the XML Registry has no effect on the processing of XML documents. For this reason, it is highly recommended that you always use JAXP in your XML applications.

 

---

XML Parser and Transformer Configuration Tasks

By default, WebLogic Server is configured to use the built-in parser and transformer to parse and transform XML documents. In release 8.1, the built-in XML parser is one based on Apache Xerces (package name weblogic.apache.xerces.*) and the built-in transformer is the Apache Xalan included in the JDK 1.4.1 (package name org.apache.xalan.*). As long as you use the default, you do not have to perform any configuration tasks for your XML applications. If you want to use a parser or transformer other than the built-in, you must use the XML Registry to configure them, as described in the following sections.

Configuring a Parser or Transformer Other Than the Built-In

The following procedure first describes how to create an XML registry that defines SAX and DOM parsers and transformers. It then describes how to associate the new XML Registry with an instance of WebLogic Server so that the server starts to use the new parsers and transformer.

Warning: In version 8.1 of WebLogic Server, you can plug in only the following versions of the Apache Xerces parser:

• Xerces 1.2.2
• Xerces 1.2.3
• Xerces 1.3.0
• Xerces 1.3.1
• Xerces 1.4.0
• Xerces 1.4.1
• Xerces 1.4.2
• Xerces 1.4.3
• Xerces 1.4.4

In addition, you can plug in only those versions of the Apache Xalan transformer that are compatible with the preceding versions of the Apache Xerces parser.

1. Start the WebLogic Administration Server and invoke the Administration Console in your browser. See Overview of Administering WebLogic Server XML for information on invoking the Administration Console.
2. Follow the steps outlined in Configuring a Parser or Transformer Other Than the Built-In of the Administration Console Online Help.

Configuring a Parser for a Particular Document Type

When you configure a parser for a particular document type, you can use the document's system id, public id, or root element tag to identify the document type.

Warning: WebLogic Server searches only the first 1000 bytes of an XML document when attempting to identify its document type. If it does not find a DOCTYPE identifier in those first 1000 bytes, it stops searching the document and uses the parser configured for the WebLogic Server instance to parse the document.

Note: The following procedure assumes that you are going to create a new XML registry, add the necessary parser registry entries, and associate it with a server.

To configure a parser for a particular document type, follow these steps:

1. Start the WebLogic Administration Server and invoke the Administration Console in your browser.

   See Overview of Administering WebLogic Server XML for information on invoking the Administration Console.

2. Follow the steps outlined in Configuring a Parser for a Particular Document Type of the Administration Console Online Help.

 

---

External Entity Configuration Tasks

Use the XML Registry to configure external entity resolution and to configure and monitor the external entity cache.

Configuring External Entity Resolution

You can configure external entity resolution with WebLogic Server in the following two ways:

• Physically copy the entity files to a directory accessible by WebLogic Administration Server and specify that the Administration Server use the local copy whenever the external entity is referenced in an XML document.
• Specify that a Managed Server cache external entities that are referenced with a URL or a pathname relative to the Administration Server, either at server-startup or when the entity is first referenced.

Caching the external entity in a Managed Server saves the remote access time and provides a local backup in the event that the Administration Server cannot be accessed while an XML document is being parsed, due to the network or the Administration Server being down.

You can configure the expiration date for a cached entity, at which point WebLogic Server re-retrieves the entity from the URL or Administration Server and re-caches it.

Note: In the following procedure it is assumed that you are going to create a new XML registry, add the necessary external entity resolution registry entries, and associate it with a server.

To configure external entity resolution, perform the following steps:

1. Start the WebLogic Administration Server and invoke the Administration Console in your browser.

   See Overview of Administering WebLogic Server XML for information on invoking the Administration Console.

2. Follow the steps outlined in Configuring External Entity Resolution of the Adminsitration Console Online Help.

Configuring the External Entity Cache

You can configure the following properties of the external entity cache:

• Size, in KB, of the cache memory. The default value for this property is 500 KB.
• Size, in MB, of the persistent disk cache. The default value for this property is 5 MB.
• Number of seconds after which external entities in the cache become stale after they have been cached by WebLogic Server. This is the default value for the entire server - you can override this value for specific external entities when you configure the entity. The default value for this property is 120 seconds (2 minutes).

To configure the external entity cache, follow these steps:

1. Start the WebLogic Administration Server and invoke the Administration Console in your browser.

   See Overview of Administering WebLogic Server XML for information on invoking the Administration Console.

2. Follow the steps outlined in Configuring the External Entity Cache in the Administration Online Help.

Monitoring the External Entity Cache

A set of statistics that describes the external entity cache is available for you to use to monitor the effectiveness of the cache. These statistics describe:

• The current state of the cache.
• The cumulative activity for the current session.
• The cumulative activity since the cache was created, typically when WebLogic Server started.

To monitor the external entity cache, follow these steps:

1. Start the WebLogic Administration Server and invoke the Administration Console in your browser.

   See Overview of Administering WebLogic Server XML for information on invoking the Administration Console.

2. Follow the steps outlined in Monitoring the External Entity Cache in the Administration Console Online Help.