Developing WebLogic Server Applications
Enterprise Application Deployment Descriptor Elements
The following sections describe Enterprise application deployment descriptors: application.xml
(a J2EE standard deployment descriptor) and weblogic-application.xml (a WebLogic-specific application deployment descriptor).
The weblogic-application.xml file is optional if you are not using any WebLogic Server extensions.
application.xml Deployment Descriptor Elements
The following sections describe the application.xml
file. 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. The elements within the application
element are described in the following sections.
The following table describes the elements you can define within the application
element.
Element
|
Required Optional
|
Description
|
<icon>
|
Optional
|
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.
For more information on the elements you can define within the icon element, refer to icon.
|
<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
|
The application.xml deployment descriptor contains one module element for each module within the Enterprise application. Each module element contains an connector , 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.
For more information on the elements you can define within the module element, refer to module.
|
<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.
For more information on the elements you can define within the security-role element, refer to security-role.
|
icon
The following table describes the elements you can define within an icon
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.
|
module
The following table describes the elements you can define within a module
element.
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 you must 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
The following table describes the elements you can define within a security-role
element.
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 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 8.1.0//EN"
"http://www.bea.com/servers/wls810/dtd/weblogic-application_2_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.
The following table describes the elements you can define within a weblogic-application
element.
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.
For more information on the elements you can define within the ejb element, refer to ejb.
|
<xml>
|
Optional
|
Contains information about parsers and entity mappings for XML processing that is specific to this application.
For more information on the elements you can define within the xml element, refer to xml.
|
<jdbc-connection-pool>
|
|
Deprecated
Zero or more. Specifies an application-scoped JDBC connection pool.
For more information on the elements you can define within the jdbc-connection-pool element, refer to jdbc-connection-pool.
|
<security>
|
Optional
|
Specifies security information for the application.
For more information on the elements you can define within the security element, refer to security.
|
<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 and for responses.
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 and servlet responses. 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.
The following parameter is used to affect the behavior of Web applications that are contained in this application.
Example:
<application-param>
<param-name>
webapp.encoding.default
</param-name>
<param-value>UTF8</param-value>
</application-param>
For more information on the elements you can define within the application-param element, refer to 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.
Example:
<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>
For more information on the elements you can define within the classloader-structure element, refer to 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.
For more information on the elements you can define within the listener element, refer to listener.
|
<startup>
|
|
Zero or more. Used to register user-defined startup classes.
For more information on the elements you can define within the startup element, refer to startup.
|
<shutdown>
|
|
Zero or more. Used to register user defined shutdown classes.
For more information on the elements you can define within the shutdown element, refer to shutdown.
|
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>
For more information on the elements you can define within the entity-cache element, refer to entity-cache.
|
<start-mbds-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.
|
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. 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>
|
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:
Default Value: MultiVersion
Example:
<caching-strategy>Exclusive</caching-strategy>
|
xml
The following table describes the elements you can define within an xml element.
Element
|
Required Optional
|
Description
|
<parser-factory>
|
Optional
|
The parent element used to specify a particular XML parser or transformer for an enterprise application.
For more information on the elements you can define within the parser-factory element, refer to parser-factory.
|
<entity-mapping>
|
Optional
|
Zero or More. Specifies the 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.
For more information on the elements you can define within the entity-mapping element, refer to entity-mapping.
|
parser-factory
The following table describes the elements you can define within a parser-factory element.
Element
|
Required Optional
|
Description
|
<saxparser-factory>
|
Optional
|
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
|
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
|
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
The following table describes the elements you can define within an entity-mapping element.
Element
|
Required Optional
|
Description
|
<entity-mapping-name>
|
|
Specifies the name for this entity mapping.
|
<public-id>
|
Optional
|
Specifies the public ID of the mapped entity.
|
<system-id>
|
Optional
|
Specifies the system ID of the mapped entity.
|
<entity-uri>
|
Optional
|
Specifies the entity URI 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
|
Specifies the integer value in seconds.
|
jdbc-connection-pool
The following table describes the elements you can define within a jdbc-connection-pool element.
Element
|
Required Optional
|
Description
|
<data-source-name>
|
|
Specifies the JNDI name in the application-specific JNDI tree.
|
<connection-factory>
|
|
Specifies the connection parameters that define overrides for default connection factory settings.
For more information on the elements you can define within the connection-factory element, refer to connection-factory.
|
<pool-params>
|
Optional
|
Defines parameters that affect the behavior of the pool.
For more information on the elements you can define within the pool-params element, refer to pool-params.
|
<driver-params>
|
Optional
|
Sets behavior on WebLogic Server drivers.
For more information on the elements you can define within the driver-params element, refer to driver-params.
|
connection-factory
The following table describes the elements you can define within a connection-factory element.
Element
|
Required Optional
|
Description
|
<factory-name>
|
Optional
|
Specifies the name of a JDBCDataSourceFactoryMBean in the config.xml file.
|
<connection-properties>
|
Optional
|
Specifies the connection properties for the connection factory. Elements that can be defined for the connection-properties element are:
<connection-params>
<parameter>
<param-name>foo</param-name>
<param-value>xyz</param-value>
</parameter>
|
pool-params
The following table describes the elements you can define within a pool-params element.
Element
|
Required Optional
|
Description
|
<size-params>
|
Optional
|
Defines parameters that affect the number of connections in the pool.
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.
|
<xa-params>
|
Optional
|
Defines the parameters for the XA DataSources.
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.
Note: Prepared-statement-cache-size is deprecated. Use cache-size in driver-params/prepared-statement . See driver-params for more information.
|
<xa-params> Continued...
|
Optional
|
Used in: xa-params
Example:
<xa-set-transaction-timeout>
true
</xa-set-transaction-timeout>
When the xa-set-transaction-timeout value is set to
true, the transaction manager invokes setTransactionTimeout on
the resource before calling XAResource.start. The
Transaction Manager passes the global transaction timeout
value. If this attribute is set to a value greater than 0, then this
value is used in place of the global transaction timeout.
Default value: 0
Used in: xa-params
Example:
<xa-transaction-timeout>
30
</xa-transaction-timeout>
|
<login-delay-seconds>
|
Optional
|
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
|
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
|
|
<connection-check-params>
Continued...
|
Optional
|
test-frequency-seconds—Optional. The number of seconds between database connection tests. After every test-frequency-seconds interval, unused database connections are tested using table-name. Connections that do not pass the test will be closed and reopened to re-establish a valid physical database connection. If table-name is not set, the test will not be performed.
|
<jdbcxa-debug-level>
|
Optional
|
This is an internal setting.
|
<remove-infected-connections-enabled>
|
Optional
|
Controls whether a connection is removed from the pool when the application asks for the underlying vendor connection object. Enabling this attribute has an impact on performance; it essentially disables the pooling of connections (as connections are removed from the pool and replaced with new connections).
|
driver-params
The following table describes the elements you can define within a driver-params element.
Element
|
Required Optional
|
Description
|
<statement>
|
Optional
|
Defines the driver-params statement. Contains the following optional element: profiling-enabled.
Example:
<statement>
<profiling-enabled>true</profiling-enabled>
</statement>
|
<prepared-statement
|
Optional
|
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.
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 output volume. This is a resource-consuming feature, so it is recommended that you turn it off on a production server.
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
|
|
security
The following table describes the elements you can define within a security element.
Element
|
Required Optional
|
Description
|
<realm-name>
|
Optional
|
Names a security realm to be used by the application. If none is specified, the system default realm is used
|
<security-role-assignment>
|
|
Declares a mapping between an application-wide security role and one or more WebLogic Server principals.
Example:
<security-role-assignment>
<role-name>
PayrollAdmin
</role-name>
<principal-name>
Tanya
</principal-name>
<principal-name>
Fred
</principal-name>
<principal-name>
system
</principal-name>
</security-role-assignment>
|
application-param
The following table describes the elements you can define within a application-param element.
Element
|
Required Optional
|
Description
|
<description>
|
Optional
|
Provides a description of the application parameter.
|
<param-name>
|
|
Defines the name of the application parameter.
|
<param-value>
|
|
Defines the value of the application parameter.
|
classloader-structure
The following table describes the elements you can define within a classloader-structure element.
Element
|
Required Optional
|
Description
|
<module-ref>
|
|
Zero or more. The following table describes the elements you can define within a module-ref element.
module-uri—Zero or more. Defined within the module-ref element.
|
listener
The following table describes the elements you can define within a listener element.
Element
|
Required Optional
|
Description
|
<listener-class>
|
|
Name of the user's implementation of ApplicationLifecycleListener.
|
<listener-uri>
|
Optional
|
A JAR file within the EAR that contains the implementation. If you do not specify the listener-uri, it is assumed that the class is visible to the application.
|
startup
The following table describes the elements you can define within a startup element.
Element
|
Required Optional
|
Description
|
<startup-class>
|
|
Defines the name of the class to be run when the application is being deployed.
|
<startup-uri>
|
Optional
|
Defines a JAR file within the EAR that contains the startup-class. If startup-uri is not defined, then its assumed that the class is visible to the application.
|
shutdown
The following table describes the elements you can define within a shutdown element.
Element
|
Required Optional
|
Description
|
<shutdown-class>
|
|
Defines the name of the class to be run when the application is undeployed.
|
<shutdown-uri>
|
Optional
|
Defines a JAR file within the EAR that contains the shutdown-class. If you do not define the shutdown-uri element, it is assumed that the class is visible to the application.
|