Skip Headers

Oracle9iAS Containers for J2EE User's Guide
Release 2 (9.0.2)

Part Number A95880-01
Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index

Go to previous page Go to next page

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

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:

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:

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:

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:

jms.xml

This file contains the configuration for the in-memory Java Messaging Service (JMS) implementation. In the jms.xml file, specify the following:

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:

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:

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:

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:

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

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

Reference Other Configuration Files

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

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:

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:

<compiler>

Specifies an alternative compiler (such as Jikes) for EJB/JSP compiling.

Attributes:

<cluster>

Cluster settings for this server.

Attribute:

<global-application>

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

Attributes:

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

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

<rmi-config>

Attribute:

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

<transaction-config>

Transaction configuration for the server.

Attribute:

<web-site>

Attribute:

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 apdx_aa.gif follows

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 Web server looks for the following:

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:

<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

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

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:

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


Go to previous page Go to next page
Oracle
Copyright © 2002 Oracle Corporation.

All Rights Reserved.
Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index