Skip navigation.
Downloads | Product Documentation | Support

Programming WebLogic XML

# XML Application Scoping

The following sections describe how to configure parsers, transformers, external entities, and the external entity cache for a particular application:

- Overview of Application Scoping
- The weblogic-application.xml File
- Configuring a Parser or Transformer for an Enterprise Application
- Configuring an External Entity for an Enterprise Application
- Configuring the External Entity Cache for an Enterprise Application

# Overview of Application Scoping

Application scoping refers to configuring resources for a particular enterprise application rather than for an entire WebLogic Server configuration. In the case of XML, these resources include parser, transformer, external entity, and external entity cache configuration. The main advantage of application scoping is that it isolates the resources for a given application to the application itself. Using application scoping, you can configure different parsers for different applications, store the DTDs for an application within the `EAR` file or exploded enterprise directory, and so on.

Another advantage of using application scoping is that by associating the resources with the EAR file, you can run this EAR file on another instance of WebLogic Server without having to configure the resources for that server.

To configure XML resources for a particular application, you add information to the `weblogic-application.xml` deployment descriptor file located in the `META-INF` directory of the `EAR` file or exploded enterprise application directory.

Note: You use the Administration Console to configure parser, transformer, and external entity resources for a WebLogic Server instance, as described in Administering WebLogic Server XML.

# The weblogic-application.xml File

The `weblogic-application.xml` file is the WebLogic Server-specific deployment descriptor for an enterprise application. It contains configuration information about the XML, JDBC, and EJB resources used by an enterprise application. The standard J2EE deployment descriptor is called `application.xml`.

The following sample `weblogic-application.xml` file shows how to configure XML resources for an enterprise application; the body of the various elements are shown in bold:

>     <weblogic-application>
>       ...
>       <xml>
>          <parser-factory>
>             <saxparser-factory>
>                weblogic.xml.babel.jaxp.SAXParserFactoryImpl
>             </saxparser-factory>
>             <document-builder-factory>
>                org.apache.xerces.jaxp.DocumentBuilderFactoryImpl
>             </document-builder-factory>
>             <transformer-factory>
>               org.apache.xalan.processor.TransformerFactoryImpl
>             </transformer-factory>
>          </parser-factory>
>          <entity-mapping>
>            <entity-mapping-name>My Mapping</entity-mapping-name>
>            <public-id>-//BEA Systems, Inc.//DTD for cars//EN</public-id>
>            <system-id>http://www.bea.com/dtds/car.dtd</system-id>
>            <entity-uri>dtds/car.dtd</entity-uri>
>          </entity-mapping>
>       </xml>
>     </weblogic-application>

The main element for configuring XML resources is `<xml>`. The following diagram describes the sub-elements of the `<xml>` element; the sections following the diagram describe each element.

Figure 3-1 Sub-Elements of the <xml> Element in weblogic-application.xml

## xml

The main element for configuring XML resources, such as parsers, transformers, external entities, and the external entity cache for an enterprise application.

## parser-factory

The parent element for specifying a particular parser or transformer for an enterprise application.

## saxparser-factory

Element that specifies the factory class to be used for SAX style parsing in this application. If this element is not specified, the default SAX parser factory specified for the WebLogic Server instance is used.

## document-builder-factory

Element that specifies the factory class to be used for DOM style parsing in this application. If this element is not specified, the default DOM parser factory specified for the WebLogic Server instance is used.

## transformer-factory

Element that specifies the factory class to be used when transforming documents using the `javax.xml.transform` packages in this application. If this element is not specified, the default XSLT transformer factory specified for the WebLogic Server instance is used.

## entity-mapping

The parent element for mapping an entity declaration in an XML file to a local copy of the entity, such as a DTD or Schema.

## entity-mapping-name

Element that specifies the name of the entity mapping declaration.

## public-id

Element that specifies the public ID of the entity, such as:

>      -//BEA Systems, Inc.//DTD for cars//EN.

## system-id

Element that specifies the system ID of the entity, such as:

>     http://www.bea.com/dtds/car.dtd

## entity-uri

Element that specifies the URI of the entity. The path is relative to the main directory of the EAR archive or the exploded directory.

For example, `dtds/car.dtd` indicates that there is a directory called `dtds` in the main EAR archive (parallel to the `META-INF` directory) and it contains a file called `car.dtd`.

## when-to-cache

Element that specifies when you should cache the external entity. Valid values are:

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

The default value is `cache-on-reference`.

## cache-timeout-interval

Element that specifies 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 main directory of the EAR archive or exploded directory if the cached copy has been in the cache for longer than this interval.

The default value for this field is 120 seconds.

# Configuring a Parser or Transformer for an Enterprise Application

You can specify that an XML application use a parser or transformer different from the built-in parser or transformer configured for WebLogic Server by updating the `weblogic-application.xml` file of the EAR file or exploded directory that contains the XML application.

To configure a parser or transformer, other than the built-in, for an enterprise application, follow these steps:

1. Use the `<parser-factory>` sub-element of the `<xml>` element to configure factory classes for both SAX and DOM style parsing and for XSLT transformations for the enterprise application, as shown in the following example:

>          <parser-factory>
>             <saxparser-factory>
>                weblogic.xml.babel.jaxp.SAXParserFactoryImpl
>             </saxparser-factory>
>             <document-builder-factory>
>                org.apache.xerces.jaxp.DocumentBuilderFactoryImpl
>             </document-builder-factory>
>             <transformer-factory>
>               org.apache.xalan.processor.TransformerFactoryImpl
>             </transformer-factory>
>          </parser-factory>

The application corresponding to this `weblogic-application.xml` file uses the `weblogic.xml.babel.jaxp.SAXParserFactoryImpl` factory class for SAX style parsing, the `org.apache.xerces.jaxp.DocumentBuilderFactoryImpl` factory class for DOM style parsing, and the `org.apache.xalan.processor.TransformerFactoryImpl` class for XSLT transformations.

1. If you want the parser or transformer classes to be local to the EAR archive, put the JAR file that contains the classes anywhere you want in the EAR file, then update the `Class-Path` variable in the `META-INF/MANIFEST.MF` file.

For example, if you put the parser or transformer classes in a JAR file called `myparser.jar` in the directory `lib/xml,` update the `MANIFEST.MF` file as shown:

>     Manifest-Version: 1.0
>     Created-By: 1.3.1_01 (Sun Microsystems Inc.)
>     Class-Path: lib/xml/myparser.jar

2. If you want to store the parser or transformer classes in a location other than the EAR archive, be sure that you update the WebLogic Server CLASSPATH variable to include the full pathname of the JAR file that contains the classes.

# Configuring an External Entity for an Enterprise Application

You can store a local copy of an external entity, such as a DTD, in the EAR archive or exploded directory rather than always retrieving it from the Web.

To configure an external entity for an enterprise application:

1. Create the directory `lib/xml/registry` under the main directory of the EAR archive.
2. Copy the external entity, such as a DTD, to the directory.
3. Update the `weblogic-application.xml` file, using the `<entity-mapping>` sub-element of the `<xml>` element to map the name of the entity to entity declarations in any XML files processed by the application, as shown in the following example:

>          <entity-mapping>
>            <entity-mapping-name>My Mapping</entity-mapping-name>
>            <public-id>-//BEA Systems, Inc.//DTD for cars//EN</public-id>
>            <system-id>http://www.bea.com/dtds/car.dtd</system-id>
>            <entity-uri>dtds/car.dtd</entity-uri>
>          </entity-mapping>

In the example, a local copy of a DTD called `car.dtd` is stored in the `lib/xml/registry/dtds` directory under the main directory of the EAR archive or exploded directory. The public ID of the entity is`-//BEA Systems, Inc.//DTD for cars//EN` and the system id is `http://www.bea.com/dtds/car.dtd`. Whenever the application is parsing an XML file and it encounters an entity declaration using either one of the IDs, it will substitute the `car.dtd` file.

Note: Specify an `<entity-mapping>` element for each entity declaration for which you want to map a local copy of the entity.

# Configuring the External Entity Cache for an Enterprise Application

You can specify that WebLogic Server cache external entities that are referenced with a URL or a pathname relative to the main directory of the EAR archive, either at server-startup or when the entity is first referenced.

Caching the external entity 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 of a cached entity, at which point WebLogic Server re-retrieves the entity from the URL or directory of the EAR and re-caches it.

Use the `<when-to-cache>` and `<cache-timeout-interval>` subelements of the `<entity-mapping>` element to configure external entity caching for an enterprise application, as shown in the following example:

>          <entity-mapping>
>            <entity-mapping-name>My Mapping</entity-mapping-name>
>            <public-id>-//BEA Systems, Inc.//DTD for cars//EN</public-id>
>            <system-id>http://www.bea.com/dtds/car.dtd</system-id>
>            <entity-uri>dtds/car.dtd</entity-uri>
>           <when-to-cache>cache-at-initialization</when-to-cache>
>            <cache-timeout-interval>300</cache-timeout-interval>
>          </entity-mapping>

In the example, the `car.dtd` is stored in the `lib/xml/registry/dtds` directory under the main directory of the EAR archive or exploded directory. WebLogic Server caches a copy of the DTD in its memory when it first starts up, and then refreshes the cached copy if it is stored for longer than 300 seconds.