Skip navigation.
Downloads | Product Documentation | Support

Administration Console Online Help

# XML

[Attributes and Console Screen Reference for 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 Document Builder Factory, Sax Parser Factory, and Transformer Factory 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, Documen tBuilder Factory and Transformer Factory 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. 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.
- `cache-never`—WebLogic Server never caches the external entity.

2. Click the Create button. The XML Registry is created and listed under the XML node in the left pane.
3. Select the Target and Deploy tab.
4. Select the Server on which you want to deploy this XML Registry.
5. Click Apply.

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

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 Document Builder Factory, Sax Parser Factory, and Transformer Factory 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. Select the Target and Deploy tab.
5. Select the Server on which you want to deploy this XML Registry.
6. Click Apply.
7. Under the XML node in the left pane, right-click the Parser Select Entries 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.
8. 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 1-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 1-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 Document Builder Factory or Sax Parser Factory fields to the appropriate Factory parser classes.

For example, enter `weblogic.xml.babel.jaxp.SAXParserFactoryImpl` in the Sax Parser Factory 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.

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

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 Document Builder Factory, Sax Parser Factory, and Transformer Factory 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. Select the Target and Deploy tab.
5. Select the Server on which you want to deploy this XML Registry.
6. Click Apply.
7. Under the XML node in the left pane, right-click the Entity Spec Entries 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.
8. 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 1-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. 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.