Application Deployment Descriptor Elements

The following sections describe deployment descriptors for J2EE applications on ProductName. Two deployment descriptors are required: a J2EE standard deployment descriptor named application.xml, and a WebLogic-specific application deployment descriptor named weblogic-application.xml. The weblogic-application.xml file is optional if you are not using any WebLogic Server extensions.

• application.xml Deployment Descriptor Elements

• weblogic-application.xml Deployment Descriptor Elements

 

---

application.xml Deployment Descriptor Elements

The following sections describe the application.xml file.

The application.xml file is the deployment descriptor for Enterprise Application Archives. 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">

The following diagram summarizes the structure of the application.xml deployment descriptor.

 

The following sections describe each of the elements that can appear in the file.

 

---

application

application is the root element of the application deployment descriptor. The elements within the application element are described in the following sections.

icon

Optional. The icon element specifies the locations of small and large images that represent the application in a GUI tool. This element is not currently used by WebLogic Server.

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.

display-name

The display-name element specifies the application display name, a short name that is intended to be displayed by GUI tools.

description

The optional description element provides descriptive text about the application.

module

The application.xml deployment descriptor contains one module element for each module in the Enterprise Archive file. 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 an optional URI to the post-assembly version of the deployment descriptor.

alt-dd

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 component specification.

connector

Specifies the URI of a resource adapter (connector) archive file, relative to the top level of the application package.

ejb

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

Defines a client application module in the application file.

Example:

<java>client_app.jar</java>

web

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 you must avoid having 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

The security-role element 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.

description

Optional. Text description of the security role.

role-name

Defines the name of a security role or principal that is used for authorization within the application. Roles are mapped to ProductName users or groups in the weblogic-application.xml deployment descriptor.

Example:

<security-role>
  <description>the gold customer role</description>
  <role-name>gold_customer</role-name>
</security-role>
<security-role>
  <description>the customer role</description>
  <role-name>customer</role-name>
</security-role>

 

---

weblogic-application.xml Deployment Descriptor Elements

The following sections describe the weblogic-application.xml file. The weblogic-application.xml file is the BEA WebLogic Server-specific deployment descriptor extension for the application.xml deployment descriptor 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 7.0.0//EN"

"http://www.bea.com/servers/wls700/dtd/weblogic-application_1_0.dtd;">

The following sections describe each element that can appear in the file.

 

---

weblogic-application

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

ejb

Optional. The ejb element 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.

entity-cache

One 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>

entity-cache-name

The entity-cache-name element 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. The max-beans-in-cache element specifies the maximum number of entity beans that are allowed in the cache. If the limit is reached, beans may be passivated. This mechanism does not take into account the actual amount of memory that different entity beans require. This element can be set to a value of 1 or greater.

Default Value: 1000

max-cache-size

The max-cache-size element is 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. The caching-strategy element 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>

start-mdbs-with-application

Optional. Allows you to configure the EJB container to start Message Driven BeanS (MDBS) 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.

xml

Optional. The xml element contains information about parsers and entity mappings for XML processing that is specific to this application.

parser-factory

Optional. The parser-factory element contains three elements: saxparser-factory?, document-builder-factory?, and transformer-factory?.

saxparser-factory

Optional. The saxparser-factory element allows you to set the SAXParser Factory for the XML parsing required in this application only. This element determines the factory to be used for SAX style parsing. If you do not specify the saxparser-factory element setting, the configured SAXParser Factory style in the Server XML Registry is used.

Default Value: Server XML Registry setting

document-builder-factory

Optional. The document-builder-factory element allows you to set the Document Builder Factory for the XML parsing required in this application only. This element determines the factory to be used for DOM style parsing. If you do not specify the document-builder-factory element setting, the configured DOM style in the Server XML Registry is used.

Default Value: Server XML Registry setting

transformer-factory

Optional. The transformer-factory element allows you to set the Transformer Engine for the style sheet processing required in this application only. If you do not specify a value for this element, the value configured in the Server XML Registry is used.

Default value: Server XML Registry setting.

entity-mapping

Zero or more. The entity-mapping element is used to specify entity mapping. This mapping determines the alternative entity URI for a given public or system ID. The default place to look for this entity URI is the lib/xml/registry directory.

entity-mapping-name

The entity-mapping-name element specifies the name for this entity mapping.

public-id

Optional. The public-id element specifies the public ID of the mapped entity.

system-id

Optional. The system-id element specifies the system ID of the mapped entity.

entity-uri

Optional. The entity-uri element specifies the entityuri for the mapped entity.

when-to-cache

Optional. Legal values are:

• cache-on-reference

• cache-at-initialization

• cache-never

The default value is cache-on-reference.

cache-timeout-interval

Optional. The cache-timeout-interval element allows you to specify the integer value in seconds.

jdbc-connection-pool

Zero or more. The jdbc-connection-pool element specifies an application-scoped JDBC connection pool.

data-source-name

The data-source-name element specifies the JNDI name in the application-specific JNDI tree.

connection-factory

The connection-factory element defines the number of physical database connections to create when the pool is initialized. The default value is 1.

factory-name

The factory-name element specifies the name of a JDBCDataSourceFactoryMBean in the config.xml file.

connection-properties

Optional. The connection-properties element specifies the connection parameters that define overrides for default connection factory settings.

• user-name—Optional. The user-name element is used to override UserName in the JDBCDataSourceFactoryMBean.

• url—Optional. The url element is used to override URL in the JDBCDataSourceFactoryMBean.

• driver-class-name—Optional. The driver-class-name element is used to override DriverName in the JDBCDataSourceFactoryMBean.

• connection-params—Zero or more.

  • parameter+ (param-value, param-name)—One or more

pool-params

Optional. The pool-params element defines parameters that affect the behavior of the pool.

size-params

Optional. The size-params element defines parameters that affect the number of connections in the pool.

• initial-capacity—Optional. The initial-capacity element defines the number of physical database connections to create when the pool is initialized. The default value is 1.

• max-capacity—Optional. The max-capacity element defines the maximum number of physical database connections that this pool can contain. Note that the JDBC Driver may impose further limits on this value. The default value is 1.

• capacity-increment—Optional. The capacity-increment element defines the increment by which the pool capacity is expanded. When there are no more available physical connections to service requests, the pool creates this number of additional physical database connections and adds them to the pool. The pool ensures that it does not exceed the maximum number of physical connections as set by max-capacity. The default value is 1.

• shrinking-enabled—Optional. The shrinking-enabled element indicates whether or not the pool can shrink back to its initial-capacity when connections are detected to not be in use.

• shrink-period-minutes—Optional. The shrink-period-minutes element defines the number of minutes to wait before shrinking a connection pool that has incrementally increased to meet demand. The shrinking-enabled element must be set to true for shrinking to take place.

xa-params

Optional. The xa-params element defines the parameters for the XA DataSources.

• debug-level—Optional. Integer. The debug-level element defines the debugging level for XA operations. The default value is 0.

• keep-conn-until-tx-complete-enabled—Optional. Boolean. If you set the keep-conn-until-tx-complete-enabled element to true, the XA connection pool associates the same XA connection with the distributed transaction until the transaction completes.

• end-only-once-enabled—Optional. Boolean. If you set the end-only-once-enabled element to true, the XAResource.end() method is only called once for each pending XAResource.start() method.

• recover-only-once-enabled—Optional. Boolean. If you set the recover-only-once-enabled element to true, recover is only called one time on a resource.

• tx-context-on-close-needed—Optional. Set the tx-context-on-close-needed element to true if the XA driver requires a distributed transaction context when closing various JDBC objects (for example, result sets, statements, connections, and so on). If set to true, the SQL exceptions that are thrown while closing the JDBC objects in no transaction context are swallowed.

• new-conn-for-commit-enabled—Optional. Boolean. If you set the new-conn-for-commit-enabled element to true, a dedicated XA connection is used for commit/rollback processing of a particular distributed transaction.

• prepared-statement-cache-size—Optional. Use the prepared-statement-cache-size element to set the size of the prepared statement cache. The size of the cache is a number of prepared statements created from a particular connection and stored in the cache for further use. Setting the size of the prepared statement cache to 0 turns it off.

• keep-logical-conn-open-on-release—Optional. Boolean. Set the keep-logical-conn-open-on-release element to true, to keep the logical JDBC connection open when the physical XA connection is returned to the XA connection pool. The default value is false.

• local-transaction-supported—Optional. Boolean. Set the local-transaction-supported to true if the XA driver supports SQL with no global transaction; otherwise, set it to false. The default value is false.

• resource-health-monitoring-enabled—Optional. Set the resource-health-monitoring-enabled element to true to enable JTA resource health monitoring for this connection pool.

login-delay-seconds

Optional. Integer value. The login-delay-seconds element sets the number of seconds to delay before creating each physical database connection. Some database servers cannot handle multiple requests for connections in rapid succession. This property allows you to build in a small delay to let the database server catch up. This delay occurs both during initial pool creation and during the lifetime of the pool whenever a physical database connection is created.

leak-profiling-enabled

Optional. The leak-profiling-enabled element enables JDBC connection leak profiling. A connection leak occurs when a connection from the pool is not closed explicitly by calling the close() method on that connection. When connection leak profiling is active, the pool stores the stack trace at the time the connection object is allocated from the pool and given to the client. When a connection leak is detected (when the connection object is garbage collected), this stack trace is reported.

This element uses extra resources and will likely slowdown connection pool operations, so it is not recommended for production use.

connection-check-params

Optional. The connection-check-params element defines whether, when, and how connections in a pool is checked to make sure they are still alive.

• table-name—Optional. The table-name element defines a table in the schema that can be queried.

• check-on-reserve-enabled—Optional. If the check-on-reserve-enabled element is set to true, then the connection will be tested each time before it is handed out to a user.

• check-on-release-enabled—Optional. If the check-on-release-enabled element is set to true, then the connection will be tested each time a user returns a connection to the pool.

• refresh-minutes—Optional. If the refresh-minutes element is defined, a trigger is fired periodically (based on the number of minutes specified). This trigger checks each connection in the pool to make sure it is still valid.

driver-params

Optional. The driver-params element sets behavior on WebLogic Server drivers.

statement

Optional.

• profiling-enabled—Optional. profiling-enabled boolean. The profiling-enabled element enables the running of JDBC SQL roundtrip profiling. When enabled, SQL statement text, execution time, and other metrics are stored externally for further analysis. This is a resource-consuming feature, so it is recommended that you turn it off on a production server. The default value is false.

prepared-statement

Optional. profiling-enabled boolean. The prepared-statement element enables the running of JDBC prepared statement cache profiling. When enabled, prepared statement cache profiles are stored in external storage for further analysis. This is a resource-consuming feature, so it is recommended that you turn it off on a production server. The default value is false.

• profiling-enabled—Optional.

• cache-profiling-threshold—Optional. The cache-profiling-threshold element defines a number of statement requests after which the state of the prepared statement cache is logged. This element minimizes the ouput volume. This is a resource-consuming feature, so it is recommended that you turn it off on a production server.

• cache-size—Optional. The cache-size element returns the size of the prepared statement cache. The size of the cache is a number of prepared statements created from a particular connection and stored in the cache for further use.

• parameter-logging-enabled—Optional. During SQL roundtrip profiling it is possible to store values of prepared statement parameters. The parameter-logging-enabled element enables the storing of statement parameters. This is a resource-consuming feature, so it is recommended that you turn it off on a production server.

• max-parameter-length—Optional. During SQL roundtrip profiling it is possible to store values of prepared statement parameters. The max-parameter-length element defines maximum length of the string passed as a parameter for JDBC SQL roundtrip profiling. This is a resource-consuming feature, so you should limit the length of data for a parameter to reduce the output volume.

row-prefetch-enabled

Optional

row-prefetch-size

Optional

stream-chunk-size

Optional

acl-name

Optional

application-param

Zero or more. The application-param element defines various parameters that affect container behavior. These parameters are as follows:

• webapp.encoding.usevmdefault

• webapp.encoding.default

• webapp.getrealpath.accept_context_path