1. Developing XML Applications for Oracle WebLogic Server
  2. XML Application Scoping

8 XML Application Scoping

This chapter describes application scoping and how to configure parsers, transformers, external entities, and the external entity cache for a particular application.

This chapter includes the following sections:

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, xpath, schema, xmlInput, xmlOutput, xmlEntity 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 WebLogic Server 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 Java EE 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>
          com.sun.org.apache.xerces.internal.jaxp.SAXParserFactoryImpl 
        </saxparser-factory>
        <document-builder-factory>
          com.sun.org.apache.xerces.internal.jaxp.DocumentBuilderFactoryImpl 
        </document-builder-factory>
        <transformer-factory>
         com.sun.org.apache.xalan.internal.xsltc.trax.TransformerFactoryImpl 
        </transformer-factory>
        <xpath-factory> 
          com.sun.org.apache.xpath.internal.jaxp.XPathFactoryImpl
        </xpath-factory
        <schema-factory>
          com.sun.org.apache.xerces.internal.jaxp.validation.XMLSchemaFactory
        </schema-factory>
        <xml-input-factory>
          com.ctc.wstx.stax.WstxInputFactory
        </xml-input-factory>
        <xml-output-factory>
          com.ctc.wstx.stax.WstxOutputFactory
        </xml-output-factory>
        <xml-event-factory>
          com.ctc.wstx.stax.WstxEventFactory
        </xml-event-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>. Figure 8-1 describes the sub-elements of the <xml> element; the sections following this figure describe each element.

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

Description of Figure 8-1 follows
Description of "Figure 8-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.

schema-factory

Element that enables applications deployed to WebLogic Server to configure and obtain a Schema object used to validate XML documents using schema. If this element is not specified, the default schema factory specified for the WebLogic Server instance is used.

xpath-factory

Element that enables applications deployed to WebLogic Server to configure and obtain a XPath object used to search XML elements. If this element is not specified, the default XPath factory specified for the WebLogic Server instance is used.

xml-input-factory

Element that enables applications deployed to WebLogic Server to configure and obtain a XMLEventReader/XMLStreamReader object used to read XML streams. If this element is not specified, the default XML input factory specified for the WebLogic Server instance is used.

xml-output-factory

Element that enables applications deployed to WebLogic Server to configure and obtain a XMLEventWriter/XMLStreamWriter object used to write XML streams. If this element is not specified, the default XML output factory specified for the WebLogic Server instance is used.

xml-event-factory

Element that enables applications deployed to WebLogic Server to configure and obtain a XMLEvent object used to parse or build XML streams. If this element is not specified, the XMLEvent 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 default 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 default, for an enterprise application, follow these steps:

Note:

The following factory types follow the same process detailed below: XPathFactory, SchemaFactory, XMLInputFactory, XMLOutputFactory and XMLEventFactory.

  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>
          com.sun.org.apache.xerces.internal.jaxp.SAXParserFactoryImpl
        </saxparser-factory>
        <document-builder-factory>
          com.sun.org.apache.xerces.internal.jaxp.DocumentBuilderFactoryImpl
        </document-builder-factory>
        <transformer-factory>
         com.sun.org.apache.xalan.internal.xsltc.trax.TransformerFactoryImpl
        </transformer-factory>
     </parser-factory>

    The application corresponding to this weblogic-application.xml file uses the com.sun.org.apache.xerces.internal.jaxp.SAXParserFactoryImpl factory class for SAX style parsing, the com.sun.org.apache.xerces.internal.jaxp.DocumentBuilderFactoryImpl factory class for DOM style parsing, and the com.sun.org.apache.xalan.internal.xsltc.trax.TransformerFactoryImpl class for XSLT transformations.

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

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