Oracle® Containers for J2EE Developer's Guide 10g (10.1.3.1.0) Part Number B28952-01 |
|
|
View PDF |
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:
This section provides an overview of the OC4J-specific application deployment descriptor file.
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 false
.
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 the 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
.
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.
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.
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 application 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>
:
<property-config> <flow-control-policy> <replication-policy> <protocol> <synchronous-replication>
For descriptions of these subelements, see Oracle Containers for J2EE Configuration and Administration Guide.
Attributes:
enabled
: Whether clustering is enabled for the application. The default is true
. Setting this value at the application level overrides the value inherited from the parent application, including the default
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.
This attribute is ignored if the <database>
tag is included.
allow-collocation
: Whether to allow application state to be replicated to a group member (JVM) residing on the same host machine.
The default is true
. However, this attribute should be set to false
if multiple hosts are available.
If multiple OC4J instances are instantiated on the same machine, different listener ports must be specified for each instance in the default-web-site.xml
, jms.xml
, and rmi.xml
configuration files.
write-quota
: The number of other application group members (JVMs) to which the application state should be replicated. This attribute makes it possible to reduce overhead by limiting the number of JVMs to which state is written, similar to the islands concept used in previous OC4J releases.
The default is 1
JVM.
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. In installations where heavy request loads are expected, this value should be increase, for example to 5000
. Setting this value higher also prevents the OC4J instance from creating a replica of session data within itself if allow-colocation
is set to true
.
This attribute is ignored if the <database>
tag is included.
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/
instance
/connectors/
rarName
./oc4j-connectors.xml
.
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/
instance
/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.
A string containing an optional short description of the application.
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.
A relative/absolute path to a log file.
Attribute:
path
: The path.
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. For a description of this element, see the description of the <jazn>
element of the jazn.xml
file in the Oracle Containers for J2EE Security Guide.
Defines the filter element of JAZNUserManager
. For a description of this element, see the description of the <jazn-web-app>
element of the jazn.xml
file in the Oracle Containers for J2EE Security Guide.
<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.
Specifies either a relative or an 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.
Sets the logging configuration for the application.
Subelements:
<file> <mail> <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/
instance
/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 log
N
.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/
instance
/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.
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.
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).
Specifies the namespace (naming context) security policy for RMI clients.
Defines a resource with a specific security setting.
Attribute:
root
: The root of the part of the namespace that this rule applies to.
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>
For a description of the <jazn>
element, see the description of the <jazn>
element of the jazn.xml
file in the Oracle Containers for J2EE Security Guide
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
.
Defines the path to the principals.xml
file.
Attribute:
path
: The path (relative to the enterprise archive or absolute) to the principals file.
Contains a property as a name and 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>
The read-access policy.
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.
Defines the runtime mapping to groups and users of a role. Maps to a security ole of the same name in the assembly descriptor.
Attributes:
impliesAll
: Whether or not this mapping implies all users.
name
: The name of the role
Defines a user that the security-role mapping implies.
Attribute:
name
: The name of the user.
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.
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
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.
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.
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
.
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.
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.
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.
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