bea.com | products | dev2dev | support | askBEA

Download Docs | Site Map | Glossary
Search

Administration Console Online Help

XML

The XML Registry is a facility for configuring and administering the XML resources of an instance of WebLogic Server. XML resources in WebLogic Server include the parser used by an application to parse XML data, the transformer used by an application to transform XML data, external entity resolution, and caching of external entities.

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. In addition, you cannot configure external entity resolution to increase the performance of your XML applications.

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 configure the following two types of entries for a given XML registry:

- to configure parsers and transformers.

- to configure external entity resolution.

Tasks

Configuring a Parser or Transformer Other Than the Built-In

1. 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.

2. 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

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

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

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

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

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

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 4.

1. 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.

2. 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.

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

4. 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.

5. 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 94-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 94-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>

1. 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.

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

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

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

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

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

Configuring External Entity Resolution

When you configure external entity resolution with WebLogic Server, you 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.

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 4.

1. 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 in the right pane.

2. 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.

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

4. 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.

5. 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 94-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>

1. 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.

2. 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://.

3. 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.

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

4. 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 amount.

   The default value for this field is -1, which means that the global timeout value for WebLogic Server is used.

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

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

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

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

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

10. 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. 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.

2. Select the Services tab in the right pane.

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

4. In the Cache Memory Size field, enter the size, in KB, of the cache memory. The default value for this property is 500 KB.

5. In the Cache Disk Size field, enter the size, in MB, of the persistent disk cache. The default value for this property is 5 MB.

6. In the Cache Timeout Interval field, enter the number of seconds after which entities become stale. The default value for this property is 120 seconds.

7. 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. 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.

2. Select the Services tab in the right pane.

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

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

5. 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.