XML Application Scoping

The XML Application Scoping mechanism in WebLogic allows you to configure XML resources such as parsers, transformers, and entity resolvers on a per-application basis. This is different from the XML Registry settings that we covered earlier they apply to a server instance and all applications running on it. An application-scoped XML configuration has two major benefits:

• It allows you to configure different parsers for different applications. You can covertly change the parsers that will be used by the enterprise application simply by editing a deployment descriptor.
• It makes the resultant EAR file less dependent on the server configuration. If you do not specify an application-scoped factory, the application is at the mercy of the target server. You need to ensure that all servers that will host the enterprise application are configured identically. A scoped XML configuration defined for an application EAR removes this dependence.

To use this mechanism, you have to include an XML deployment descriptor, weblogic-application.xml, within the META-INF directory of the application EAR file, as shown in Example 18-4. You also can use this descriptor file to configure application-specific parameters, JDBC pools, security settings, EJB-wide settings, etc. For now, we focus only on the XML configuration settings.

Example 18-4. A typical weblogic-application.xml configuration

weblogic.xml.babel.jaxp.SAXParserFactoryImpl weblogic.apache.xerces.jaxp.DocumentBuilderFactoryImpl org.apache.xalan.processor.TransformerFactoryImpl My Mapping >-//OReilly & Associates//DTD WL//EN http://www.oreilly.com/dtds/wl.dtd dtds/wl.dtd cache-at-initialization 300

Example 18-4 shows how the weblogic-application.xml descriptor file allows you to set up application-scoped XML resources. The configuration is split into two parts a parser factory configuration that specifies the default parsers and transformers to use, and multiple entity mappings that associate external entities with local or remote URIs. The entity mappings also include cache settings, which are analogous to the external entity resolution mappings that may be specified for an XML Registry. The easiest way to set up this configuration is to use the WebLogic Builder tool.

18.4.1 Configuring Factories

The parser factory configuration is quite straightforward. If the parser-factory element declares any XML or transformer factories, these settings will be used to manufacture a parser (or transformer) whenever the application uses JAXP. If you don't specify a factory in the weblogic-application.xml descriptor file, the factory in the XML Registry will be used instead. If there is no application-scoped factory setting, nor any corresponding setting in the XML Registry targeted to the server, WebLogic will then use its built-in XML factory.

To specify an XML factory, you need to provide its fully qualified class name. You can define any of the following three subelements:

saxparser-factory

This element specifies the factory to use for generating SAX parsers. In Example 18-4, we configured the application to use the WebLogic FastParser.

document-builder-factory

This element specifies the factory to use for generating DOM parsers. In Example 18-4, we configured the application to use the default built-in DOM parser factory.

transformer-factory

This element specifies the factory to use for generating XSL transformers. In Example 18-4, we configured the application to use the default built-in XSL transformer factory.

Now any server-side component in the application that uses the JAXP interface will automatically use the factory settings declared in the weblogic-application.xml descriptor file:

SAXParserFactory spf = SAXParserFactory.newInstance( ); //Create a parser using the factory SAXParser sp = spf.newSAXParser( );

Given the XML configuration in Example 18-4, the preceding code for retrieving a SAX parser will use WebLogic's FastParser.

18.4.2 Configuring Entity Resolution

As Example 18-4 illustrates, the weblogic-application.xml descriptor may also define multiple entity-mapping elements. Each entity-mapping element specifies a name for identification purposes, and includes the following optional subelements:

public-id

This element specifies the public identifier of the external entity.

system-id

This element specifies the system identifier of the external entity.

entity-uri

This element specifies the location of a file that holds the substitution text for the external entity. The file path is relative to the root directory of the EAR. When parsing an XML document, WebLogic uses the entity-uri setting to resolve a reference to an external entity with a matching public or system identifier.

Given the configuration in Example 18-4, any request for an external entity matching the specified system or public ID will resolve to the file dtds/wl.dtd, where this path is relative to the root directory of the EAR.

Just like entity resolution mappings in an XML Registry, you can specify the cache settings for an application-scoped entity mapping:

when-to-cache

This element determines when the external entity should be cached. It can accept three valid values:

cache-on-reference

This setting ensures that WebLogic will cache this entity the first time the entity is referenced. This is the default value for the when-to-cache setting.

cache-at-initialization

This setting ensures that WebLogic will cache this entity during server initialization.

cache-never

This setting guarantees that WebLogic will never cache this entity.

cache-timeout-interval

If an item is cached, this setting determines the duration (in seconds) after which the cached entity should be considered stale. After a cached entity becomes stale, the next request for the entity causes WebLogic to retrieve it again from its location. The default value for this setting is 120 seconds.