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 7.0, the built-in XML parser is Apache Xerces and the built-in transformer is 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 7.0 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. In the left pane, right-click the XML node under the Services node and select Configure a new XML Registry from the drop-down menu. The window to create a new XML registry is displayed.

   Figure 7-1 Main XML Registry Window in Administration Console

   
    

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

   For example, to use WebLogic FastParser, enter the following information:

Name: WebLogic FastParser
DocumentBuilderFactory: 
SAXParserFactory: weblogic.xml.babel.jaxp.SAXParserFactoryImpl
TransformerFactory:

Note that in the preceding example, DocumentBuilderFactory and TransformerFactory have been left blank. This means that for DOM parsing and transformation, the built-in parser and transformer are used, respectively. The WebLogic FastParser will only be used for SAX parsing.

If you want to directly specify the Apache Xerces parser and Xalan transformer, enter the following information:

Name: Apache Xerces/Xalan Registry
DocumentBuilderFactory: org.apache.xerces.jaxp.DocumentBuilderFactoryImpl
SAXParserFactory: org.apache.xerces.jaxp.SAXParserFactoryImpl
TransformerFactory: org.apache.xalan.processor.TransformerFactoryImpl

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

5. In the left pane under the Servers node, click the name of the server with which you want to associate the new XML registry.

6. In the right pane, select the Services tab.

7. Select the XML tab. The window to configure XML properties of WebLogic Server appears in the right pane.

   Figure 7-2 Window to Configure XML Properties in Administration Console

   
    

8. Select the XML registry name that you want to associate with this server in the XML Registry field and click the Apply button.

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

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. If you have already associated an existing XML registry with your server, skip to step 5.

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. In the left pane, right-click the XML node under the Services node and select Configure a new XML Registry from the drop-down menu. The window to create a new XML registry is displayed, as shown in Figure 7-1.

3. Enter a unique registry name in the Name field. If you want to configure default parsers and transformer for your server, enter the factory class names in the DocumentBuilderFactory, SaxParserFactory, and TransformerFactory fields. Otherwise, leave these fields blank.

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

5. Under the XML node in the left pane, right-click the XML Parser Select Registry Entry node under your XML registry. Select Configure a New XMLParserSelectRegistryEntry from the drop-down menu. A blank window for entering document type information appears in the right pane.

   Figure 7-3 Configuring an XML Parser Using the Administration Console

   
    

6. Enter the document type information 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.xml (see Listing 7-1), enter -//BEA Systems, Inc.//DTD for cars//EN in the Public Id field.

   2. Specify the Root Element Tag name of the document. For the car.xml example, enter CAR in the Root Element Tag field.

      If your XML document defines a namespace, be sure to enter the fully qualified root element tag, such as VEHICLES:CAR.

Listing 7-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://www.bea.com/dtds/car.dtd"> 
<CAR> 
<MAKE>Toyota</MAKE> 
<MODEL>Corrolla</MODEL> 
<YEAR>1998</YEAR> 
<ENGINE>1.5L</ENGINE> 
<HP>149</HP> 
</CAR>

7. Set the DocumentBuilderFactory or SaxParserFactory fields to the appropriate Factory parser classes.

   For example, enter weblogic.xml.babel.jaxp.SAXParserFactoryImpl in the SaxParserFactory field to specify that this document type be parsed by WebLogic FastParser.

   Note: Do not enter any information in the Parser Class Name field; this field is for backward compatibility with previous versions of WebLogic Server only.

8. Click the Create button. The XMLParserSelect registry entry is created.

9. In the left pane under the Servers node, click the name of the server with which you want to associate the new XML registry.

10. In the right pane, select the Services tab.

11. Select the XML tab. The window to configure XML properties of WebLogic Server appears in the right pane, as shown in Figure 7-2.

12. In the XML Registry field, select the XML registry name that you want to associate with this server, and click the Apply button.

13. Restart your server so the new settings take effect.

 

---

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. If you have already associated an existing XML registry with your server, skip to step 5.

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. Right-click the XML node under the Services node in the left pane and select Configure a new XML Registry from the drop-down menu. The window to create a new XML registry is displayed, as shown in Figure 7-1.

3. In the Name field, enter a unique registry name. If you want to configure default parsers and transformer for your server, enter the factory class names in the DocumentBuilderFactory, SaxParserFactory, and TransformerFactory fields. Otherwise, leave these fields blank.

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

5. Under the XMl node in the left pane, right-click the XML Entity Spec Registry Entry node under your XML registry. Select Configure a New XMLEntitySpecRegistryEntry from the drop-down menu. A blank window for entering entity resolution information appears in the right pane.

   Figure 7-4 Configuring External Entities using the Administration Console

   
    

6. Enter either the System Id or Public Id that is used to reference the external entity in the XML document. For example, for the following car.xml file, enter http://www.bea.com/dtds/car.dtd for the System Id:

Listing 7-2 car.xml File

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

7. If you are configuring a local copy of an external entity, ensure that the registries entity directory DOMAIN/xml/registries/reg_name exists, where DOMAIN refers to your domain directory and reg_name is the name of your XML Registry. If it does not exist, create it.

8. In the EntityURI field, enter one of the following two entity paths:

   1. The pathname of the copy of the entity file in the Administration Server. This pathname must be relative to the registries entity directory DOMAIN/xml/registries/reg_name.

      For example, for the car.xml file, you might enter dtds/car.dtd in the EntityURI field.

   2. A URL that points to an external entity out on the Web or an entity stored in a repository. For example, enter http://java.sun.com/j2ee/dtds/application_1_2.dtd to reference the DTD for the application.xml file used to describe J2EE Enterprise Applications or use jdbc: to reference an entity in a database.

      Use the following protocol declarations to specify an external entity: http://, file://, jdbc:, or ftp://.

9. Select one of the following options from the When To Cache list box:

   • cache-on-reference—WebLogic Server caches the external entity referenced by a URL the first time the entity is referenced in an XML document.

   • cache-at-initialization—WebLogic Server caches the entity when the server starts.

   • defer-to-registry-setting—WebLogic Server uses the default caching setting. See Configuring the External Entity Cache for information on configuring default caching settings.

   • cache-never—WebLogic Server never caches the external entity.

10. In the Cache Timeout Interval field, enter the number of seconds after which the cached external entity becomes stale, or out-of-date. WebLogic Server re-retrieves the external entity from the specified URL or pathname relative to the Administration Server if the cached copy has been in the cache for longer than this interval.

    The default value for this field is -1, which means that the global timeout value for WebLogic Server is used. See Configuring the External Entity Cache for information on configuring global cache timeout settings.

11. Click the Create button. The XMLEntitySpec registry entry is created.

12. In the left pane under the Servers node, click the name of the server with which you want to associate the new XML registry.

13. In the right pane, select the Services tab.

14. Select the XML tab. The window to configure XML properties of WebLogic Server appears in the right pane, as shown in Figure 7-2.

15. In the XML Registry field, select the XML registry name that you want to associate with this server, and click the Apply button.

16. Restart your server so the new settings take effect.

17. If you specified that a local copy of the entity be used, rather than caching the one from the Web, copy the entity file into the entity directory.

    For example, you would copy the car.dtd file to the directory DOMAIN/xml/registries/reg_name/dtds, where DOMAIN refers to your domain directory and reg_name is the name of your XML Registry.

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. Under the Servers node in the left pane, click the name of the WebLogic Server for which you want to configure the external entity cache.

3. Select the Services tab in the right pane.

4. Select the XML tab. The window to configure XML properties of WebLogic Server appears in the right pane, as shown in Figure 7-2.

5. In the Cache Memory Size field, enter the size, in KB, of the cache memory.

6. In the Cache Disk Size field, enter the size, in MB, of the persistent disk cache.

7. In the Cache Timeout Interval field, enter the number of seconds after which entities become stale.

8. Click the Apply button.

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. Under the Servers node in the left pane, click the name of the WebLogic Server for which you want to configure the external entity cache.

3. Select the Services tab in the right pane.

4. Select the XML tab. The window to configure XML properties of WebLogic Server appears in the right pane, as shown in Figure 7-2.

5. Click Monitor XML Entity Cache in the right pane.

6. Click the Current tab to view the current state of the cache, the Session tab to view the cumulative activity for the current session, and the Historical tab to view the cumulative activity since the cache was created, typically when WebLogic Server started.

The following table describes the fields when viewing the current state of the external entity cache.

Table 7-1 Current State of Cache Statistics

Field	Tab	Description
Total Current Entries	General	Returns the number of total entries in the cache.
Total Persistent Current Entries	General	Returns the number of persistent entries in the cache.
Total Transient Current Entries	General	Returns the number of transient entries in the cache.
Avg Percent Transient	General	Returns the percent of entries which are transient.
Avg Percent Persistent	General	Returns the percent of entries which are persistent.
Avg Timeout	General	Returns the average timeout value for the entries.
Min Entry Timeout	General	Returns the smallest timeout value for any current entry.
Max Entry Timeout	General	Returns the largest timeout value for any current entry.
Avg Per Entry Memory Size	Entry Resource Usage	Returns the average memory size of the current entries.
Max Entry Memory Size	Entry Resource Usage	Returns the largest memory size for any current entry.
Min Entry Memory Size	Entry Resource Usage	Returns the smallest memory size for any current entry.
Avg Per Entry Disk Size	Entry Resource Usage	Returns the average disk size of the current entries.
Memory Usage	Total Resource Usage	Returns the number of bytes used to store all memory-resident entries.
Disk Usage	Total Resource Usage	Returns the number of bytes used to store all disk resident entries.

The following table describes the fields when viewing the cumulative activity of the external entity cache.

Table 7-2 Cumulative Activity of the Cache

Method	Tab	Description
Total Current Entries	General	Returns the number of total entries in the cache.
Total Persistent Current Entries	General	Returns the number of persistent entries in the cache.
Total Transient Current Entries	General	Returns the number of transient entries in the cache.
Avg Percent Transient	General	Returns the percent of entries which are transient.
Avg Percent Persistent	General	Returns the percent of entries which are persistent.
Avg Timeout	General	Returns the average timeout value for the entries.
Min Entry Timeout	General	Returns the smallest timeout value for any current entry.
Max Entry Timeout	General	Returns the largest timeout value for any current entry.
Avg Per Entry Memory Size	Entry Resource Usage	Returns the average memory size of the current entries.
Max Entry Memory Size	Entry Resource Usage	Returns the largest memory size for any current entry.
Min Entry Memory Size	Entry Resource Usage	Returns the smallest memory size for any current entry.
Avg Per Entry Disk Size	Entry Resource Usage	Returns the average disk size of the current entries.
Total Number Of Rejections	Rejections	Returns the number of entries that have been rejected.
Total Size Of Rejections	Rejections	Returns the total size in bytes of all items rejected.
Percent Rejected	Rejections	Returns the percent of inserts that were rejected.
Total Number Of Renewals	Rejections	Returns the number of times an stale entry was renewed.