Oracle® Containers for J2EE Configuration and Administration Guide
10g Release 3 (10.1.3) Part No. B14432-01 |
|
Previous |
Next |
This chapter provides detailed documentation on the XML files used to store configuration data for the OC4J server and J2EE applications and modules deployed into it.
The configuration data for an OC4J server instance and the applications and modules deployed into it is persisted in a number of XML files. Figure B-1 provides an overview of these XML files and their respective roles.
Note that schemas defining the Oracle-proprietary XML files used by OC4J can be viewed at the following link:
http://www.oracle.com/technology/oracleas/schema/index.html
Table B-1 describes the role and function for each OC4J server-level XML file as well as the global configuration files displayed in the preceding figure.
Unless otherwise indicated, all of these files are installed in the ORACLE_HOME/j2ee/home/config
directory by default.
Table B-1 Server-Level and Global Configuration Files
Table B-2 describes the role and function for the various application-level XML files displayed in the preceding figure.
Unless otherwise indicated, all of these files are installed in the ORACLE_HOME/j2ee/home/config
directory by default.
Table B-2 Application-Level Configuration Files
The OC4J configuration file, server.xml
, is located in the ORACLE_HOME/j2ee/home/config
directory. It is the starting point for configuration of the OC4J server and all J2EE applications, Web applications and Web sites enabled within the server.
Unless specifically instructed to do so in the OC4J documentation, you should not have to edit server.xml
manually, as notations are added and updated as needed by OC4J.
The server.xml
file includes references to the application descriptor of each application within the OC4J instance, either directly or indirectly. In the case of a typical J2EE application, this reference points to the extracted EAR top-level directory and, therefore, to the application.xml
file that the EAR file contains. In the case of the OC4J global application, the server.xml
file points directly to the OC4J global application descriptor.
The server.xml
file also points to other XML configuration files. For each XML file, the location can be the full path or a path relative to the location of where the server.xml
file exists. In addition, the name of the XML file can be any name, as long as the contents of the file conform to the appropriate DTD.
The <rmi-config>
element denotes the name and location of the rmi.xml
file.
The <jms-config>
element denotes the name and location of the jms.xml
file.
The <global-application>
element denotes the name and location of the global application.xml
file.
The <global-web-app-config>
element denotes the name and location of the global-web-application.xml
file.
The <web-site>
element denotes the name and location of one *-web-site.xml
file. Since you can have multiple Web sites, you can have multiple <web-site>
entries.
The server.xml
file format is described by application-server-10_1.xsd
, which can be viewed at the following link:
http://www.oracle.com/technology/oracleas/schema/index.html
Below is an example server.xml
, with <!-- comments -->
to describe the various sections:
<application-server xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://xmlns.oracle.com/oracleas/schema/ application-server-10_1.xsd" application-directory="../applications" deployment-directory="../application-deployments" connector-directory="../connectors" schema-major-version="10" schema-minor-version="0" > <!-- Shared library definitions --> <shared-library name="global.libraries" version="1.0" library-compatible="true"> <code-source path="../applib"/> <code-source path="../../../sqlj/lib"/> <code-source path="../../../lib/dsv2.jar"/> </shared-library> <shared-library name="global.tag.libraries" version="1.0" library-compatible="true"> <code-source path="../jsp/lib/taglib/standard.jar"/> </shared-library> <!-- J2EE services --> <rmi-config path="./rmi.xml" /> <sep-config path="./internal-settings.xml" /> <jms-config path="./jms.xml" /> <javacache-config path="../../../javacache/admin/javacache.xml" /> <!-- Logging --> <j2ee-logging-config path="./j2ee-logging.xml" /> <log> <file path="../log/server.log" /> </log> <java-compiler name="javac" in-process="false" encoding="ISO8859_1" extdirs="c:\sdk\jdk\jre\lib\ext" /> <!-- Default application configuration --> <global-application name="default" path="application.xml" /> <!-- Deployed application configuration --> <application name="petstore" path="../applications\petstore.ear" start="true" /> <application name="ascontrol" path="../applications\ascontrol.ear" start="true" /> <!-- Default Web application configuration file --> <global-web-app-config path="global-web-application.xml" /> <!-- Transaction Manager configuration file --> <transaction-manager-config path="transaction-manager.xml" /> <!-- Configuration files for enabled Web sites --> <web-site path="./default-web-site.xml" /> </application-server>
Required? Required; one only
Child elements:
This is the root element of the OC4J configuration file.
Table B-3 <application-server> Attributes
Name | Description |
---|---|
application-directory
|
Values: string Default: ../applications
The target directory for deployed archives. |
application-auto- deploy-directory
|
Values: string Default: n/a
The directory into which EAR files can be copied, triggering automatic deployment/redeployment of the application. |
connector-directory
|
Values: string Default: ../connectors
The target directory for standalone resource adapters. |
deployment-directory
|
Values: string Default: ../application-deployments
The directory containing the OC4J-specific deployment descriptors and generated files, such as compiled JSP classes and EJB wrapper classes. |
check-for-updates
|
Values: all|adminClientOnly|none Default: adminClientOnly
See the Oracle Containers for J2EE Deployment Guide for an explanation of supported values and the impact of each. |
localhostIsAdmin
|
Values: Boolean Default: true
If |
taskmanager-granularity | Values: int Default: 1000
The interval at which the task manager performs its duties, specified in milliseconds. The default is every second (1000 milliseconds). |
Parent element: <application-server>
Required? Optional; multiple allowed
Child elements:
Defines a J2EE application deployed into the OC4J instance. The <application>
element defining an application is added to server.xml
by OC4J at the time the application is deployed. As such, there is generally no need to manually modify this element.
Table B-4 <application> Attributes
Name | Description |
---|---|
name
|
Values: string Default: n/a
The application name; typically the same as the EAR file name without the |
path | Values: string Default: n/a
The location of the EAR file or the extracted EAR top-level directory. As such, the path indirectly points to the J2EE standard |
start
|
Values: Boolean Default: true
If |
Parent element: <shared-library>
Required? Required; multiple allowed
Specifies the path to a JAR or ZIP file included in the shared library definition.
Table B-5 <code-source> Attributes
Name | Description |
---|---|
path | Values: string Default: n/a
The path to a JAR or ZIP file included in a shared library. Paths may be absolute if outside of the You can optionally set |
Parent element: startup-class, shutdown-class
Required? Optional; one only
Child elements:
Specifies the order of execution for each startup class. Specify an integer that designates the order in which the classes are executed.
Parent element: <application-server>
Required? Required; one only
Child elements:
Specifies the OC4J global application, known as the default
application. The name
attribute defines its name; the path
attribute specifies what to use as the OC4J global application descriptor.
Table B-6 <global-application> Attributes
Name | Description |
---|---|
name
|
Values: string Default: default
The global application name. |
path
|
Values: string Default: application.xml
The filename and path for the global application descriptor file. The default descriptor is |
Parent element: <application-server>
Required? Required; one only
Child elements:
Contains the configuration for a single thread pool within the OC4J process. See "Using Thread Pools" for details. Note that the cx-*
attributes are used to configure the second thread pool if two pools are being created.
Table B-7 <global-thread-pool> Attributes
Name | Description |
---|---|
min | Values: string Default: n/a
The minimum number of threads that OC4J can simultaneously execute. |
max
|
Values: string Default: n/a
The maximum number of threads that OC4J can simultaneously execute. |
queue | Values: string Default: n/a
The maximum number of requests that can be kept in the queue. |
keep-alive
|
Values: string Default: n/a
The length of time, in milliseconds, to keep a thread alive (idle) while waiting for a new request. This timeout designates how long an idle thread remains alive. If the timeout is reached, the thread is destroyed. |
cx-max
|
Values: string Default: n/a
The minimum number of connection threads that OC4J can simultaneously execute in the second pool. |
cx-min | Values: string Default: n/a
The maximum number of connection threads that OC4J can simultaneously execute in the second pool. |
cx-queue | Values: string Default: n/a
The maximum number of requests that can be kept in the queue in the second pool. |
Parent element: <application-server>
Required? Required; one only
Child elements:
Identifies the configuration file for the OC4J global web application, which by default is the parent of all other Web applications.
The name and root directory path of the default Web application are specified in the global application descriptor, and the default Web application is bound to a Web site through the default-web-site.xml
file. In OC4J standalone, the default context path for the default Web application is "/
".
Parent element: <shared-library>
Required? Optional; multiple allowed
Identifies a shared library to be imported by a shared library defined in the enclosing <shared-library>
element. For additional information on configuring and using shared libraries, see the Oracle Containers for J2EE Developer's Guide.
Parent element: <startup-class>, <shutdown-class>
Required? Optional; multiple allowed
Child elements: <param-name>, <param-value>
Specifies initialization parameters within a <startup-class>
or <shutdown-class>
element. Contains key-value pairs, of type String
, which OC4J takes, which are provided within the input Hashtable
argument. The names for the key-value pairs must be unique, as JNDI is used to bind each value to its name.
Parent element: <application-server>
Required? Optional; only one allowed
Child elements:
Defines the file to use as the J2EE logging configuration file.
Parent element: <application-server>
Required? Optional; one only
Child elements:
Specifies configuration parameters for the Java compiler to use to compile EJBs. By default, the javac
compiler installed with the JDK defined in the JAVA_HOME
environment variable will be used.
Table B-12 <java-compiler> Attributes
Name | Description |
---|---|
name | Values: string Default: modern|classic|javac|ojc|jikes
The name of the Java compiler to use. |
in-process | Values: Boolean Default: false
Specifies whether to run the compiler in-process or out-of-process. If set to If set to |
encoding
|
Values: string Default: ISO-8859-1
The source file encoding to use. |
bindir | Values: string Default: n/a
The absolute path to the directory containing the compiler executable. This attribute does not need to be specified to use the default |
extdir
|
Values: string Default: n/a
The compiler extension library location, if applicable. |
debug
|
Values: Boolean Default: false
Set to |
Parent element: <application-server>
Required? Optional; only one allowed
Child elements: None
Specifies the path to javacache.xml
, the Java Object Cache configuration file.
Parent element: <application-server>
Required? Optional; only one allowed
Child elements:
Specifies the file to use as the OC4J JMS configuration file.
Parent element: <application-server>
Required? Optional; only one allowed
Child elements: <file>
The enclosed <file> element points to the location of the OC4J server log file.
Parent element: <application-server>
Required? Optional; only one allowed
Child elements:
Defines the file to use as the OC4J RMI configuration file.
Parent element: <application-server>
Required? Optional; multiple allowed
Child elements: <code-source>, <import-shared-library>
Declares a shared library installed within the OC4J instance. For additional information on configuring and using shared libraries, see the Oracle Containers for J2EE Developer's Guide.
Table B-16 <shared-library> Attributes
Name | Description |
---|---|
name
|
Values: string Default: required
The name of the shared library directory created within the |
version | Values: string Default: required
The version number that serves as the name of the subdirectory containing the shared library's archive files in the |
library-compatible
|
Values: Boolean Default: false
This attribute is intended for internal use only. |
Parent element: shutdown-classes
Required? Optional; multiple allowed
Child elements: execution-order, init-param
Defines a shutdown class to execute before OC4J terminates within the <startup-classes>
element.
Parent element: startup-classes
Required? Optional; multiple allowed
Child elements: execution-order, init-param
Defines a startup class to execute on OC4J initialization within the <startup-classes>
element.
Table B-18 <startup-class> Attributes
Name | Description |
---|---|
classname
|
Values: string Default: required
The name of the class that implements the |
failure-is-fatal | Values: Boolean Default: false
If |
Parent element: <application-server>
Required? Optional; only one allowed
Child elements:
Specifies the transaction manager configuration file.
Parent element: <application-server>
Required? Optional; multiple allowed
Child elements:
References the configuration file for a single Web site defined within OC4J. A <web-site> element must be created for each Web site; otherwise, the site will not be enabled within OC4J. See Chapter 13, "Managing Web Sites in OC4J" for details.
The element descriptions in this section apply to any OC4J Web site configuration file, including default-web-site.xml
.
Required? Required; one only
Child elements:
<description> <frontend> <web-app> <default-web-app> <user-web-apps> <access-log> <odl-access-log> <ssl-config>
This is the root element for a Web site configuration file.
Table B-21 Web Site Configuration File Attributes
Name | Description |
---|---|
display-name
|
Values: string Default: n/a
Optionally defines a user-friendly or informal Web site name. |
host
|
Values: string Default: n/a
Specifies the host for this Web site, as either a DNS host name or an IP address. If a server is a "multi-home" machine (having multiple IP addresses), you can use the " |
log-request-info
|
Values: Boolean Default: false
Specifies whether to write information about the incoming request into the Web site log if an error occurs. The Web site log is enabled through either the |
max-request-size
|
Values: string Default: 15000
Sets a maximum size, in bytes, for incoming HTTP requests. If a client sends a request that exceeds this maximum, it will receive a "request entity too large" error. The default maximum is 15000. |
secure
|
Values: Boolean Default: false
Specifies whether to support Secure Socket Layer (SSL) functionality. For a protocol setting of " Also note that a SSL and HTTPS features are also available through Oracle HTTP Server for communication between Oracle HTTP Server and the client. For information, see Oracle Application Server Security Guide. |
protocol
|
Values: string Default: n/a
Specifies the protocol that the Web site is using. Possible values are The " To use either an " |
port
|
Values: string Default: n/a
Specifies the port number for this Web site. Each port must have a corresponding protocol, and each protocol must have a corresponding port. In OC4J standalone, a port setting of 8888 is used by default for direct access to the OC4J listener, but you can change this as desired. In an Oracle Application Server environment, this port setting is overridden by OPMN, the Oracle Process Management and Notification system. Oracle Application Server uses port In a UNIX environment, port numbers less than |
use-keep-alive
|
Values: Boolean Default: true
Typical behavior for a servlet container is to close a connection once a request has been completed. With a |
virtual-hosts
|
Values: string Default: n/a
This optional attribute is useful for virtual sites sharing the same IP address. The value is a comma-delimited list of host names tied to this Web site. |
Specifies a perceived front-end host and port of this Web site as seen by HTTP clients. When the site is behind a load balancer or firewall, the <frontend>
specification is necessary to provide appropriate information to Web application code for functionality such as URL rewriting.
Using the host and port specified in the <frontend>
element, the back-end server running the application knows to refer to the front end, instead of to itself, in any URL rewriting. This way, subsequent requests properly come in through the front end again, instead of trying to access the back end directly.
Table B-22 describes the attributes of <frontend>
.
This element binds a particular Web module to this Web site. It specifies the name of a J2EE application archive (EAR file name minus the .ear
extension) from the server.xml
file, and the name of a Web module within the J2EE application. The Web module is defined in the J2EE application.xml
file in the application EAR file (or possibly in the orion-application.xml
file in the EAR file). The Web module is bound at the location specified by the <web-app>
element root
attribute.
Note: It is possible to deploy a WAR file by itself, instead of within an EAR file. In OC4J standalone, such Web applications are added to the OC4J default application. (In OC4J, there must always be a parent application of some sort.) See "Understanding the Application Hierarchy in OC4J" for more information.In this scenario, the Web site XML file |
Mapping to and from Web site XML files, particularly with respect to the application
and name
attributes, is shown in examples elsewhere in this document. See "Deploying a J2EE Application (EAR)" (for a typical scenario of deploying a WAR file within an EAR file) and "Deploying a Standalone Web Module (WAR)" (for the scenario of deploying a WAR file by itself to the OC4J default application).
Table B-23 describes the attributes of <web-app>
.
Table B-23 <web-app> Attributes
Name | Description |
---|---|
access-log | Values: string Default: true
Specifies whether OC4J access logging, which logs requests to the Web site, is enabled for the Web module. The default is See the descriptions of the |
application | Values: string Default: n/a
Specifies the J2EE application archive name, which is the EAR file name without the If you deploy a WAR file by itself in OC4J standalone, using the OC4J default application as the parent, then the |
load-on-startup | Values: Boolean Default: false
Optional. Specifies whether the Web module should be preloaded on application startup. Otherwise, it is loaded upon the first request for it. Supported values are |
max-inactivity-time | Values: string Default: 0
Optional. Specifies the number of minutes of inactivity after which OC4J will shut down the Web module. By default, a Web module is never shut down due to inactivity. |
name | Values: Boolean Default: n/a
Specifies the name of a Web module within the specified J2EE application, and corresponds to the
|
root
|
Values: string Default: n/a
Specifies the path to which the Web module is to be bound, which defines the context path portion of the URL used to invoke the module. For example, if the Web module http://www.example.com/catalog The Specifying a |
shared | Values: string Default: false
Allows sharing of a published Web module between Web sites, when a Web site is defined by a particular pairing of a protocol and a port. Supported values are If an HTTPS Web application is marked as shared, its session tracking strategy reverts from SSL session tracking to session tracking through cookies or URL rewriting. This could possibly make the Web application less secure but may be necessary to work around issues such as SSL session timeouts not being properly supported in some browsers. |
This element creates a reference to the default Web application bound to this Web site. When a single application is bound to the Web site - such as Application Server Control Console - specify the application within this element.
For users, this element is relevant only in an OC4J standalone environment. In an Oracle Application Server environment, the OC4J default Web application has system-level functionality but is not otherwise meaningful.
The <default-web-app>
element uses the same attributes as the <web-app>
element described immediately preceding, but note that the default setting of load-on-startup
is "true"
.
Use this element to support user directories and applications. Each user has his or her own Web module and associated web-application.xml
file. User applications are reached at /
username
/
from the server root.
Table B-24 describes the attributes of <user-web-apps>
.
Table B-24 <user-web-apps> Attributes
Name | Description |
---|---|
max-inactivity-time | Values: int Default: n/a
Optional integer attribute to specify the number of minutes of inactivity after which OC4J will shut down the Web module. By default, a Web module is never shut down due to inactivity. |
path | Specifies a path to specify the local directory of the user application, including a wildcard for the user name. The default path setting in UNIX, for example, is /home/username , where username is replaced by the particular user name.
|
Use this element to enable text-based access logging for this Web site and to specify information about the access log, including the path, file name, and what information is included. The log file is where incoming requests (each access of the Web site) are logged.
See "Configuring Text-Based Access Logging" for configuration details.
Use this element to enable ODL-based access logging for the Web site and to specify information about the access logs, including the path, and maximum values for the size of each file and the total size of all files in the log directory. The log files are where incoming requests (each access of the Web site) are logged.
See "Configuring ODL Access Logging" for configuration details.
This element specifies SSL configuration settings, if applicable. You must use it whenever you set the secure
attribute of the <web-site>
element to "true"
.
Subelement of <ssl-config>
:
<property>
Table B-25 describes the attributes of <ssl-config>
.
Table B-25 <ssl-config> Attributes
Name | Description |
---|---|
keystore | Values: string Default: n/a
A relative or absolute path to the keystore database (a binary file) used by this Web site to store certificates and keys for the user base in this installation. The path value includes the file name. A relative path is relative to the location of the Web site XML file. A keystore is a |
keystore-password
|
Values: string Default: n/a
The password required to open the keystore. |
needs-client-auth
|
Values: string Default: false
Indicates whether the entity that is a client to OC4J, such as Oracle HTTP Server, must submit a certificate for authorization so it can communicate with OC4J. Supported values are |
provider
|
Values: string Default: com.sun.net.ssl.internal.ssl.Provider
You can use this attribute to specify a provider if you are using JSSE (Java Secure Socket Extension). By default, OC4J usually employs the Sun Microsystems implementation of SSL. However, OC4J employs the Oracle SSL implementation in some cases, such as for SOAP and |
factory
|
Values: string Default: JSSE: com.evermind.ssl.JSSESSLServerSocketFactory
If you are not using JSSE, use the If you use a third-party |