A OC4J-Specific Deployment Descriptors

This appendix provides an overview of OC4J-specific orion-application.xml and orion-application-client.xml deployment descriptor files. See the other OC4J developer guides for documentation of other OC4J-specific descriptors.

The following topics are included:

• Elements in the orion-application.xml File

• Elements in the orion-application-client.xml File

Elements in the orion-application.xml File

This section provides an overview of the OC4J-specific application deployment descriptor file.

<orion-application>

The top level element of the orion-application.xml file is the <orion-application> element.

Attributes:

• autocreate-tables: Whether to automatically create database tables for CMP beans in this application. The default is true.

• autodelete-tables: Whether to automatically delete old database tables for CMP beans when redeploying in this application. The default is false.

• default-data-source: The default data source to use if other than server default. This must point to a valid data source for this application if specified.

• deployment-version: The version of OC4J that this JAR was deployed against, if it is not matching the current version then it will be redeployed. This is an internal server value; do not edit.

• treat-zero-as-null: Whether or not to treat read zero as null when representing a primary key. The default is false.

<argument>

An argument used when invoking the application client if starting it in-process; that is, if auto-start="true". This element is specific to client applications.

Attribute:

• value: The value of the argument.

<arguments>

Contains one or more<argument> elements, each containing an argument used when invoking the application client if starting it in-process; that is, if auto-start="true". This element is specific to client applications.

<client-module>

An application client module of the application. An application client is a GUI or console-based standalone client that interacts with the server.

Attributes:

• auto-start: Whether to automatically start the application in-process at OC4J server startup. The default is false. Note that if true, the user attribute must also be set to true.

• deployment-time: Indicates the time the client was deployed. Internal to OC4J; do not edit.

• path: The path- absolute or relative to the EAR file - to the application client.

• user: Set to true to run the client in-process. If auto-start is true, the attribute must also be set to true.

<cluster>

Contains the clustering configuration for an enterprise application running within an OC4J instance.

Clustering is typically enabled at the global level; however, application-level settings will override the global configuration. See Oracle Containers for J2EE Configuration and Administration Guide for a detailed overview of the OC4J clustering framework.

Subelements of <cluster>:

<javagroups-config>
<protocol>

Attributes:

• enabled: Whether clustering is enabled for the application. The default is true. Note that setting this value at the application level overrides the global value, meaning that clustering can be disabled for a specific application.

• group-name: The name to use when establishing the replication group channels. If not supplied, the application name as defined in server.xml, the OC4J server configuration file, is used by default, and new group channels are created for each enterprise application.

  If a value is specified, the application and all child applications will use the channels associated with this group name.

  Note that this attribute is ignored if the <database> tag is included.

• allow-collocation: Whether to allow application state to be replicated to a group member residing on the same host machine. The default is true.

  If multiple OC4J instances are instantiated on the same machine, different listener ports must be specified for each instance in the http-web-site, jms.xml and rmi.xml configuration files.

• write-quota: The number of other group members the application state should be replicated to. This attribute makes it possible to reduce overhead by limiting the number of nodes state is written to, similar to the "islands" concept used in previous OC4J releases. The default is 1 member.

  Note that this attribute is ignored if the <database> tag is included.

• cache-miss-delay: The length of time, in milliseconds, to wait in-process for another group member to respond with a session if the session cannot be found locally. If the session cannot be found, the request will pause for the entire length of time specified. The default is 1000 milliseconds.

  Note that this attribute is ignored if the <database> tag is included.

• replication-policy: The replication policy to apply to the cluster, which defines when replication of data occurs. See the Oracle Containers for J2EE Configuration and Administration Guide for the values for this attribute. The default is onCall.

<connectors>

Attribute:

• path: The name and path of the oc4j-connectors.xml file. If no <connectors> element is specified, then the default path is ORACLE_HOME/j2ee/home/connectors/rarName./oc4j-connectors.xml.

<data-sources>

Specifies the path and filename of the XML file defining data sources to be used by the application.

OC4J data sources exist in an XML file known as data-sources.xml. This file is installed in the j2ee/home/config/ directory with a default data source.

Attribute:

• path: The path to the data-sources.xml file. The path can be fixed or relative to the location of the orion-application.xml descriptor.

<description>

A string containing an optional short description of the application.

<ejb-module>

References an EJB JAR module within the application.

Attributes:

• path: The path (relative to the EAR or absolute) to the ejb-jar file.

• remote: Set to true to activate the EJB instances on this node or to look them up remotely from another server (remote or inside a cluster). The default is false.

<file>

A relative/absolute path to a log file.

Attribute:

• path: The path.

<group>

A group that this security-role-mapping implies. That is, all members of the specified group are included in this role.

Attribute:

• name: The name of the group.

<javagroups-config>

Contains data required to use the JavaGroups group communication protocol to replicate session state across nodes in a cluster.

Attributes:

• url: A link to a JavaGroups XML configuration file.

• property-string: A string containing the properties that define how the JavaGroups JChannel should be created.

<jazn>

Configures the Java Authentication and Authorization Service (JAAS) to use the XML-based configuration provider type.

Attributes:

• provider: Set to XML.

• location: The path to the jazn-data.xml file. For example: ./jazn-data.xml This can be an absolute path, or a path relative to the jazn.xml file, where the JAAS Provider first looks for the jazn-data.xml in the directory containing the jazn.xml file. Optional if jazn.xml file configured, otherwise required.

• persistence: Values are NONE (do not persist changes), ALL (persist changes after every modification), VM_EXIT (default - persist changes when VM exits).

• default-realm: The default realm name. For example: sample_subrealm. Optional if only one realm is configured; otherwise required.

<jazn-web-app>

Defines the filter element of JAZNUserManager.

Attributes:

• auth-method: Values are SSO, which enables Oracle Application Server Single Sign-On for HTTP clients; and DIGEST, which enables the digest authentication mechanism.

• runas-mode and doasprivileged-mode: Used to control privileges in servlets. See the Oracle Containers for J2EE Security Guide for more information on these attributes.

<jmx-mbean>

Specifies a single MBean deployed with an application that is to be registered automatically with the OC4J MBeanServer.

Subelements:

• <description>: A string containing a readable name for the MBean. This name will be displayed in the MBean browser user interface.

Attributes:

• objectname: The name to register the MBean under. The domain part of the name will be ignored even if specified; application MBeans are registered using the application's deployment name as the domain name.

  For example, if you deploy an MBean named MyMBeanA with an application named widget, supply:name=MyMBeanA as the value of this attribute. The name will then be displayed as widget:name=MyMBeanA.

• class: The MBean implementation class.

<library>

Specifies either a relative or absolute path or URL to a directory or a JAR or ZIP archive to add as a library path for this OC4J instance. Directories are scanned for archives to include at OC4J startup.

Attribute:

• path: The path.

<log>

Sets the logging configuration for the application.

Subelements:

<file>
<mail>
<odl>

<odl>

Configures Oracle Diagnostic Logging for the application. The ODL framework provides plug-in components that complement the standard Java framework to automatically integrate log data with Oracle log analysis tools. In the ODL framework, log files are formatted in XML, enabling them to be more easily parsed and reused by other Oracle Application Server and custom developed components

• maxDirectorySize: Sets the maximum size, in bytes, allowed for the log file directory. When this limit is exceeded, log files are purged, beginning with the oldest files.

• maxFileSize: The maximum size, in bytes, that an individual log file is allowed to grow to. When this limit is reached, a new log file is generated.

• path: Path and folder name of the log folder for this component. You can use an absolute path or a path relative to where the configuration XML file exists, which is normally in the j2ee/home/config directory. This denotes where the log files will reside for the feature that the XML configuration file is concerned with.

When you enable ODL logging, each message goes into its respective log file, named logN.xml, where N is a number starting at one. The first log message starts the log file, log1.xml. When the log file size maximum is reached, the second log file is opened to continue the logging, log2.xml. When the last log file is full, the first log file, log1.xml, is erased and a new file is opened for the new messages. Thus, your log files are constantly rolling over and do not encroach on your disk space.

Attributes:

• path: Path and folder name of the log folder for this area. You can use an absolute path or a path relative to where the configuration XML file exists, which is normally in the j2ee/home/config directory. This denotes where the log files will reside for the feature that the XML configuration file is concerned with. For example, modifying this element in the server.xml file denotes where the server log files are written.

• max-file-size: The maximum size in KB of each individual log file.

• max-directory-size: The maximum size of the directory in KB. The default directory size is 10 MB.

New files are created within the directory, until the maximum directory size is reached. Each log file is equal to or less than the maximum specified in the attributes.

<mail>

An e-mail address to log events to. A valid mail-session also needs to be specified if this option is used.

Attribute:

• address: The mail-address.

<mail-session>

Defines the session SMTP server host (if using SMTP).

Attributes:

• location: The location in the namespace to store the session at.

• smtp-host: The session SMTP-server host (if using SMTP).

<namespace-access>

Specifies the namespace (naming context) security policy for RMI clients.

<namespace-resource>

Defines a resource with a specific security setting.

Attribute:

• root: The root of the part of the namespace that this rule applies to.

<password-manager>

Specifies the UserManager that is used for the lookup of hidden passwords. If omitted, the current UserManager is used for authentication and authorization. For example, you can use a JAZN LDAP UserManager for the overall UserManager, but use a JAZN XML UserManager for checking hidden passwords.

To identify a UserManager, provide a <jazn> element definition within this element, as follows:

<password-manager>
	<jazn ...>
</password-manager>

<persistence>

Contains a relative (to the application root) or absolute path to a directory where application state should be stored across restarts.

Attribute:

• path: The path - relative to the EAR file or absolute - to the persistence directory. For example, ./persistence.

<principals>

Defines the path to the principals.xml file.

Attribute:

• path: The path (relative to the enterprise archive or absolute) to the principals file.

<property>

Contains a property as a name/value pair.

Attributes:

• name: The name of the parameter.

• value: The value of the parameter.

<protocol>

Defines the mechanism to use for data replication. Note that only one can be specified.

Subelements:

<multicast>
<peer>
<database>

<read-access>

The read-access policy.

<resource-provider>

Define a JMS resource provider. To add a custom <resource-provider>, add the following to your orion-application.xml file:

<resource-provider class="providerClassName" name="JNDI name"> 
  <description> description </description> 
  <property name="name" value="value" /> 
</resource-provider>

In place of the user-replaceable constructs (those in italics) in the preceding example, do the following:

• Replace the value providerClassName of the class attribute with the name of the resource-provider class.

• Replace the value JNDI name of the name attribute with a name by which to identify the resource provider. This name will be used in finding the resource provider in the application's JNDI as "java:comp/resource/name/".

• Replace the value description of the description tag with a description of the specific resource provider.

• Replace the values name and value of the corresponding attributes with the same name in any property tags that the specific resource provider needs to be given as parameters.

<security-role-mapping>

Defines the runtime mapping to groups and users of a role. Maps to a security-role of the same name in the assembly descriptor.

Attributes:

• impliesAll: Whether or not this mapping implies all users. The default is false.

• name: The name of the role

<user>

Defines a user that the security-role-mapping implies.

Attribute:

• name: The name of the user.

<user-manager>

Specifies an optional user-manager class to use. These are used to integrate existing systems and provide custom user-managers for Web applications.

Attributes:

• class: The fully qualified classname of the user-manager; for example com.evermind.sql.DataSourceUserManager or com.evermind.ejb.EJBUserManager.

• display-name: A descriptive name for the UserManager instance.

<web-module>

Identifies a Web application/module that is part of the application. Each Web application can be installed on any site and in any context on those sites (for instance http://www.myserver.com/myapp/).

Attributes:

• id: The name used to reference this Web application, for example when binding the module to a Web site

• path: The path - relative to the EAR or absolute - to the Web application.

<write-access>

The write-access policy

Elements in the orion-application-client.xml File

This file is the OC4J-specific descriptor for an application client.

<orion-application-client>

Defines an orion-application-client.xml file containing the deploy time information for a J2EE application client. It complements the application client assembly information found in application-client.xml.

<context-attribute>

Contains an attribute sent to the context. The only mandatory attribute in JNDI is the 'java.naming.factory.initial,' which is the classname of the context factory implementation.

Attributes:

• name: The name of the attribute.

• value: The value of the attribute.

<ejb-ref-mapping>

Used for the declaration of a reference to another enterprise bean's home. The ejb-ref-mapping element ties this to a JNDI-location when deploying.

Attributes:

• location: The JNDI location to look up the EJB home from, such as ejb/Payroll.

• name: The ejb-ref name. Matches the name defined in an <ejb-ref> in application-client.xml.

<env-entry-mapping>

Overrides the value of an env-entry in the assembly descriptor. It is used to keep the EAR (assembly) clean from deployment-specific values. The body is the value.

Attributes:

• name: The name of the context parameter.

<lookup-context>

Specifies an optional javax.naming.Context implementation used for retrieving the resource. This is useful when hooking up with third party modules, such as a third party JMS server for instance. Either use the context implementation supplied by the resource vendor or if none exists write an implementation which in turn negotiates with the vendor software.

Attributes:

• location: The name looked for in the foreign context when retrieving the resource.

<resource-env-ref-mapping>

Declares a reference to an external resource, such as a data source, JMS queue, mail session, or similar. The resource-env-ref-mapping ties that element to a JNDI location during deployment.

Attributes:

• location: The JNDI location to bind the resource to.

<resource-ref-mapping>

Declares a reference to an external resource such as a data source, JMS queue, mail session or similar. The resource-ref-mapping ties this to a JNDI-location when deploying.

Attributes:

• location: The JNDI location to look up the resource home from.

• name: The resource-ref name. Matches the name of a resource-ref in application-client.xml