Enterprise Application Deployment Descriptor Elements

Enterprise Application Deployment Descriptor Elements

application.xml

The application.xml file is the deployment descriptor for an Enterprise application. The file is located in the META-INF subdirectory of the application archive. It must begin with the following DOCTYPE declaration:
<!DOCTYPE application PUBLIC "-//Sun Microsystems, Inc.//DTD J2EE Application 1.3//EN" http://java.sun.com/dtd/application_1_3.dtd>

application

The application element is the root element of the application deployment descriptor.

Element

Required
Optional

Description
<icon> Optional Specifies the locations of small and large images that represent the application in a GUI tool. Not currently used by WebLogic Server.
<display-name> Required Specifies the application display name, a short name that is intended to be displayed by GUI tools.
<description> Optional Provides descriptive text about the application.
<module> Required application.xml contains one module element for each module within the Enterprise application. Each module element contains an ejb, java, or web element that indicates the module type and location of the module within the application. An optional alt-dd element specifies a URI to the post-assembly version of the deployment descriptor.
<security-role> Required Contains the definition of a security role which is global to the application. Each security-role element contains an optional description element, and a role-name element.

icon

Element

Required
Optional

Description
<small-icon> Optional Specifies the location for a small (16x16 pixel) .gif or .jpg image used to represent the application in a GUI tool. Currently, this is not used by WebLogic Server.
<large-icon> Optional Specifies the location for a large (32x32 pixel) .gif or .jpg image used to represent the application in a GUI tool. Currently, this element is not used by WebLogic Server.

module
Element

Required
Optional

Description
<alt-dd> Optional Specifies an optional URI to the post-assembly version of the deployment descriptor file for a particular J2EE module. The URI must specify the full pathname of the deployment descriptor file relative to the application's root directory. If you do not specify alt-dd, the deployer must read the deployment descriptor from the default location and file name required by the respective module specification. You can specify an alternate deployment descriptor only for the J2EE deployment descriptors, web.xml and ejb-jar.xml. You cannot specify alternate descriptor files for the weblogic.xml or weblogic-ejb-jar.xml.
<connector> Required Specifies the URI of a resource adapter (connector) archive file, relative to the top level of the application package.
<ejb>
Required
Defines an EJB module in the application file. Contains the path to an EJB JAR file in the application.
Example:
<ejb>petStore_EJB.jar</ejb> 
<java>
Required
Defines a client application module in the application file.
Example:
<java>client_app.jar</java> 
<web>
Required
Defines a Web application module in the application.xml file. The web element contains a web-uri element and a context-root element. If you do not declare a value for the context-root, then the basename of the web-uri element is used as the context path of the Web application. (Note that the context path must be unique in a given Web server. More than one Web application may be using the same Web server, so avoid context path clashes across multiple applications.)
web-uri Defines the location of a Web module in the application.xml file. This is the name of the WAR file.
context-root Specifies a context root for the Web application.
Example:
<web>
      <web-uri>petStore.war</web-uri>
      <context-root>estore</context-root>
</web>
security-role
Element

Required
Optional

Description
<description> Optional Text description of the security role.
<role-name>
Optional
Defines the name of a security role or principal that is used for authorization within the application. Roles are mapped to WebLogic Server users or groups in weblogic-application.xml.
 
<security-role> 
    <description>Gold customer role</description> 
    <role-name>gold_customer</role-name>
</security-role>
<security-role>
    <description>Tin customer role</description>
    <role-name>tin_customer</role-name>
</security-role>
weblogic-application.xml

The weblogic-application.xml file is the BEA WebLogic Server-specific deployment descriptor extension for application.xml from Sun Microsystems. This is where you configure features such as application-scoped JDBC pools and EJB caching.
The file is located in the META-INF subdirectory of the application archive. It must begin with the following DOCTYPE declaration:

<!DOCTYPE weblogic-application PUBLIC "-//BEA Systems, Inc.//DTD WebLogic Application 8.1.0//EN" http://www.bea.com/servers/wls810/dtd/weblogic-application_2_0.dtd">

weblogic-application

The weblogic-application element is the root element of weblogic-application.xml.
Element

Required
Optional

Description
<ejb> Optional Contains information that is specific to the EJB modules that are part of a WebLogic application. Currently, one can use the ejb element to specify one or more application level caches that can be used by the application's entity beans.
<xml> Optional Contains information about parsers and entity mappings for XML processing that is specific to this application.
<jdbc-connection-pool>
Zero or more. Specifies an application-scoped JDBC connection pool.
<security> Optional Specifies security information for the application.
<application-param>
Zero or more. Used to specify un-typed parameters that affect the behavior of container instances related to the application. The parameters listed here are currently supported. Also, these parameters in weblogic-application.xml can determine the default encoding to be used for requests.

webapp.encoding.default
Can be set to a string representing an encoding supported by the JDK. If set, this defines the default encoding used to process servlet requests. This setting is ignored if webapp.encoding.usevmdefault is set to true. This value is also overridden for request streams by the input-charset element of weblogic.xml.
webapp.encoding.usevmdefault
Can be set to true or false. If true, the system property file.encoding is used to define the default encoding.

webapp.getrealpath.accept_context_path
This is a compatibility switch that may be set to true or false. If set to true, the context path of Web applications is allowed in calls to the servlet API getRealPath.
<application-param>
    <param-name>webapp.encoding.default</param-name>
    </param-value>UTF8</param-value>
</application-param>
<classloader-structure>
Optional
A classloader-structure element allows you to define the organization of classloaders for this application. The declaration represents a tree structure that represents the classloader hierarchy and associates specific modules with particular nodes. A module's classes are loaded by the classloader that its associated with this element.
<classloader-structure> 
    <module-ref>
        <module-uri>ejb1.jar</module-uri>
    </module-ref>
</classloader-structure>
<classloader-structure>
    <module-ref>
        <module-uri>ejb2.jar</module-uri>
    </module-ref>
</classloader-structure>
<listener>
Zero or more. Used to register user defined application lifecycle listeners. These are classes that extend the abstract base class weblogic.application.ApplicationLifecycleListener.
<startup>
Zero or more. Used to register user-defined startup classes.
<shutdown>
Zero or more. Used to register user defined shutdown classes.
ejb

The following table describes the elements you can define within an ejb element.
Element

Required
Optional

Description
<entity-cache>
Zero or more. The entity-cache element is used to define a named application level cache that is used to cache entity EJB instances at runtime. Individual entity beans refer to the application-level cache that they must use, referring to the cache name. There is no restriction on the number of different entity beans that may reference an individual cache.Application-level caching is used by default whenever an entity bean does not specify its own cache in the weblogic-ejb-jar.xml descriptor. Two default caches named ExclusiveCache and MultiVersionCache are used for this purpose. An application may explicitly define these default caches to specify non-default values for their settings. Note that the caching-strategy cannot be changed for the default caches. By default, a cache uses max-beans-in-cache with a value of 1000 to specify its maximum size.
Example:
<entity-cache> 
    <entity-cache-name>ExclusiveCache</entity-cache-name> 
    <max-cache-size> 
    <megabytes>50</megabytes> 
    </max-cache-size> 
</entity-cache>
<start-mbds-with-application Optional Allows you to configure the EJB container to start Message Driven Beans with the application. If set to true, the container starts MDBs as part of the application. If set to false, the container keeps MDBs in a queue and the server starts them as soon as it has started listening on the ports.
entity-cache

The following table describes the elements you can define within a entity-cache element.
Element

Required
Optional

Description
<entity-cache-name>
Specifies a unique name for an entity bean cache. The name must be unique within an ear file and may not be the empty string. Example:
<entity-cache-name>ExclusiveCache</entity-cache-name> 
<max-beans-in-cache> Optional Specifies the maximum number of entity beans that are allowed in the cache. If the limit is reached, beans may be passivated. If 0 is specified, then there is no limit. This mechanism does not take into account the actual amount of memory that different entity beans require.Default Value: 1000
<max-cache-size> Optional Used to specify a limit on the size of an entity cache in terms of memory size - expressed either in terms of bytes or megabytes. A bean provider should provide an estimate of the average size of a bean in the weblogic-ejb-jar.xml descriptor if the bean uses a cache that specifies its maximum size using the max-cache-size element. By default, a bean is assumed to have an average size of 100 bytes.bytes | megabytes - The size of an entity cache in terms of memory size, expressed in bytes or megabytes. Used in the max-cache-size element.
<caching-strategy>
Optional
Specifies the general strategy that the EJB container uses to manage entity bean instances in a particular application level cache. A cache buffers entity bean instances in memory and associates them with their primary key value.The caching-strategy element can only have one of the following values:

Exclusive - Caches a single bean instance in memory for each primary key value. This unique instance is typically locked using the EJB container's exclusive locking when it is in use, so that only one transaction can use the instance at a time.

MultiVersion - Caches multiple bean instances in memory for a given primary key value. Each instance can be used by a different transaction concurrently.

Default Value: MultiVersion
Example:
<caching-strategy>Exclusive</caching-strategy>

Element	Required Optional	Description
<icon>	Optional	Specifies the locations of small and large images that represent the application in a GUI tool. Not currently used by WebLogic Server.
<display-name>	Required	Specifies the application display name, a short name that is intended to be displayed by GUI tools.
<description>	Optional	Provides descriptive text about the application.
<module>	Required	application.xml contains one module element for each module within the Enterprise application. Each module element contains an ejb, java, or web element that indicates the module type and location of the module within the application. An optional alt-dd element specifies a URI to the post-assembly version of the deployment descriptor.
<security-role>	Required	Contains the definition of a security role which is global to the application. Each security-role element contains an optional description element, and a role-name element.

Element	Required Optional	Description
<small-icon>	Optional	Specifies the location for a small (16x16 pixel) .gif or .jpg image used to represent the application in a GUI tool. Currently, this is not used by WebLogic Server.
<large-icon>	Optional	Specifies the location for a large (32x32 pixel) .gif or .jpg image used to represent the application in a GUI tool. Currently, this element is not used by WebLogic Server.

Element	Required Optional	Description
<alt-dd>	Optional	Specifies an optional URI to the post-assembly version of the deployment descriptor file for a particular J2EE module. The URI must specify the full pathname of the deployment descriptor file relative to the application's root directory. If you do not specify alt-dd, the deployer must read the deployment descriptor from the default location and file name required by the respective module specification. You can specify an alternate deployment descriptor only for the J2EE deployment descriptors, web.xml and ejb-jar.xml. You cannot specify alternate descriptor files for the weblogic.xml or weblogic-ejb-jar.xml.
<connector>	Required	Specifies the URI of a resource adapter (connector) archive file, relative to the top level of the application package.
<ejb>	Required	Defines an EJB module in the application file. Contains the path to an EJB JAR file in the application. Example: <ejb>petStore_EJB.jar</ejb>
<java>	Required	Defines a client application module in the application file. Example: <java>client_app.jar</java>
<web>	Required	Defines a Web application module in the application.xml file. The web element contains a web-uri element and a context-root element. If you do not declare a value for the context-root, then the basename of the web-uri element is used as the context path of the Web application. (Note that the context path must be unique in a given Web server. More than one Web application may be using the same Web server, so avoid context path clashes across multiple applications.) web-uri Defines the location of a Web module in the application.xml file. This is the name of the WAR file. context-root Specifies a context root for the Web application. Example: <web> <web-uri>petStore.war</web-uri> <context-root>estore</context-root> </web>

Element	Required Optional	Description
<ejb>	Optional	Contains information that is specific to the EJB modules that are part of a WebLogic application. Currently, one can use the ejb element to specify one or more application level caches that can be used by the application's entity beans.
<xml>	Optional	Contains information about parsers and entity mappings for XML processing that is specific to this application.
<jdbc-connection-pool>		Zero or more. Specifies an application-scoped JDBC connection pool.
<security>	Optional	Specifies security information for the application.
<application-param>		Zero or more. Used to specify un-typed parameters that affect the behavior of container instances related to the application. The parameters listed here are currently supported. Also, these parameters in weblogic-application.xml can determine the default encoding to be used for requests. webapp.encoding.default Can be set to a string representing an encoding supported by the JDK. If set, this defines the default encoding used to process servlet requests. This setting is ignored if webapp.encoding.usevmdefault is set to true. This value is also overridden for request streams by the input-charset element of weblogic.xml. webapp.encoding.usevmdefault Can be set to true or false. If true, the system property file.encoding is used to define the default encoding. webapp.getrealpath.accept_context_path This is a compatibility switch that may be set to true or false. If set to true, the context path of Web applications is allowed in calls to the servlet API getRealPath. <application-param> <param-name>webapp.encoding.default</param-name> </param-value>UTF8</param-value> </application-param>
<classloader-structure>	Optional	A classloader-structure element allows you to define the organization of classloaders for this application. The declaration represents a tree structure that represents the classloader hierarchy and associates specific modules with particular nodes. A module's classes are loaded by the classloader that its associated with this element. <classloader-structure> <module-ref> <module-uri>ejb1.jar</module-uri> </module-ref> </classloader-structure> <classloader-structure> <module-ref> <module-uri>ejb2.jar</module-uri> </module-ref> </classloader-structure>
<listener>		Zero or more. Used to register user defined application lifecycle listeners. These are classes that extend the abstract base class weblogic.application.ApplicationLifecycleListener.
<startup>		Zero or more. Used to register user-defined startup classes.
<shutdown>		Zero or more. Used to register user defined shutdown classes.

Element	Required Optional	Description
<entity-cache-name>		Specifies a unique name for an entity bean cache. The name must be unique within an ear file and may not be the empty string. Example: <entity-cache-name>ExclusiveCache</entity-cache-name>
<max-beans-in-cache>	Optional	Specifies the maximum number of entity beans that are allowed in the cache. If the limit is reached, beans may be passivated. If 0 is specified, then there is no limit. This mechanism does not take into account the actual amount of memory that different entity beans require.Default Value: 1000
<max-cache-size>	Optional	Used to specify a limit on the size of an entity cache in terms of memory size - expressed either in terms of bytes or megabytes. A bean provider should provide an estimate of the average size of a bean in the weblogic-ejb-jar.xml descriptor if the bean uses a cache that specifies its maximum size using the max-cache-size element. By default, a bean is assumed to have an average size of 100 bytes.bytes \| megabytes - The size of an entity cache in terms of memory size, expressed in bytes or megabytes. Used in the max-cache-size element.
<caching-strategy>	Optional	Specifies the general strategy that the EJB container uses to manage entity bean instances in a particular application level cache. A cache buffers entity bean instances in memory and associates them with their primary key value.The caching-strategy element can only have one of the following values: Exclusive - Caches a single bean instance in memory for each primary key value. This unique instance is typically locked using the EJB container's exclusive locking when it is in use, so that only one transaction can use the instance at a time. MultiVersion - Caches multiple bean instances in memory for a given primary key value. Each instance can be used by a different transaction concurrently. Default Value: MultiVersion Example: <caching-strategy>Exclusive</caching-strategy>