Skip Headers

Oracle® Application Server Containers for J2EE Standalone User's Guide 10g Release 2 (10.1.2) Part No. B14361-02 |
| Library | Product | Contents | Index

Previous | Next |

# B Additional Information

This appendix contains complete information about the following topics:

- Description of XML File Contents

- Elements in the server.xml File

- Elements in the application.xml File

- Elements in the orion-application.xml File

- Elements in the application-client.xml File

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

- Standalone OC4J Command-Line Options and Properties

- OC4J System Properties

- Configuration and Deployment Examples

## B.1 Description of XML File Contents

OC4J uses configuration and deployment XML files. The following sections describe each of these files and their function.

### B.1.1 OC4J Configuration XML Files

This section describes the following XML files, which are necessary for OC4J configuration:

- server.xml

- http-web-site.xml

- jazn-data.xml

- principals.xml

- data-sources.xml

- jms.xml

- rmi.xml

#### B.1.1.1 server.xml

This file contains the configuration for the application server. The `server.xml` file is the root configuration file—it contains references to other configuration files. In this file, specify the following:

- Library path, which is located in the application deployment descriptor

- Global application, global Web application, and default Web site served

- Maximum number of HTTP connections the server allows

- Logging settings

- Java compiler settings

- Transaction time-out

- SMTP host

- Location of the `data-sources.xml` configuration

- Location of the configuration for JMS and RMI

- Location of the default and additional Web sites

  Specify these locations by adding entries that list the location of the Web site configuration files. You can have multiple Web sites. The `http-web-site.xml` file defines a default Web site; therefore, there is only one of these XML files. All other Web sites are defined in `web-site.xml` configuration files. Register each Web site within the `server.xml` file, as follows:

      <web-site path="./http-web-site.xml" />
      <web-site path="./another-web-site.xml" />

  Note: The path that is designated is relative to the `config/` directory.

- Pointers to all applications for the container to deploy and execute

  Specify the applications that run on the container in the `server.xml` file. You can have as many application directories as you want, and they do not have to be located under the OC4J installation directory.

#### B.1.1.2 http-web-site.xml

This file contains the configuration for a Web site. In the `http-web-site.xml` file, specify the following:

- Host name or IP address, virtual host settings for this site, listener ports, and security using SSL

- Default Web application for this site

- Additional Web applications for this site

- Access-log format

- Settings for user Web applications (for `/~user/ sites`)

- SSL configuration

#### B.1.1.3 jazn-data.xml

This file contains security information for the OC4J server. It defines the user and group configuration for employing the default `JAZNUserManager`.

In the `jazn-data.xml` file, specify the following:

- Username and passwords

- Name and description of users, groups, and roles

#### B.1.1.4 principals.xml

This file contains security information for the OC4J server. It defines the user and group configuration for employing the `XMLUserManager`, which is no longer the default security manager. In the `principals.xml` file, specify the following:

- Username and password for the client-admin console

- Name and description of users/groups, and real name and password for users

- Optional X.509 certificates for users

#### B.1.1.5 data-sources.xml

This file contains configuration for the data sources that are used. In addition, it contains information on how to retrieve JDBC connections. In the `data-sources.xml` file, specify the following:

- JDBC driver

- JDBC URL

- JNDI paths to which to bind the data source

- Username/password for the data source

- Database schema to use

- Inactivity time-out

- Maximum number of connections allowed to the database

  Note: Database schemas are used to make auto-generated SQL work with different database systems. OC4J contains an XML file format for specifying properties, such as type-mappings and reserved words. OC4J comes with database schemas for MS SQL Server/MS Access, Oracle, and Sybase. You can edit these or make new schemas for your DBMS.

#### B.1.1.6 jms.xml

This file contains the configuration for the OC4J Java Message Service (JMS) implementation. In the `jms.xml` file, specify the following:

- Host name or IP address, and port number to which the JMS server binds

- Settings for queues and topics to be bound in the JNDI tree

- Log settings

#### B.1.1.7 rmi.xml

This file contains configuration for the Remote Method Invocation (RMI) system. It contains the setting for the RMI listener, which provides remote access for EJBs. In the `rmi.xml` file, specify the following:

- Host name or IP address, and port number to which the RMI server binds

- Remote servers to which to communicate

- Log settings

### B.1.2 J2EE Deployment XML Files

The OC4J-specific deployment XML files contain deployment information for different components. If you do not create the OC4J-specific files, they are automatically generated when the application is deployed. You can edit OC4J-specific deployment XML files manually. OC4J uses these files to map environment entries, resources references, and security-roles to actual deployment-specific values.

This section describes the following XML files necessary for J2EE application deployment:

- The J2EE application.xml File

- The OC4J-Specific orion-application.xml File

- The J2EE ejb-jar.xml File

- The OC4J-Specific orion-ejb-jar.xml File

- The J2EE web.xml File

- The OC4J-Specific orion-web.xml File

- The J2EE application-client.xml File

- The OC4J-Specific orion-application-client.xml File

#### B.1.2.1 The J2EE application.xml File

This file identifies the Web or EJB applications that are contained within the J2EE application. See "Elements in the application.xml File" for a list of the elements.

#### B.1.2.2 The OC4J-Specific orion-application.xml File

This file configures the global application. In the `orion-application.xml` file, specify the following:

- Whether to auto-create and auto-delete tables for CMP beans

- Which default data source to use with CMP beans

- Security role mappings

- Which user manager is the default for security

- JNDI namespace-access rules (authorization)

See "Elements in the orion-application.xml File" for a list of the elements.

#### B.1.2.3 The J2EE ejb-jar.xml File

This file defines the deployment parameters for the EJBs in this JAR file. See the Sun Microsystems EJB specification for a description of these elements.

#### B.1.2.4 The OC4J-Specific orion-ejb-jar.xml File

This file is the OC4J-specific deployment descriptor for EJBs. In the `orion-ejb-jar.xml` file, specify the following:

- Time-out settings

- Transaction retry settings

- Session persistence settings

- Transaction isolation settings

- CMP mappings

- OR mappings

- Finder method specifications

- JNDI mappings

- Minimum and maximum instance pool settings

- resource reference mappings

See the appendix in the Oracle Application Server Containers for J2EE Enterprise JavaBeans Developer's Guide for description of the elements.

#### B.1.2.5 The J2EE web.xml File

This file contains deployment information about the servlets and JSPs in this application. See the Sun Microsystems specifications for a description of these elements.

#### B.1.2.6 The OC4J-Specific orion-web.xml File

This is the OC4J-specific deployment descriptor for mapping Web settings. This XML file contains the following:

- Auto-reloading (including modification-check time-interval)

- Buffering

- Charsets

- Development mode

- Directory browsing

- Document root

- Locales

- Web timeouts

- Virtual directories

- Session tracking

- JNDI mappings

- Classloading priority for Web applications

See the appendix in the Oracle Application Server Containers for J2EE Servlet Developer's Guide for description of the elements.

#### B.1.2.7 The J2EE application-client.xml File

This file contains JNDI information for accessing the server application and other client information. See "Elements in the application-client.xml File" for a list of the elements.

#### B.1.2.8 The OC4J-Specific orion-application-client.xml File

This OC4J-specific deployment file is for the client application. It contains JNDI mappings and entries for the client.

See "Elements in the orion-application-client.xml File" for a list of the elements.

## B.2 Elements in the server.xml File

The `server.xml` file is where you perform the following tasks:

- Configure OC4J

- Reference other configuration files

- Specify your J2EE application(s)

### B.2.1 Configure OC4J

Configuring the OC4J server includes defining the following elements in the `server.xml` file:

- Library path

- Global application, the global Web application, and the default Web site

- Maximum number of HTTP connections the server allows

- Logging settings

- Java compiler settings

- Transaction time-out

- SMTP host

### B.2.2 Reference Other Configuration Files

Referencing other configuration files in the `server.xml` file includes specifying the following:

- `data-sources.xml` location

- `jazn-data.xml` location

- `jms.xml` and `rmi.xml` locations

Several XML files and directories are defined in the `server.xml` file. The path to these files or directories can be relative or absolute. If relative, the path should be relative to the location of the `server.xml` file.

#### B.2.2.1 <application-server> Element Description

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

`<application-server>`

This element contains the configuration for an application server.

Attributes:

- `application-auto-deploy-directory=".../applications/auto"` —Specifies the directory from which EAR files are automatically detected and deployed by the running OC4J server. In addition, it performs the Web application binding for the default Web site.

- `auto-start-applications="true|false"—`If set to `true`, all applications defined in the `<applications>` elements are automatically started when the OC4J server is started. If set to `false`, the applications are not started unless their `auto-start` attribute is set to `true`. The default for `auto-start-applications` is `true`.

- `application-directory=".../applications"`— Specifies a directory in which to store applications (EAR files). If none is specified (the default), OC4J stores the information in `j2ee/home/applications`.

- `deployment-directory=".../application-deployments"`—Specifies the master location where applications that are contained in EAR files are deployed. The location defaults to `j2ee/home/application-deployments/`.

- `connector-directory`—The location and file name of the `oc4j-connectors.xml` file.

- `check-for-updates="true|false"`—Default in standalone OC4J is "`true`". If true, task manager checks for XML configuration file modifications. Thus, if you set to false, you can disable automatic refreshing of the configuration to any new XML modifications. Also, setting this attribute to false stops the automatic deployment of any applications until you execute `admin.jar -updateConfig`. If set to false, you cause the XML configuration to refresh from the XML files and any necessary automatic deployment to occur by using the `admin.jar` `-updateConfig` option.

- `recovery-procedure="automatic|prompt|ignore"`— Specifies how the EJB container recovers a global transaction (JTA) if an error occurs in the middle of the transaction. If a CMP bean is in the middle of a global transaction when an error occurs, then the EJB container saves the transactional state to a file. The next time OC4J is started, these attributes specify how to recover the JTA transaction.

  - `automatic` — automatically attempts recovery (the default)

  - `prompt` — prompts the user (system in/out)

    You may notice a prompt for recovery even if no CMP beans were executing. This is caused by the OC4J server asking for permission to see whether there is anything to recover.

  - `ignore` — ignores recovery (useful in development environments or if you are never executing a CMP entity bean)

- `taskmanager-granularity=``milliseconds``.` The task manager is a background process that performs cleanup. However, the task manager can be expensive. You can manage when the task manager performs its duties through this attribute, which sets how often the task manager is kicked off for cleanup. Value is in milliseconds. Default is 1000 milliseconds.

#### B.2.2.2 Elements Contained Within <application-server>

Within the `<application-server>` element, the following elements, which are listed alphabetically and not by DTD ordering, can be configured:

`<application>`

An application is a entity with its own set of users, Web applications, and EJB JAR files.

Attributes:

- `auto-start="true|false"` — Specifies whether the application should be automatically started when the OC4J server starts. The default is `true`. Setting `auto-start` to `false` is useful if you have multiple applications installed and want them to start on demand. This can improve general server startup time and resource usage.

- `deployment-directory=".../application-deployments/myapp"` — Specifies a directory to store application deployment information. If none is specified (the default), OC4J looks in the global `deployment-directory`, and if none exists there, it stores the information inside the EAR file. The path can be relative or absolute. If relative, the path should be relative to the location of the `server.xml` file.

- `name="anApplication"` — Specifies the name used to reference the application.

- `parent="anotherApplication"` — The name of the optional parent application. The default is the global application. Children see the namespace of its parent application. This is used to share services such as EJBs among multiple applications.

- `path=".../applications/myApplication.ear" />` — The path to the EAR file containing the application code. In this example, the EAR file is named `myApplication.ear`.

`<compiler>`

This element is deprecated for version 9.0.4 and forward. See the `<java-compiler>` element for the alternative. For previous releases, it specifies an alternative compiler (such as Jikes) for EJB/JSP compiling.

Attributes:

- `classpath="/my/rt.jar"` — Specifies an alternative/additional classpath when compiling. Some compilers need an additional classpath (such as Jikes, which needs the `rt.jar` file of the Java 2 VM to be included).

- `executable="jikes" />` — The name of the compiler executable to use, such as Jikes or JVC.

`<cluster>`

Cluster settings for this server.

Attribute:

- `id="123" />` — The unique cluster ID of the server.

`<execution-order>`

Defines the ordering of how the startup classes are executed. Value is an integer. OC4J loads from 0 on up. If duplicate numbers, OC4J chooses the ordering for those classes.

`<global-application>`

The default application for this server. This acts as a parent to other applications in terms of object visibility.

Attributes:

- `name="default"` — Specifies the application.

- `path=".../application.xml" />` — Specifies the path to the global `application.xml` file, which contains the settings for the default application. An `application.xml` file exists for each application as the standard J2EE application descriptor file, which is different than this file. This `application.xml` may have the same name, but it exists to provide global settings for all J2EE applications.

`<global-thread-pool>`

You can specify unbounded, one, or two thread pools for an OC4J process through this element. If you do not specify this element, then an infinite number of threads can be created. See "Thread Pool Settings" for a full description.

Attributes:

- `min` —The minimum number of threads that OC4J can simultaneously execute. By default, a minimum number of threads are preallocated and placed in the thread pool when the container starts. Value is an integer. The default is 20. The minimum value you can set this to is 10.

- `max` —The maximum number of threads that OC4J can simultaneously execute. New threads are spawned if the maximum size is not reached and if there are no idle threads. Idle threads are used first before a new thread is spawned. Value is an integer. The default is 40.

- `queue` —The maximum number of requests that can be kept in the queue. Value is an integer. The default is 80.

- `keepAlive` —The number of 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. The minimum time is a minute. Time is set in milliseconds. To never destroy threads, set this timeout to a negative one.

  Value is a long. The default is 600000 milliseconds.

- `cx-min` —The minimum number of connection threads that OC4J can simultaneously execute. Value is an integer. The default is 20. The minimum value you can set this to is 10.

- `cx-max` —The maximum number of connection threads that OC4J can simultaneously execute. Value is an integer. The default is 40.

- `cx-queue` —The maximum number of connection requests that can be kept in the queue. Value is an integer. The default is 80.

- `cx-keepAlive` —The number of milliseconds to keep a connection 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. The minimum time is a minute. Time is set in milliseconds. To never destroy threads, set this timeout to a negative one.

  Value is a long. The default is 600000 milliseconds.

- `debug` —If true, print the application server thread pool information at startup. The default is false.

`<global-web-app-config>`

Attributes:

- `path`— The path where the `web-application.xml` file is located.

      path=".../web-application.xml" />

`<init-library>`

Attributes:

- `path`— The path in which the startup and shutdown classes are located. The path indicates the directory in which the class resides or the directory and JAR filename of the JAR where the class is archived. If more than one directory or JAR file exists, then supply an `<init-library>` element for each directory and JAR filename.

      <init-library path="../xxx">

`<init-param>`

Attributes:

- Defines the key-value pairs of the parameters to pass into the startup class.

`<javacache-config>`

Attributes:

- `path`—Specifies the path to the `javacache.xml` file.

      <javacache-config path="../../../javacache/admin/javacache.xml" />

`<java-compiler>`

You can specify an alternative compiler—either in or out of process—for your JSP and EJB compilation. The default compiler is an out of process `javac` compiler found in the JDK `bin` directory.

Attributes:

- `name`—Specify the name of the compiler to use. Valid compiler names are as follows:

  - for in-process compilers—`modern`, `classic`, `javac` or `ojc`

  - for out-of-process compilers (forked)—`modern`, `javac`, `ojc`, or `jikes`

    These names are defined as follows:

    - `javac`—the standard compiler name for all JDKs.

    - `classic`—the standard compiler of JDK 1.1/1.2.

    - `modern`—the standard compiler of JDK 1.3/1.4.

    - `jikes`—the Jikes compiler.

    - `ojc`—The Oracle Java compiler.

- `in-process`—If true, the compiler is to run in process. If false, the compiler runs out of the process. Most compilers can execute both in and out of the process. The exceptions are as follows:

  - The `classic` compiler cannot run out of the process; thus, the in-process attribute is always true.

  - The `jikes` compiler cannot run in process; thus, the in-process attribute is always false.

- `encoding`—Specify the type of character encoding for the source file, such as UTF-8, EUCJIS, or SJIS. Encoding is only supported by the `javac` compiler. The default is determined by the language version of the JVM that is installed.

- `bindir`—Provide the absolute path to the compiler directory. You do not need to specify this attribute for `javac`, `modern`, or `classic` as the JDK bin directory is searched for this compiler.

  The syntax is specific to the operating system platform:

  - Sun Microsystems Solaris example—If you are using `jikes`, which is in `/usr/local/bin/jikes`, then specify the following:

        name="jikes"
        bindir="/usr/local/bin"

  - Windows example—To specify `jikes`, which is located in `c:\jdk1.3.1\bin\jikes.exe`, specify the following:

        name="jikes"
        bindir="c:\\jdk1.3.1\\bin"

- `extdirs`—Specifies extension directories that the compilation uses to compile against. The default is your JDK extension directories. Multiple directories can be specified, each separated by a colon. Each `JAR` archive in the specified directories are searched for class files. You can specify certain directories to be searched by modifying the `-Djava.ext.dirs` system property. The `jikes` compiler requires that extension directories are specified in either this attribute or in the `-Djava.ext.dirs` system property.

The following are four examples of how to define alternate compilers in this element:

    <java-compiler name="jikes" bindir="C:\java\jikes\bin"
    	in-process="false" />
    <java-compiler name="ojc" bindir="C:\java\jdev\jdev\bin"
    	in-process="false"/>
    <java-compiler name="classic" in-process="true" />
    <java-compiler name="modern" in-process="true" />

`<jms-config>`

Attribute:

- `path`— Specifies the path to the `jms.xml` file.

      path=".../jms.xml"

`<log>`

`<file`>

Attribute:

- `path=".../log/server.log"` — Specifies a relative or absolute path to a file where log events are stored.

`<mail`>

An e-mail address where log events are forwarded. You must also specify a valid mail-session if you use this option.

Attribute:

- `address="my@mail.address"` — Specifies the mail address.

`<odl>`

The ODL log entries are each written out in XML format in its respective log file. The log files have a maximum limit. When the limit is reached, the log files are overwritten.

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 logfile is full, the first log file, `log1.xml` is erased and a new one 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.

`<max-http-connections>`

Used to define the maximum number of concurrent connections any given Web site can accept at a single point in time. If text exists inside the tag, it is used as a redirect-URL when the limit is reached.

Attributes:

- `max-connections-queue-timeout="10"` — When the maximum number of connections are reached, this is the number of seconds that can pass before the connections are dropped and a message is returned to the client stating that the server is either busy or connections will be redirected. The default is 10 seconds.

- `socket-backlog` — The number of connections to queue up before denying connections at the socket level. The default is 30.

- `value` — The maximum number of connections.

`<metric-collector>`

The `<metric-collector>` element specifies that OC4J sends a metric between 0 and 100, inclusive, to `mod_oc4j` so that `mod_oc4j` can make routing decisions to load-balance incoming requests to a list of available OC4J instances. The metric sent has a relative value only, where 0 means that the OC4J instance is very busy and 100 means that the OC4J instance is available (not busy). When configured for metric load balancing, `mod_oc4j` routes first to the OC4J instance with the greater value.

The metric sent from OC4J to `mod_oc4j` is used only when metric-based load balancing is specified for `mod_oc4j` and when OC4J runs in an Oracle Application Server environment.

If you specify metric-based load balancing in `mod_oc4j` and do not specify the `<metric-collector>` element in `server.xml`, then `mod_oc4j` expects OC4J to send metrics, but OC4J does not send metrics. In this case, `mod_oc4j` reports the following warning message:

    No run time metrics for oc4j(opmnid=%s) in notification Oc4jSelectMethod is configured to use run time metrics, please make sure OC4J side is configured accordingly. Default to 50.

In this case, `mod_oc4j` uses the value 50 for each of the OC4J processes and continues.

Likewise, if you specify the `<metric-collector>` element in `server.xml`, but do not specify metric-based load balancing in `mod_oc4j`, then OC4J sends metrics but `mod_oc4j` is not configured to receive metrics. In this case, `mod_oc4j` ignores the metrics and uses whatever the configured method is for load balancing. You specify the load balancing method with `Oc4jSelectMethod`. If no `Oc4jSelectMethod` is specified, then `mod_oc4j` uses the default, which is roundrobin.

The `<metric-collector>` element takes the following attribute: `classname`.

The `classname` attribute defines an interface for gathering and calculating a server-wide metric. Use `oracle.oc4j.server.DMSMetricCollector` for the `classname` attribute when using a DMS-noun-based metric collector. A DMSMetricCollector instance takes several parameters. Details for the values for these parameters are available in the Oracle Application Server 10g Performance Guide.

For example:

    <metric-collector classname="oracle.oc4j.server.DMSMetricCollector">
       <init-param>
         <param-name>
           dms-noun
         </param-name>
         <param-value>
           /oc4j/default/WEBs/processRequest.time
         </param-value>
       </init-param>
       <init-param>
         <param-name>
           history-proportion
         </param-name>
         <param-value>
           0.2
         </param-value>
       </init-param>
       <init-param>
         <param-name>
           debug
         </param-name>
         <param-value>
           false
         </param-value>
       </init-param>
    </metric-collector>

For details on using the `<metric-collector>` element and using metric-based load balancing with mod_oc4j, see the Oracle Application Server 10g Performance Guide.

`<rmi-config>`

Attribute:

- `path`— Specifies the path to the `rmi.xml` file.

      path=".../rmi.xml"

`<sep-config>`

The `<sep-config>` element in this file specifies the pathname, normally `internal-settings.xml`, for the server extension provider properties.

Attribute:

- `path`—The path of the server extension provider properties.

`<sfsb-config>`

Passivation for stateful session beans is automatically done, unless you set the `enable-passivation` attribute for this element to false. For more information on stateful session bean passivation, see the Advanced chapter in the Oracle Application Server Containers for J2EE Enterprise JavaBeans Developer's Guide.

Attribute

- `enable-passivation`—Default is true, which means that stateful session bean passivation occurs. If you have a situation where your stateful session beans are not in a state to be passivated, set this attribute to false.

`<shutdown-classes>`

Shutdown classes can be defined by the user, and are executed after undeployment, but before the core services are stopped.

`<shutdown-class>`

Each startup class is defined within the `<startup-class>` element.

Attributes:

- `classname`—The classname of the user-defined startup class.

`<startup-classes>`

Startup classes can be defined by the user, and will be executed after the core services (JMS, RMI) are started, but before applications are deployed. The shutdown classes are executed after undeployment, but before the core services are stopped.

`<startup-class>`

Each startup class is defined within the `<startup-class>` element.

Attributes:

- `classname`—The classname of the user-defined startup class.

- `failure-is-fatal`—If true, if an exception is thrown, then OC4J logs the exception and exit. If false, OC4J logs the exception and then continues. Default is false.

`<transaction-config`>

Transaction configuration for the server.

Attribute:

- `timeout="30000"` — Specifies the maximum amount of time (in milliseconds) that a transaction can take to finish before it is rolled back due to a timeout. The default value is 30000. This timeout will be a default timeout for all transactions that are started in OC4J. You can change it by using the dynamic API—`UserTransaction.setTransactionTimeout(milliseconds)`.

`<web-site>`

Attribute:

- `path`— The path to a `*web-site.xml` file that defines a Web site. For each Web site, you must specify a separate `*web-site.xml` file. This example shows that a Web site is defined in the `my-web-site.xml` file.

      path=".../my-web-site.xml"

## B.3 Elements in the application.xml File

This section provides an overview of the J2EE application deployment descriptor file.

### B.3.1 <application> Element Description

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

#### B.3.1.1 Elements Contained Within <application>

Within the `<application>` element, the following elements, which are listed alphabetically and not by DTD ordering, can be configured:

`<alt-dd>path/to/dd</alt-dd>`

The `alt-dd` element 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 alt-dd is not specified, the deployer must read the deployment descriptor from the default location and file name required by the respective component specification.

`<connector>context</connector>`

The `connector` element specifies the URI of a resource adapter archive file, relative to the top level of the aplication package.

`<context-root>thedir/</context-root>`

The `context-root` element specifies the context root of a web application.

`<description>A description.</description>`

The `description` element provides a human readable description of the application. The `description` element should include any information that the application assembler wants to provide the deployer.

`<display-name>The name.</display-name>`

The `display-name` element specifies an application name. The application name is assigned to the application by the application assembler and is used to identify the application to the deployer at deployment time.

`<ejb>pathToEJB.jar</ejb>`

The `ejb` element specifies the URI of a EJB JAR, relative to the top level of the application package.

`<icon>`

The `icon` element contains a `small-icon` and a `large-icon` element which specify the location within the application for a small and large image used to represent the application in a GUI tool.

`<java>pathToClient.jar</java>`

The `java` element specifies the URI of a Java application client module, relative to the top level of the application package.

`<large-icon>path/to/icon.gif</large-icon>`

The `large-icon` element contains the location within the application of a file containing a large (32x32 pixel) icon image. The image must be either GIF or JPEG format and the filename must end with the extension of ".`gif`" or ".`jpg`".

`<module>`

The `module` element represents a single J2EE module and contains an EJB, Java, or Web element, which indicates the module type and contains a path to the module file, and an optional `alt-dd` element, which specifies an optional URI to the post-assembly version of the deployment descriptor. The application deployment descriptor must have one module element for each J2EE module in the application package.

`<role-name>nameOfRole</role-name>`

The name of the role.

`<security-role>`

The `security-role` element contains the definition of a security role which is global to the application. The definition consists of a description of the security role, and the security role name. The descriptions at this level override those in the component level security role definitions and must be the descriptions tool display to the deployer.

`<small-icon>path/to/icon.gif</small-icon>`

The `small-icon` element contains the location within the application of a file containing a small (16x16 pixel) icon image. The image must be either GIF or JPEG format and the filename must end with the extension of ".`gif`" or ".`jpg`".

`<web>`

The `web` element contains the `web-uri` and `context-root` of a Web application module.

`<web-uri>pathTo.war</web-uri>`

The `web-uri` element specifies the URI of a web application file, relative to the top level of the application package.

## B.4 Elements in the orion-application.xml File

This section describes the OC4J-specific application deployment descriptor file.

### B.4.1 <orion-application> Element Description

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

Attributes:

- `autocreate-tables` - Whether or not to automatically create database tables for CMP beans in this application. The default is true.

- `autodelete-tables` - Whether or not 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 CMT 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's as null's when they represent primary keys. The default is false.

#### B.4.1.1 Elements Contained Within <orion-application>

Within the `<orion-application>` element, the following elements, which are listed alphabetically and not by DTD ordering, can be configured:

`<argument value="theValue" />`

An argument used when invoking the client.

Attribute:

- `value` - The value of the argument.

`<arguments>`

A list of arguments to used when invoking the application client if starting it in-process (auto-start="true").

`<client-module auto-start="true|false" deployment-time="073fc2ab513bc3ce" path="myappclient.jar" user="theUser">`

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 or not to auto-start the client (in-process) at server startup. The default is false.

- `deployment-time` - Last deploy time attribute. Internal to OC4J; do not edit.

- `path` - The path (relative to the enterprise archive or absolute) to the application-client.

- `user` - User to run the client as if run in-process (autostart="true"). Must be specified if auto-start is activated.

`<commit-coordinator>`

Configure the two-phase commit engine.

`<commit-class class="com.evermind.server.OracleTwoPhaseCommitDriver" />`

Attribute:

- `class` - Configures the `OracleTwoPhaseCommitDriver` class for two-phase commit engines.

`<connectors path="./oc4j-connectors.xml" />`

Attribute:

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

`<data-sources path="./data-sources.xml" />`

Attribute:

- `path` - The path.

`<description>A short description</description>`

A short description of this component.

`<ejb-module path="myEjbs.jar" remote="true|false" />`

An EJB JAR module of the application.

Attributes:

- `path` - The path (relative to the enterprise archive or absolute) to the ejb-jar.

- `remote` - `true`/`false` value stating whether or not to activate the EJB instances on this node or to look them up remotely from another server. The default is false.

`<file path="../log/server.log" />`

A relative/absolute path to log events to.

Attribute:

- `path` - The path to the log file.

`<group name="theGroup" />`

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.

`<jazn provider="XML" location="./jazn-data.xml" />`

Configure the OracleAS JAAS Provider to use the XML-based provider type.

Attributes:

- `provider` - XML

- `location` - Path to file. For example: `./jazn-data.xml` This can be an absolute path, or a path relative to the `jazn.xml` file, where the OracleAS 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 can be `NONE` `(`Do not persist changes), `ALL` (Persist changes after every modification), `VM_EXIT` - (Default- Persist changes when VM exits)

- `default-realm` - A realm name. For example: sample_subrealm. Optional if only one realm is configured.

`<jazn-web-app auth-method="SSO" runas-mode="false" doasprivileged-mode="true" />`

The filter element of `JAZNUserManager`.

Attributes:

- Set `auth-method` to SSO (single sign-on). If you do not set this parameter, it defaults to null.

- The `runas-mode` and `doasprivileged-mode` settings are described in Table B-1. See the Oracle Application Server Containers for J2EE Security Guide for more information.

Table B-1 runas-mode and doasprivileged-mode Settings

If runas-mode is Set To... | If doasprivileged-mode Is Set To... | Then...
--- | --- | ---
true | true (default) | `Subject.doAsPrivileged` in a `privilegedExceptionAction` block that calls`chain.doFilter (myrequest,response)`
true | false | `Subject.doAs` in a `privilegedExceptionAction` block that calls `chain.doFilter (myrequest,response)`
false (default) | true | `chain.doFilter (myrequest,response)`
false | false | `chain.doFilter (myrequest,response)`

`<library path="../lib/" />`

A relative/absolute path/URL to a directory or a JAR/ZIP to add as a library-path for this server. Directories are scanned for JARS/ZIP files to include at startup.

Attribute:

- `path` - The path.

`<log>`

Logging settings.

`<odl>`

The ODL log entries are each written out in XML format in its respective log file. The log files have a maximum limit. When the limit is reached, the log files are overwritten.

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 logfile is full, the first log file, `log1.xml` is erased and a new one 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 address="my@mail.address" />`

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 location="mail/TheSession" smtp-host="smtp.server.com">`

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

Namespace (naming context) security policy for RMI clients.

`<namespace-resource root="the/path">`

A resource with a specific security setting.

Attribute:

- `root` - The root of the part of the namespaec 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 OracleAS JAAS Provider LDAP `UserManager` for the overall `UserManager`, but use a OracleAS JAAS Provider XML `UserManager` for checking hidding passwords.

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

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

`<persistence path="./persistence" />`

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 enterprise archive or absolute) to the persistence directory.

`<principals path="principals.xml" />`

Attribute:

- `path` - The path (relative to the enterprise archive or absolute) to the principals file.

`<property name="theName" value="theValue" />`

Contains a name/value pair initialization param.

Attributes:

- `name` - The name of the parameter.

- `value` - The value of the parameter.

`<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 code, 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` element 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 elements that the specific resource provider needs to be given as parameters.

`<security-role-mapping impliesAll="true|false" name="theRole">`

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 name="theUser" />`

A user that this security-role-mapping implies.

Attribute:

- `name` - The name of the user.

`<user-manager class="com.name.of.TheUserManager" display-name="Friendly UserManager name">`

Specifies an optional user-manager to use. For example, user-managers are `com.evermind.sql.DataSourceUserManager`, `com.evermind.ejb.EJBUserManager`, and so on. 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.

- `display-name` - A descriptive name for this UserManager instance.

`<web-module id="myWebApp" path="myWebApp.war" />`

A Web application module 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 when used in web-sites etc.

- `path` - The path (relative to the enterprise archive or absolute) to the web-application.

`<write-access>`

The write access policy.

## B.5 Elements in the application-client.xml File

This section describes the J2EE application client deployment descriptor file.

### B.5.1 <application-client> Element Description

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

#### B.5.1.1 <application-client>

The `application-client` element is the root element of an application client deployment descriptor. The application client deployment descriptor describes the EJB components and external resources referenced by the application client.

#### B.5.1.2 Elements Contained Within <application-client>

Within the `<application-client>` element, the following elements, which are listed alphabetically and not by DTD ordering, can be configured:

`<callback-handler>`

The `callback-handler` element names a class provided by the application. The class must have a no args constructor and must implement the `javax.security.auth.callback.CallbackHandler` interface. The class will be instantiated by the application client container and used by the container to collect authentication information from the user.

`<description>The description</description>`

A short description.

`<display-name>The name</display-name>`

The `display-name` element contains a short name that is intended to be displayed by tools.

`<ejb-link>EmployeeRecord</ejb-link>`

The `ejb-link` element is used in the `ejb-ref` element to specify that an EJB reference is linked to an enterprise bean in the encompassing J2EE Application package. The value of the `ejb-link` element must be the `ejb-name` of an enterprise bean in the same J2EE Application package.

`<ejb-ref>`

The `ejb-ref` element is used for the declaration of a reference to an enterprise bean's home. The declaration consists of an optional description; the EJB reference name used in the code of the referencing application client; the expected type of the referenced enterprise bean; the expected home and remote interfaces of the referenced enterprise bean; and an optional `ejb-link` information. The optional ejb-link element is used to specify the referenced enterprise bean.

`<ejb-ref-name>ejb/Payroll</ejb-ref-name>`

The `ejb-ref-name` element contains the name of an EJB reference. The EJB reference is an entry in the enterprise bean's environment. It is recommended that name is prefixed with "`ejb`/".

`<ejb-ref-type>Entity/Session</ejb-ref-type>`

The `ejb-ref-type` element contains the expected type of the referenced enterprise bean. The `ejb-ref-type` element must be one of the following: Entity Session

`<env-entry>`

The `env-entry` element contains the declaration of an Enterprise JavaBean's environment entries. The declaration consists of an optional description, the name of the environment entry, and an optional value.

`<env-entry-name>minAmount</env-entry-name>`

The `env-entry-name` element contains the name of an Enterprise JavaBean's environment entry.

`<env-entry-type>java.lang.String</env-entry-type>`

The `env-entry-type` element contains the fully-qualified Java type of the environment entry value that is expected by the enterprise bean's code. The following are the legal values of `env-entry-type`: `java.lang.Boolean`, `java.lang.String`, `java.lang.Integer,` `java.lang.Double`, `java.lang.Byte`, `java.lang.Short`, `java.lang.Long`, and `java.lang.Float`.

`<env-entry-value>100.00</env-entry-value>`

The `env-entry-value` element contains the value of an Enterprise JavaBean's environment entry.

`<home>com.aardvark.payroll.PayrollHome</home>`

The `home` element contains the fully-qualified name of the Enterprise JavaBean's home interface.

`<icon>`

The `icon` element contains a `small-icon` and `large-icon` element which specify the URIs for a small and a large GIF or JPEG icon image used to represent the application client in a GUI tool.

`<large-icon>lib/images/employee-service-icon32x32.jpg</large-icon>`

The `large-icon` element contains the name of a file containing a large (32 x 32) icon image. The file name is a relative path within the application client JAR file. The image must be either in the JPEG or GIF format, and the file name must end with the suffix ".`jpg`" or ".`gif`" respectively. The icon can be used by tools.

`<remote>com.wombat.empl.EmployeeService</remote>`

The `remote` element contains the fully-qualified name of the Enterprise JavaBean's remote interface.

`<res-auth>Application/Container</res-auth>`

The `res-auth` element specifies whether the Enterprise JavaBean code signs on programmatically to the resource manager, or whether the Container will sign on to the resource manager on behalf of the bean. In the latter case, the Container uses information that is supplied by the Deployer. The value of this element must be one of the two following: `Application` or `Container`

`<resource-env-ref>`

The `resource-env-ref` element contains a declaration of an application's reference to an administered object associated with a resource in the application's environment. It consists of an optional descrioption, the resource environment reference name, and an indication of the resource environment reference type expected by the application code.

`<resource-env-ref-name>`

The `resource-env-ref-name` element specifies the name of a resource environment entry name used in the application code.

`<resource-env-ref-type>`

The `resource-env-ref-type` element specifies the type of a resource environment reference.

`<resource-ref>`

The `resource-ref` element contains a declaration of Enterprise JavaBean's reference to an external resource. It consists of an optional description, the resource factory reference name, the indication of the resource factory type expected by the enterprise bean code, and the type of authentication (`Bean` or `Container`).

`<res-ref-name>name</res-ref-name>`

The `res-ref-name` element specifies the name of a resource factory reference.

`<res-sharing-scope>Shareable</res-sharing-scope>`

The `res-sharing-scope` element specifies whether connections obtained through the given resource manager connection factory reference can be shared. The value of this element, if specified, must be one of the following: `Shareable` or `Unshareable`. The default value is `Shareable`.

`<res-type>javax.sql.DataSource</res-type>`

The `res-type` element specifies the type of the data source. The type is specified by the Java interface (or class) expected to be implemented by the data source.

`<small-icon>lib/images/employee-service-icon16x16.jpg </small-icon>`

The `small-icon` element contains the name of a file containing a small (16 x 16) icon image. The file name is a relative path within the application client JAR file. The image must be either in the JPEG or GIF format, and the file name must end with the suffix ".`jpg`" or ".`gif`" respectively. The icon can be used by tools.

## B.6 Elements in the orion-application-client.xml File

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

### B.6.1 <orion-application-client> Element Description

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

`<orion-application-client>`

An `orion-application-client.xml` file contains the deploy time information for a J2EE application client. It complements the application client assembly information found in `application-client.xml`.

#### B.6.1.1 Elements Contained Within <orion-application-client>

Within the `<orion-application-client>` element, the following elements, which are listed alphabetically and not by DTD ordering, can be configured:

`<context-attribute name="name" value="value" />`

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 location="ejb/Payroll" name="ejb/Payroll" />`

The `ejb-ref` element is 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.

- `name` - The `ejb-ref` name. Matches the name of an ejb-ref in `application-client.xml`.

`<env-entry-mapping name="theName">deploymentValue</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.

Attribute:

- `name` - The name of the context parameter.

`<lookup-context location="foreign/resource/location">`

The specification of 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 location="jdbc/TheDS" >`

The `resource-env-ref` element is used for the declaration of 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 location="jdbc/TheDS" name="jdbc/TheDSVar">`

The `resource-ref` element is used for the declaration of 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 an `resource-ref` in `application-client.xml`.

## B.7 Standalone OC4J Command-Line Options and Properties

You start OC4J through `oc4j.jar`. You manage OC4J through the `admin.jar` tool. The following sections describe the options for each JAR.

- Options for the OC4J Server JAR

- Options for the OC4J Administration Management JAR

### B.7.1 Options for the OC4J Server JAR

The `oc4j.jar` command-line options enable you to start, stop, and install OC4J.

Table B-2 lists all the `oc4j.jar` command-line options:

Table B-2 OC4J Command-Line Options

Command-Line Options | Description
--- | ---
`-install` | Installs the server and activates the admin account. Rewrites text files to match the operating system line feed. This should be used only the first time.
`-quiet` | Supress standard output.
`-config` | Specifies a location for the `server.xml` file.
`-out [file]` | Specifies a file to route the standard output to. The file contains messages that are printed to `System.out`, as well as the messages sent to output through the servlet logging interface. If not specified, all output is written to standard out. See Table B-9, "stdout/stderr Archive Management Properties" for additional system properties that can be set to manage `stdout` files.
`-err [file]` | Specifies a file to route standard error to. The file contains messages that are printed to `System.err`. If not specified, all errors are written to standard error. See Table B-9, "stdout/stderr Archive Management Properties" for additional system properties that can be set to manage `stderr` files.
-verbosity | Define an integer between 1 and 10 to set the verbosity level of the message output. Example:`-verbosity 10`.
`-monitorResourceThreads` | Enables backup debugging of thread resources. Enable this only if you have problems that relates to threads getting stuck in critical sections of code.
`-userThreads` | Enables context lookup support from user-created threads.
`-version` | Prints the version and exits.
`-? -help` | Prints the help message.

### B.7.2 Options for the OC4J Administration Management JAR

The `admin.jar` command-line tool enables you to administer any stand alone OC4J from a client-admin console using a command line.

The syntax is as follows:

    java -jar admin.jar ormi://oc4j_host:oc4j_ormi_port admin_id      admin_password options

The options for the `admin.jar` command-line tool cover the four subjects below:

- General OC4J administration described in Table B-3.

- Application deployment described in Table B-4.

- Web site administration described in Table B-5.

- Data source administration described in Table B-6.

#### B.7.2.1 General OC4J Administration

Table B-3 lists the `admin.jar` options for general OC4J administration. For example, the following command shuts down the OC4J server:

    java -jar admin.jar ormi://oc4j_host:oc4j_ormi_port admin_id      admin_password -shutdown

Table B-3 Options for OC4J Administration

Option | Description
--- | ---
`-shutdown [ordinary | force][reason]` | Shuts down the OC4J server. The default is "`ordinary`." Ordinary allows each thread to terminate normally. Force terminates all threads immediately. The reason is a string that is logged with the termination.
`-restart [reason]` | Restarts the OC4J server. The container must have been started with `oc4j.jar`. The reason is a string that is logged with the restart.

#### B.7.2.2 Application Deployment

Table B-4 lists the `admin.jar` options for OC4J application administration. For example, the following command structure is used to deploy an application:

    java -jar admin.jar ormi://oc4j_host:oc4j_ormi_port admin_id      admin_password -deploy -file path/filename    -deploymentName app_name -targetPath deploy_dir

The following command structure is used to bind a Web application:

    java -jar admin.jar ormi://oc4j_host:oc4j_ormi_port admin_id      admin_password -bindWebApp app_name web_app_name                                  web_site_name context_root

Table B-4 Options for Application Deployment

Option | Description
--- | ---
`-deploy` | Deploy (redeploy) an application. Supply application information in the following subswitches: `-file` path/filename: Required. The path and filename of the EAR file to deploy. `-deploymentName` app_name: Required. The user-defined application deployment name. This same name is used to identify the application within OC4J. It is also provided when you want to undeploy the application. `-targetPath` deploy_dir: Optional. The path on the server node to deploy archive into. Default is the `applications/` directory. It is best to provide a target path to the directory where the EAR file is copied for deployment. If `-targetPath` is not specified, the EAR file is copied to the `applications/` directory. OC4J maintains a unique name for the EAR file. Thus, when you redeploy the EAR file, OC4J renames the file by prepending an underscore character ('_') in front of the name to ensure that another application's EAR file is not overwritten. Each successive deployment will cause another underscore character to be prepended to the EAR file. However, if it is the same application, the `applications/` directory contains a separate EAR file for each deployment. If you provide a target path, this problem does not occur. `-parent` parent_appname: Optional. The parent application of this application. When deployed, any method within the child application can invoke any method within the parent application. This is a means to enable methods in one JAR to see EJBs that have been deployed in another JAR. This is useful to deploy all service EJBs in a single JAR file, where its users declare the service application as its parent. The default is the global application. `-deploymentDirectory` path: Optional. If not specified, the application is deployed into the `application-deployments`/ directory. To change where the application is deployed, provide a path with this option. If you supply the string "[NONE]", the deployment configurations are always read from the EAR file each time the application is deployed.
`-bindWebApp` app_name`` web_app_name`` web_site_name`` context_root | Bind a Web application to the specified site and root. app_name is the application name, which is the same name used in `-deploymentName` on the `-deploy` option. Also note that this is the same name that is saved in the `<application name=`app_name`>` attribute in the `server.xml` file. web_app_name is the name of the WAR file contained within the EAR file—without the `.WAR` extension. web_site_name is the name of the name`-web-site.xml` file that denotes the Web site that this Web application should be bound to. This is the file that will receive the Web application definition. context_root is the root context for the Web module. This option creates an entry in the OC4J name`-web-site.xml` configuration file that was denoted in the web_site_name variable.
-`updateConfig` | If you have set `check-for-updates` to false, then OC4J does not automatically refresh modifications of the XML files. You have to execute this flag to have OC4J upload all of the new changes to these files.
-`undeploy` app_name | Removes the deployed J2EE application from the OC4J Web server. The app_name is the name provided on the `-deploymentName` subswitch. This results in the following: Application is removed from the OC4J runtime and the `server.xml` file. Bindings for all the application's Web modules are removed from all the Web sites to which the Web modules were bound. Application files are removed from both the `applications` and `application-deployments` directories. `-keepFiles`: Optional subswitch that prevents application files from being removed. However, the application is removed from the runtime and the Web modules are unbound.
-`deploymentDirectory` "[NONE]" | If you specify this flag as "[NONE]", then OC4J uses the `orion-ejb-jar.xml` deployment descriptor in the current deployment to be used instead of the deployment descriptor from a previous deployment within the `application-deployments` directory.
-`iiopClientJar` | You can convert an EJB to use RMI/IIOP, making it possible for EJBs to invoke one another across EJB containers. See the RMI/IIOP chapter in the Oracle Application Server Containers for J2EE Services Guide for full details.

#### B.7.2.3 Adding Web Sites

The `-site` option enables you to add Web site configuration to the XML files. Table B-5 lists all the subswitches for the `-site` option of the `admin.jar` command-line tool.

For example, the following command structure installs a new Web site:

    java -jar admin.jar ormi://oc4j_host:oc4j_ormi_port admin_id      admin_password -site -add -host hostname -port portnumber		      -display-name name -virtual-hosts virtual_host

Table B-5 Options for Web Site Administration

-site options | Description
--- | ---
`-site -add` | Installs a new Web site. Supply information with the following subswitches: `-host` hostname: The host where the web site exists. `-port` portnum: The Web site port. `-display-name` name: The name of the Web site. `-virtual-hosts` virtual_hosts: The virtual hosts of the Web site. `-secure true|false`: The value is `true` if the Web site is secure, otherwise the value is `false`. `-factory` factory_name: The name of the `SSLServerSocketFactory` class if you are not using the Java Secure Socket Extension (JSSE). The JSSE defines a provider interface that other security providers can implement. Sun Microsystems provides its own implementation in `com.sun.net.ssl.internal.ssl.Provider`. `-keystore` keystore: The relative or absolute path to a keystore. `-storepass` password: The keystore password. `-provider` provider: The provider used if using JSSE, defaults to `com.sun.net.ssl.internal.ssl.Provider`. `-needs-client-auth true|false`: If set to `true`, a client that wants to access a J2EE Web site needs to identify itself with a digital certificate. If set to `false`, a client does not need to identify itself with a digital certificate. The default is `false`.
-`site -remove` | Removes an existing Web site. Supply the host and port of this Web site with the following subswitches: `-host` hostname: The Web site host to be removed. `-port` portnum: The Web site port to be removed.
`-site -test` | Tests an existing Web site. Supply the host and port of the Web site to be tested with the following subswitches: `-host` hostname: The Web site host to be tested. `-port` portnum: The Web site port to be tested.
`-site -list` | Lists all existing Web sites.
-`site -update` | Updates an existing Web site. Supply information with the following subswitches: `-oldHost` hostname: The old host of the Web site. You can change the Web site host and port with the "old" and "new" subswitches. `-oldPort` portnum: The old port of the Web site. `-newHost` hostname: The new host of the Web site. `-newPort` portnum: The new port of the Web site. `-display-name` name: The new display name of the Web site. `-virtual-hosts` vhosts: The new virtual hosts of the Web site. `-secure` `true|false`: If set to `true`, the Web site is secure. If set to `false`, the Web site is not secure. The default is `false`. `-factory` classname: The new name of the `SSLServerSocketFactory` class if you are not using JSSE. `-keystore` path: The new relative or absolute path to a keystore. `-storepass` password: The new keystore password. `-provider` provider: The new provider used if you are not using JSSE. `-needs-client-auth true|false`: If set to `true`, a client that wants to access a J2EE Web site needs to identify itself with a digital certificate. If set to `false`, a client does not need to identify itself with a digital certificate. The default is `false`.

#### B.7.2.4 DataSource And Application Options

Table B-6 lists the `-application` option subswitches for the `admin.jar` command-line tool. The `-application` takes in a name of an application before the subswitch command. This name can be one of the following:

- The global application name, installed originally as `default`, specified in the `name` attribute of the `<global-application>` element in the `server.xml` file.

- A specific application name defined within an `<application>` element in the `server.xml` file.

This name, while a string, should not be enclosed in quotes. For example, the following command lists all data source objects defined:

    java -jar admin.jar ormi://oc4j_host:oc4j_ormi_port admin_id      admin_password -application default -listDataSource

Table B-6 Options For Application And Data Source Management

-application Option | Description
--- | ---
`-application` `name``-restart` | Restarts the application. This triggers auto-deployment if enabled and a file has been touched.
`-application` `name``-addUser` `username password` | Adds a user to the security file (`principals.xml`).
`-application` `name``-dataSourceInfo` | Retrieves the dynamic usage information about the installed `DataSource` objects.
`-application` `name``-listDataSource` | Retrieves the statically configured information about each installed `DataSource` object.
`-application` `name``-testDataSource` | Tests an existing `DataSource`. Supply information with the following subswitches: `-location` location: The namespace location for the `DataSource`. For example, `jdbc/DefaultDS`. Required. `-username` username: The username you use to login along with a password. Optional. `-password` password: The password to log in with. Optional.
`-application` `name``-installDataSource` | Installs a new `DataSource`. Supply information within the following subswitches: `-jar` JARfile: The JAR file containing the driver that is to be added to the library of the server. `-url` URL: The JDBC database URL. `-location` JNDIlocation: The namespace location for the raw source. For example, `"jdbc/DefaultPooledDS"`. Required. `-pooledLocation` JNDIlocation: The namespace location for the pooled source. For example, "`jdbc/DefaultPooledDS"`. `-xaLocation` JNDIlocation: The namespace location for the XA source. For example,`"jdbc/xa/DefaultXADS"`. Requied if `-ejbLocation` is specified. `-ejbLocation` JNDIlocation: The namespace location for the container-managed transactional data source. This is the only data source that can perform global JTA transactions. For example, "`jdbc/DefaultDS"`. `-username` username: The username to log in with. `-password` password: The password to log in with. `-connectionDriver` driverClass: The JDBC database driver class. `-classname` DSclass: The data source class name, such as `com.evermind.sql.DriverManagerDataSource`. Required. `-sourceLocation` jndiDS: The underlying data source of this specialized data source. `-xaSourceLocation` jndiXADS: The underlying XA data source of this specialized data source.
`-application` `name``-removeDataSource` | Remove an existing `DataSource.` Supply information with the following subswitches: `-location` JNDIlocation: The namespace location for the `DataSource`. For example, `jdbc/DefaultDS`. Required.
`-application` `name``-updateDataSource` | Update an existing `DataSource`. Supply information with the following subswitches: `-oldLocation` JNDIlocation: The old namespace location for the `DataSource`. For example, `jdbc/DefaultDS`. Required. `-newLocation` JNDIlocation: The new namespace location for the `DataSource`. For example, `jdbc/DefaultDS`. `-jar` JAR: The JAR file containing the driver to add to the library of the server. `-url` URL: The JDBC database URL. `-pooledLocation` JNDIlocation: The namespace location for the pooled source. For example, `jdbc/DefaultPooledDS`. `-xaLocation` JNDIlocation: The namespace location for the XA `DataSource`. For example, `jdbc/xa/DefaultXADS`. Required if `-ejbLocation` is specified. `-ejbLocation` JNDIlocation: The namespace location for the data source for container-managed transactions. This is the only data source that can perform global JTA transactions. For example, `jdbc/DefaultDS`. `-username` username: The username you use to login. `-password` password: The password you use to login. `-connectionDriver` driverClass: The JDBC database driver class. For example, `com.mydb.Driver`. `-className` dsClass: The data source class name. For example, `com.evermind.sql.DriverManagerDataSource`. `-sourceLocation` jndiDS: The underlying data source of this specialized data source. `-xaSourceLocation` jndiXADS: The underlying XA data source of this specialized data source.

## B.8 OC4J System Properties

You can set system properties on the OC4J command-line before startup. If OC4J is running, you must restart the instance for these to take effect. All system properties are prefaced with a `-D`. For example, `-DGenerateIIOP`.

- Table B-7 details general system properties.

- Table B-8 details debugging properties.

Table B-7 -D General System Properties for OC4J

-D Option | Description
--- | ---
`java.home` | Sets the `JAVA_HOME` environment variable
`java.ext.dirs` | Sets the external directories to be searched for classes when compiling.
`java.io.tmpdir=``new_tmp_dir` | Default is `/tmp/var`. To change the temporary directory for the deployment wizard. The deployment wizard uses 20 MB in swap space of the temp directory for storing information during the deployment process. At completion, the deployment wizard cleans up the temp directory of its additional files. However, if the wizard is interrupted, it may not have the time or opportunity to clean up the temp directory. Thus, you must clean up any additional deployment files from this directory yourself. If you do not, this directory may fill up, which will disable any further deployment. If you receive an `Out` `of` `Memory` error, check for space available in the temp directory.
`GenerateIIOP=true/false` | Default is false. If true, enables IIOP stub generation.
`KeepIIOPCode=true/false` | Default is false. If true, keeps the generated IIOP stub/tie code.
`oracle.arraylist.deepCopy=true/false` | If true, then while cloning an array list, a deep copy is performed. If false, a shallow copy is performed for the array list. Default: true
`dedicated.rmicontext=true/false` | Default is false. This replaces the deprecated `dedicated.connection` setting. When two or more clients in the same process retrieve an `InitialContext`, OC4J returns a cached context. Thus, each client receives the same `InitialContext`, which is assigned to the process. Server lookup, which results in server load balancing, happens only if the client retrieves its own `InitialContext`. If you set `dedicated.rmicontext=true`, then each client receives its own `InitialContext` instead of a shared context. When each client has its own `InitialContext`, then the clients can be load balanced. This parameter is for the client. You can also set this in the JNDI properties.
`oracle.mdb.fastUndeploy=<int>` | The `oracle.mdb.fastUndeploy` system property enables you to shutdown OC4J cleanly when you are running MDBs in a Windows environment or when the backend database is running on a Windows environment. Normally, when you use an MDB, it is blocked in a receive state waiting for incoming messages. However, if you shutdown OC4J while the MDB is in a wait state in a Windows environment, then the OC4J instance cannot be stopped and the applications are not undeployed since the MDB is blocked. However, you can modify the behavior of the MDB in this environment by setting the `oracle.mdb.fastUndeploy` system property. If you set this property to an integer, then when the MDB is not processing incoming messages and in a wait state, the OC4J container goes out to the database (requiring a database round-trip) and polls to see if the session is shut down. The integer denotes the number of seconds that the system waits to poll the database. This can be expensive for performance. If you set this property to 60 (seconds), then every 60 seconds, OC4J checks the database. If you do not set this property and you try to shutdown OC4J using CTRL-C, then the OC4J process will hang for at least 2.5 hours.
`oracle.dms.sensors=[none, normal, heavy, all].` | ``You can set the value for Oracle Application Server built-in performance metrics to the following: none (off), normal (medium amount of metrics), heavy (high number of metrics), or all (every possible metric). The default is normal.This parameter should be set on the OC4J server. The previous method for turning on these performance metrics, `oracle.dms.gate=true/false`, is replaced by the `oracle.dms.sensors` variable. However, if you still use `oracle.dms.gate`, then setting this variable to false is equivalent to setting `oracle.dms.sensors=none`.
`associateUsingThirdTable=true/false` | For container-managed relationships in entity beans, you can designate if a third database table is used to manage the relationship. Set to false if you do not want a third association table. Default is false. See the "Entity Relationship Mapping" chapter in the Oracle Application Server Containers for J2EE Enterprise JavaBeans Developer's Guide for more information.
`DefineColumnType=true/false` | `DefineColumnType=true/false`. The default is false. Set this to true if you are using an Oracle JDBC driver that is prior to 9.2. For these drivers, setting this variable to true avoids a round-trip when executing a select over the Oracle JDBC driver. This parameter should be set on the OC4J server. When you change the value of this option and restart OC4J, it is only valid for applications deployed after the change. Any applications deployed before the change are not affected. When true, the `DefineColumnType` extension saves a round trip to the database that would otherwise be necessary to describe the table. When the Oracle JDBC driver performs a query, it first uses a round trip to a database to determine the types that it should use for the columns of the result set. Then, when JDBC receives data from the query, it converts the data, as necessary, as it populates the result set. When you specify column types for a query with the `DefineColumnType` extension set to true, you avoid the first round trip to the Oracle database. The server, which is optimized to do so, performs any necessary type conversions.

Table B-8 -D System Properties for Debugging

-D Debug System Properties | Description
--- | ---
`KeepWrapperCode` | Default: false. If true, keeps and debugs the generated wrapper code.
`DBEntityHomeDebug` | Default: false. If true, displays entity bean home interface debug messages.
`DBEntityObjectDebug` | Default: false. If true, displays entity bean object debug messages.
`DBEntityWrapperDebug` | Default: false. If true, displays entity bean pool debug messages.
`iiop.runtime.debug` | Default: false. If true, outputs IIOP debug messages.
`NativeJDBCDebug` | Default: false. Native JDBC debug messages.
`http.cluster.debug` | Default: false. HTTP clustering debug messages.
`http.request.debug` | Default: false. If true, provides information about each HTTP request directed to standard output.
`http.redirect.debug` | Default: false. If true, provides information about each HTTP redirects to standard output.
`http.method.trace.allow` | Default: false. If true, turns on the `trace` HTTP method.
`http.session.debug` | Default: false. If true, provides information about HTTP session events
`http.error.debug` | Default: false. If true, prints all HTTP errors
`http.virtualdirectory.debug` | Default:false. If true, print the enforced virtual directory mappings upon startup.
`debug.http.contentLength` | Default: false. If true, print explicit content-length calls as well as extra sendError information.
`ejb.cluster.debug` | Default: false. EJB clustering debug messages.
`cluster.debug` | Default: false. Clustering debug messages.
`jms.debug` | Default: false. JMS debug messages.
`multicast.debug` | Default: false. Multicast debug messages.
`rmi.debug` | Default: false. RMI debug messages.
`transaction.debug` | Default: false. If true, prints debug messages for JTA events.
`rmi.verbose` | Default: false. RMI verbose information.
`datasource.verbose` | Default: false. If true, provides verbose information on creation of data source and connections using data sources and connections released to the pool, and so on,
`jdbc.debug` | Default: false. If true, provides very verbose information when JDBC calls are made
`ws.debug` | Default:false. If true, turns on OracleAS Web Services debugging
`javax.net.debug=[ssl|all]` | If ssl, turns on SSL debugging. If all, turns on SSL debugging with verbose messages.

For more information about debugging properties, see "OC4J Debugging".

Table B-9 stdout/stderr Archive Management Properties

Property | Description
--- | ---
    stdstream.filesize= <max_file_size>
| The maximum size any file in the archive will be allowed to grow to, in megabytes. Files are rotated when this maximum is reached.
`stdstream.filenumber=<max_files>` | The maximum number of files to keep as archives. The oldest file will be automatically deleted when the limit is exceeded.
    stdstream.rotatetime= <HH:mm>
| The time at which the log file will be rotated each day.

## B.9 Configuration and Deployment Examples

The following examples show how to configure and deploy a J2EE application within OC4J. See "Configuring the FAQ Application Demo" to learn how to modify the XML configuration files for the FAQ application demo.

- J2EE Application XML Configuration Example

- Deploying Example

### B.9.1 J2EE Application XML Configuration Example

In this example, the `myapp` application contains a Java client, an EJB assembled into a JAR file, servlets and JSPs assembled into a WAR file, and an EAR file that contains both the EJB JAR file and the Web application WAR file. The tree structure showing the location of all the XML configuration files, the Java class files, and the JSP files is shown in Application EAR Structure. Notice that you can separate all the configuration files into logical directories within the application directory.

Application EAR Structure

Description of the illustration apdx_aa.gif

#### B.9.1.1 application.xml Example

The `myapp/META-INF/application.xml` file lists the EJB JAR and Web application WAR file that is contained in the EAR file using the `<module>` elements.

    <?xml version="1.0"?>
    <!DOCTYPE application PUBLIC "-//Sun Microsystems, Inc.//DTD J2EE Application 1.3//EN" "http://java.sun.com/j2ee/dtds/application_1_3.dtd">
    <application>
      <display-name>myapp j2ee application</display-name>
      <description>
         A sample J2EE application that uses a Container Managed
         Entity Bean and JSPs for a client.
      </description>
      <module>
        <ejb>myapp-ejb.jar</ejb>
      </module>
      <module>
        <web>
          <web-uri>myapp-web.war</web-uri>
          <context-root>/myapp</context-root>
        </web>
      </module>
    </application>

#### B.9.1.2 web.xml Example

The `myapp/web/WEB-INF/web.xml` file contains the class definitions for EJBs, servlets, and JSPs that are executed within the Web site. The `myapp` Web module specifies the following in its descriptor:

- The default page to be displayed for the application's root context as specified using the `admin.jar` `bind` command (`http://`oc4j_host:port`/myapp`)

- Where to find the stubs for the EJB home and remote interfaces

- The JNDI name for the EJB

- The included servlets and where to find each servlet class

- How servlets are mapped to a subcontext using the `<servlet-mapping>` element (/`template`) off of the application root context

The Web server looks for the following:

- All servlet classes under `WEB-INF/classes/<package>.<class>`.

- All HTML and JSP from the root of the WAR file that is pointed to by `<web-app name="<warfile.war>">` in the `web-site.xml` file, which is packaged in the deployed corresponding application EAR file.

- OC4J compiles each JSP from .`java` into .`class` the first time it is used and caches it for subsequent use.

    <web-app>
       <display-name>myapp web application</display-name>
       <description>
          Web module that contains an HTML welcome page, and 4 JSP's.
       </description>
       <welcome-file-list>
          <welcome-file>index.html</welcome-file>
       </welcome-file-list>
       <ejb-ref>
          <ejb-ref-name>TemplateBean</ejb-ref-name>
          <ejb-ref-type>Entity</ejb-ref-type>
          <home>TemplateHome</home>
          <remote>Template</remote>
       </ejb-ref>
       <servlet>
          <servlet-name>template</servlet-name>
          <servlet-class>TemplateServlet</servlet-class>
          <init-param>
             <param-name>length</param-name>
             <param-value>1</param-value>
          </init-param>
       </servlet>
    </web-app>

#### B.9.1.3 ejb-jar.xml Example

The `ejb-jar.xml` file contains the definitions for a container-managed persistent EJB. The `myapp` EJB deployment descriptor contains the following:

- The entity bean uses container-managed persistence.

- The primary key is stored in a table. This descriptor defines the type and fields of the primary key.

- The table name is `TemplateBean`, and columns are named according to fields in the `ejb-jar.xml` descriptor and type mappings in `j2ee/home/config/database-schemas/oracle.xml`.

- The bean uses JDBC to access databases, as specified in `data-source.xml`, by e`jb-location` or by `default-data-source` in `orion-application.xml`.

    <ejb-jar>
       <display-name>myapp</display-name>
       <description>
          An EJB app containing only one Container Managed Persistence           Entity Bean
       </description>
       <enterprise-beans>
          <entity>
             <description>
                template bean populates a generic template table.
             </description>
             <display-name>TemplateBean</display-name>
             <ejb-name>TemplateBean</ejb-name>
             <home>TemplateHome</home>
             <remote>Template</remote>
             <ejb-class>TemplateBean</ejb-class>
             <persistence-type>Container</persistence-type>
             <prim-key-class>java.lang.Integer</prim-key-class>
             <reentrant>False</reentrant>
             <cmp-field><field-name>empNo</field-name></cmp-field>
             <cmp-field><field-name>empName</field-name></cmp-field>
             <cmp-field><field-name>salary</field-name></cmp-field>
             <primkey-field>empNo</primkey-field>
          </entity>
       </enterprise-beans>
       <assembly-descriptor>
          <container-transaction>
             <method>
                <ejb-name>TemplateBean</ejb-name>
                <method-name>*</method-name>
             </method>
             <trans-attribute>NotSupported</trans-attribute>
          </container-transaction>
          <security-role>
             <description>Users</description>
             <role-name>users</role-name>
          </security-role>
       </assembly-descriptor>
    </ejb-jar>

#### B.9.1.4 server.xml Addition

When you deploy the application using the `admin.jar` `-deploy` option, this adds the location of the application EAR file to the `server.xml` file. This causes the application to be started every time that OC4J is started. If you do not want the application to be started with OC4J, change the `auto-start` attribute to `FALSE`.

Note: If you set `auto-start` to `FALSE`, you can manually start the application using the `admin.jar` tool or it is automatically started when a client requests the application.

    <application name="myapp" path="../myapp/myapp.ear"  	auto-start="true" />

where

- The `name` attribute is the name of the application.

- The `path` indicates the directory and filename for the EAR file.

- The `auto-start` attribute indicates if this application should be automatically started each time OC4J is started.

#### B.9.1.5 http-web-site.xml Addition

You must designate the WAR file name and define the root context for the Web application, which was deployed in the WAR file. You can either bind the Web context through the `admin.jar` `-bindWebApp` option or edit the `http-web-site.xml` file and add the following:

    <web-app application="myapp" name="myapp-web" root="/myapp" />

- The `name` attribute is the name of the WAR file, without the `.WAR` extension.

- The `root` attribute defines the root context for the application off of the Web site. For example, if you defined your Web site as "`http://``oc4j_host`:`8888"`, then to initiate the application, you would point your browser at "`http://``oc4j_host`:`8888/myapp"`.

#### B.9.1.6 Client Example

The application client that accesses the `myapp` application has a descriptor, which describes where to find the EJB stubs (home and remote interface) and its JNDI name.

The client XML configuration is contained in two files: `application-client.xml` and `orion-application-client.xml`.

The `application-client.xml` file contains a reference for an EJB, as follows:

    <application-client>
    	<display-name>TemplateBean</display-name>
    	<ejb-ref>
    		<ejb-ref-name>TemplateBean</ejb-ref-name>
    		<ejb-ref-type>Entity</ejb-ref-type>
    		<home>mTemplateHome</home>
    		<remote>Template</remote>
    	</ejb-ref>
    </application-client>

The `orion-application-client.xml` file maps the EJB reference logical name to the JNDI name for the EJB. For example, this file maps the `<ejb-ref-name>` element, "`TemplateBean,"` defined in the `application-client.xml`, to the JNDI name, "`myapp/myapp-ejb/TemplateBean`", as follows:

    <orion-application-client>
    	<ejb-ref-mapping name="TemplateBean" location="myapp/myapp-ejb/TemplateBean" />
    </orion-application-client>

##### B.9.1.6.1 JNDI Properties for the Client

Set the JNDI properties for a regular client so it finds the initial JNDI context factory in one of the following manners:

- Set the JNDI properties within a Hashtable, then pass the properties to `javax.naming.InitialContext.`

- Set the JNDI properties within a `jndi.properties` file.

  If you provide the JNDI properties in the `jndi.properties` file, package the properties in `myapp-client.jar` to ensure that it is in the `CLASSPATH`.

      jndi.properties:
      ---------------
      java.naming.factory.initial=com.evermind.server.ApplicationClientInitialContextFactory
      java.naming.provider.url=ormi://oc4j_host:23791/myapp
      java.naming.security.principal=admin
      java.naming.security.credentials=welcome

#### B.9.1.7 Deploying Example

After developing your J2EE application, assemble the different modules of your J2EE application (EJB, Web, and client) into an EAR file. This section provides an example of a J2EE application with a EJB, Web, and client sections.

To deploy this application from the client using the `admin.jar` command-line tool, perform the following from the `myapp` directory. Notice that it defines the EAR file in the `-file` option and the target path for copying the EAR file into in the `-targetPath` option. Because the path where the EAR resides and the target path is the same, no copying occurs.

    % java -jar $J2EE_HOME/admin.jar ormi://oc4j_host admin welcome  	-deploy -file ./myapp.ear -deploymentName myapp
    Auto-deploying myapp (New server version detected)...
    Auto-deploying myapp-ejb.jar (ejb-jar.xml had been touched since the previous deployment)... done.
    Auto-deploying myapp web application (New server version detected)...

Note: The EJB JAR file is immediately unpacked; the WAR file is unpacked when you navigate to `/myapp` on the Web server.

#### B.9.1.8 EJB Module

When you deployed the EJB module, the following messages were received:

    Auto-deploying myapp (New server version detected)...
    Auto-creating table: create table TemplateBean (col_1 NUMBER not null primary key, col_2 VARCHAR2(255) null, col_3 FLOAT null)
    Auto-deploying myapp-ejb.jar (Class 'myapp.myapp-ejb.Template' had been updated)... done.

OC4J created the `TemplateBean` table for you; however, you must first install a data source. You can use the `admin.jar` command-line tool to install the data source, as follows:

    % java -jar admin.jar ormi://oc4j_host admin welcome   	-installDataSource -jar $ORACLE_HOME/jdbc/classes12.jar  	-url jdbc:oracle:thin:@oc4j_host:1521/MYSERVICE  	-connectionDriver oracle.jdbc.driver.OracleDriver  	-location jdbc/DefaultOracleDS -username scott -password tiger

#### B.9.1.9 Web Module—Servlet and JSP Calling EJBs

To bind the Web component (WAR file) of a J2EE application (EAR file) on a Web site, do the following:

    % java -jar admin.jar ormi://oc4j_host admin welcome  	-bindWebApp myapp myapp-web http-web-site /myapp

This adds the following to `http-web-site.xml`:

    <web-app application="myapp" name="myapp-web" root="/myapp" />

#### B.9.1.10 Client Module—Standalone Java Client Invoking EJBs

Package your client module in a JAR file with the descriptor `META-INF/application-client.xml`.

##### B.9.1.10.1 Manifest File for the Client

Package the client in a runable JAR with a manifest that has the main class to run and required `CLASSPATH`, as shown below. Check that the relative paths in this file are correct. Verify that you point to the relative location of the required OC4J class libraries.

    manifest.mf
    -----------
    Manifest-Version: 1.0
    Main-Class: myapp.myapp-client.TemplateClient
    Name: "TemplateClient"
    Created-By: 1.2 (Sun Microsystems Inc.)
    Implementation-Vendor: "Oracle"
    Class-Path: ../../../j2ee/home/oc4J.jar ../../../j2ee/home/lib/jndi.jar ../../../j2ee/home/lib/ejb.jar ../myapp-ejb.jar

##### B.9.1.10.2 Executing the Client

To execute the client, perform the following:

    % java -jar myapp-client.jar
    TemplateClient.main(): start
    Enter integer value for col_1: 1
    Enter string value for col_2: BuyME
    Enter float value for col_3: 99.9
    Record added through bean