B
Additional Information

This appendix contains complete information about the following topics:

Most of these sections discuss how to modify your XML files. Modify all XML files only through Enterprise Manager. Do not modify XML files on a single node.

Description of XML File Contents

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

OC4J Configuration XML Files

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

server.xml
web-site.xml
jazn-data.xml
data-sources.xml
jms.xml
rmi.xml
httpds.conf
mod_oc4j.conf
workers.properties

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, you specify the following:

The library path, which is located in the application deployment descriptor
The global application, the global Web application, and the default Web site served
Maximum number of HTTP connections the server allows
Logging settings
Java compiler settings
Cluster ID
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

You specify these locations by adding entries that list the location of the Web site configuration files. You can have multiple Web sites. The default-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. You register each Web site within the server.xml file, as follows:
```
<web-site path="./default-web-site.xml" />
<web-site path="./another-web-site.xml" />
```
Note:
The path designated is relative to the config/ directory.

Finally, you can add your own applications to 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.

web-site.xml

This file contains the configuration for a Web site. In the 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

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 password for the client-admin console
Name and description of users/groups, and real name and password for users

data-sources.xml

This file contains configuration for the data sources 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
User/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.

jms.xml

This file contains the configuration for the in-memory Java Messaging 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

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
Clustering settings
Log settings

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 using automatic deployment. You can edit OC4J-specific deployment XML files manually. These files are used by OC4J to map environment entries, resources references, and security-roles to actual deployment-specific values.

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

application.xml

This file identifies the Web or EJB applications contained within the J2EE application. It also identifies the location of the security XML definition file--jazn-data.xml.

orion-application.xml

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
The default data source to use with CMP beans
Security role mappings
Specifying the user manager
JNDI namespace-access rules (authorization)

ejb-jar.xml

This file defines the deployment parameters for the EJBs in this JAR file.

orion-ejb-jar.xml

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

web.xml

This file contains deployment information about the servlets and JSPs in this application.

orion-web.xml

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
Clustering
Session tracking
JNDI mappings

application-client.xml

This file contains JNDI information for accessing the server application and other client information.

orion-application-client.xml

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

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)

Configure OC4J

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

The library path
The global application, the global web application, and the default Web site
Maximum number of HTTP connections the server allows
Logging settings
Java compiler settings
Cluster ID
Transaction time-out
SMTP host

Reference Other Configuration Files

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

The data-sources.xml location
The jazn-data.xml location
The 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.

<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. Also, performs the Web application binding for the default application.
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 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. This defaults to j2ee/home/application-deployments/.
connector-directory=The location and file name of the oc4j-connectors.xml file.
recovery-procedure="automatic|prompt|ignore"> -- Specifies how the EJB container reacts for recovery if an error occurred in the middle of a global transaction (JTA). If a CMP bean is in the middle of a global transaction, 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 because the OC4J server asks for permission to see if there was anything to recover.
- ignore -- ignores recovery (useful in development environments or if you are never executing a CMP entity bean)

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>

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.

<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 manifest, 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-web-app-config>

path=".../web-application.xml" /> -- The path where the web-application.xml file is located.

<jms-config>

Attribute:

path=".../jms.xml" -- Specifies the path to the jms.xml file.

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

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

<rmi-config>

Attribute:

path=".../rmi.xml" -- Specifies the path to the rmi.xml file.

<transaction-config>

Transaction configuration for the server.

Attribute:

timeout="60000" -- 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 60000.

<web-site>

Attribute:

path=".../my-web-site.xml" /> -- 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.

DTD for the server.xml

The DTD designates the syntax and ordering of the server.xml configuration.

<!ENTITY % BOOLEAN "true|false">

<!-- The default application for this server. This will act as a parent 
to the other applications in terms of object visibility etc. -->
<!ELEMENT global-application (#PCDATA)>
<!ATTLIST global-application name CDATA #IMPLIED
path CDATA #IMPLIED>

<!-- Specifies an alternative compiler (such as Jikes) for EJB/JSP 
compiling. -->
<!ELEMENT compiler (#PCDATA)>
<!ATTLIST compiler classpath CDATA #IMPLIED
  executable CDATA #IMPLIED>

<!-- A relative/absolute path to log events to. -->
<!ELEMENT file (#PCDATA)>
<!ATTLIST file path CDATA #IMPLIED>

<!-- Used to restrict the maximum number of connections any given site 
can accept concurrently at any time. If text exists inside the tag it is 
used as redirect-URL when the limit is reached. -->
<!ELEMENT max-http-connections (#PCDATA)>
<!ATTLIST max-http-connections max-connections-queue-timeout CDATA 
#IMPLIED
  socket-backlog CDATA #IMPLIED
  value CDATA #IMPLIED>

<!-- Logging settings. -->
<!ELEMENT log (file*, mail*)>

<!-- A e-mail address to log events to. A valid mail-session also needs 
to be specified if this option is used. -->
<!ELEMENT mail (#PCDATA)>
<!ATTLIST mail address CDATA #IMPLIED>

<!-- This file contains the configuration for an application-server. -->
<!ELEMENT application-server (library*, rmi-config?, jms-config?, 
principals?, log?, transaction-config?, global-application, 
application*, global-web-app-config?, max-http-connections?, web-site*,   
compiler?, cluster?  )>
<!ATTLIST application-server 

  application-auto-deploy-directory CDATA #IMPLIED
  auto-start-applications (true | false) "true" 
  auto-unpack-applications (true | false) #IMPLIED
  application-directory CDATA #IMPLIED
  deployment-directory CDATA #IMPLIED
  connector-directory CDATA #IMPLIED
  recovery-procedure CDATA #IMPLIED
  localhostIsAdmin (true|false) "true"
  transaction-log CDATA #IMPLIED>

<!ELEMENT jms-config (#PCDATA)>
<!ATTLIST jms-config path CDATA #IMPLIED>

<!-- Transaction configuration for the server. -->
<!ELEMENT transaction-config (#PCDATA)>
<!ATTLIST transaction-config timeout CDATA #IMPLIED>

<!ELEMENT web-site (#PCDATA)>
<!ATTLIST web-site path CDATA #IMPLIED>

<!ELEMENT principals (#PCDATA)>
<!ATTLIST principals path CDATA #IMPLIED>

<!-- An application is a unit with it's own set of users, web-apps and 
ejb-jars. -->
<!ELEMENT application (#PCDATA)>
<!ATTLIST application auto-start (true|false) "true"
  deployment-directory CDATA #IMPLIED
  name CDATA #IMPLIED
  parent CDATA #IMPLIED
  path CDATA #IMPLIED>

<!-- Cluster settings for this server. -->
<!ELEMENT cluster (#PCDATA)>
<!ATTLIST cluster id CDATA #IMPLIED>

<!-- 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/zips 
to include at startup. -->
<!ELEMENT library (#PCDATA)>
<!ATTLIST library path CDATA #IMPLIED>

<!ELEMENT rmi-config (#PCDATA)>
<!ATTLIST rmi-config path CDATA #IMPLIED>

<!ELEMENT global-web-app-config (#PCDATA)>
<!ATTLIST global-web-app-config path CDATA #IMPLIED>

Configuration and Deployment Examples

The following example shows how to configure and deploy a J2EE application within OC4J. See "Configuring the Pet Store Web Application Demo" to learn how to modify the XML configuration files for the Pet Store demo.

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 Figure B-1. Notice that you can separate all the configuration files into logical directories within the application directory.

Figure B-1 Application EAR Structure

Text description of the illustration apdx_aa.gif

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.2//EN" 
"http://java.sun.com/j2ee/dtds/application_1_2.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>

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 (http://<apache_host>:<port>/j2ee/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.

<?xml version="1.0"?>
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 
2.2//EN" "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd">

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

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 ejb-location or by default-data-source in orion-application.xml.


<?xml version="1.0"?>
<!DOCTYPE ejb-jar PUBLIC "-//Sun Microsystems, Inc.//DTD Enterprise 
JavaBeans 1.1//EN" "http://java.sun.com/j2ee/dtds/ejb-jar_1_1.dtd">

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

server.xml Addition

When you deploy the application using the deployment wizard, 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 variable to FALSE.

Note:

If you set auto-start to FALSE, you can manually start the application through Enterprise Manager or it is automatically started when a client requests the application.

<application name="myapp" path="../myapp/myapp.ear" 

	auto-start="true" />

where

The name variable is the name of the application.
The path indicates the directory and filename for the EAR file.
The auto-start variable indicates if this application should be automatically started each time OC4J is started.

default-web-site.xml Addition

The deployment wizard defines the root context for the Web application and binds the Web context and adds the following to the default-web-site.xml file:

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

The name variable is the name of the WAR file, without the .WAR extension.
The root variable defines the root context for the application off of the Web site. For example, if you defined your Web site as "http://<apache_host>:7777/j2ee", then to initiate the application, you would point your browser at "http://<apache_host>:7777/j2ee/myapp".

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:

<?xml version="1.0"?>
<!DOCTYPE application-client PUBLIC "-//Sun Microsystems, Inc.//DTD J2EE 
Application Client 1.2//EN" 
"http://java.sun.com/j2ee/dtds/application-client_1_2.dtd">

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

<?xml version="1.0"?>
<!DOCTYPE orion-application-client PUBLIC "-//Evermind//DTD J2EE 
Application-client runtime 1.2//EN" 
"http://xmlns.oracle.com/ias/dtds/orion-application-client.dtd">

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

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.ApplicationClientInitialCont
extFactory
java.naming.provider.url=ormi://<apache_host>:7777/j2ee/myapp
java.naming.security.principal=admin
java.naming.security.credentials=welcome

Client Module--Standalone Java Client Invoking EJBs

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

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/jndi.jar 
../../../j2ee/home/ejb.jar ../myapp-ejb.jar

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

B Additional Information

Description of XML File Contents

OC4J Configuration XML Files

server.xml

web-site.xml

jazn-data.xml

data-sources.xml

jms.xml

rmi.xml

J2EE Deployment XML Files

application.xml

orion-application.xml

ejb-jar.xml

orion-ejb-jar.xml

web.xml

orion-web.xml

application-client.xml

orion-application-client.xml

Elements in the server.xml File

Configure OC4J

Reference Other Configuration Files

<application-server> Element Description

Elements Contained Within <application-server>

DTD for the server.xml

Configuration and Deployment Examples

Figure B-1 Application EAR Structure

application.xml Example

web.xml Example

ejb-jar.xml Example

server.xml Addition

default-web-site.xml Addition

Client Example

JNDI Properties for the Client

Client Module--Standalone Java Client Invoking EJBs

Manifest File for the Client

Executing the Client

B
Additional Information