Administration Console Online Help

Before you begin

Create an XML registry and associate it with your WebLogic Server instance. For details, see Create an XML registry.

External entities are chunks of text that are not literally part of an XML document, but are referenced inside the XML document. The actual text might reside anywhere - in another file on the same computer or even somewhere on the Web. While parsing a document, if the parser encounters an external entity reference, it fetches the referenced chunk of text, places the text in the XML document, then continues parsing. An example of an external entity is a DTD; rather than including the full text of the DTD in the XML document, the XML document has a reference to the DTD that is stored in a separate file.

When you configure external entity resolution with WebLogic Server, you physically copy the entity files to a directory accessible by the WebLogic Administration Server, and specify that the Administration Server use the local copy whenever the external entity is referenced in an XML document.

The procedure in this topic uses the following XML file as an example:

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

To configure an external entity resolution entry:

If you have not already done so, in the Change Center of the Administration Console, click Lock & Edit (see Use the Change Center).
In the left pane, expand Services and select XML Registries.
In the XML Registries table, click on the XML registry for which you want to create an external entity resolution entry.
In the Settings for XMLRegistryName page, select Contents > Entity Spec Entries.
Click New.
Enter the public ID used to reference the external entity in the XML document in the Public ID field. For example, in the sample XML document listed at the top of this page, the public ID is -//Oracle//DTD for cars//EN.
Enter the system ID used to reference the external entity in the XML document in the System ID field. In the sample XML document, the system ID is http://www.oracle.com/dtds/car.dtd.
If you are configuring a local copy of an external entity, ensure that the XML 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.
In the Entity URI field, enter one of 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 Entity URI 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://.
Select an option from the When To Cache list box:
1. cache-on-reference: WebLogic Server caches the external entity referenced by a URL the first time the entity is referenced in an XML document.
2. cache-at-initialization: WebLogic Server caches the entity when the server starts.
3. defer-to-registry-setting: WebLogic Server uses the default caching setting.
4. cache-never: WebLogic Server never caches the external entity.
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 period.
The default value for this field is -1, which means that the global timeout value for WebLogic Server is used.
Click OK.
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.
To activate these changes, in the Change Center of the Administration Console, click Activate Changes.
Not all changes take effect immediately—some require a restart (see Use the Change Center).

After you finish

Create an XML entity cache and associate it with your WebLogic Server instance. See Create an XML Entity Cache.

Administration Console Online Help

Configure external entity resolution