Oracle9iAS Containers for J2EE User's Guide Release 2 (9.0.2) Part Number A95880-01 |
|
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.
OC4J uses configuration and deployment XML files. The following sections describe each of these types.
This section describes the following XML files, which are necessary for OC4J configuration:
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:
data-sources.xml
configuration
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" />
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.
This file contains the configuration for a Web site. In the web-site.xml
file specify the following:
/~user/ sites
)
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:
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:
This file contains the configuration for the in-memory Java Messaging Service (JMS) implementation. In the jms.xml
file, specify the following:
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:
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:
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
.
This file configures the global application. In the orion-application.xml
file, specify the following:
This file defines the deployment parameters for the EJBs in this JAR file.
This file is the OC4J-specific deployment descriptor for EJBs. In the orion-ejb-jar.xml
file, specify the following:
This file contains deployment information about the servlets and JSPs in this application.
This is the OC4J-specific deployment descriptor for mapping Web settings. This XML file contains the following:
This file contains JNDI information for accessing the server application and other client information.
This OC4J-specific deployment file is for the client application. It contains JNDI mappings and entries for the client.
The server.xml
file is where you perform the following tasks:
Configuring the OC4J server includes defining the following elements in the server.xml
file:
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.
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)
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:
<global-application>
The default application for this server. This acts as a parent to other applications in terms of object visibility.
Attributes:
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:
<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.
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>
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.
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>
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:
http://<apache_host>:<port>/j2ee/myapp
)
<servlet-mapping>
element (/template
) off of the application root context
The Web server looks for the following:
WEB-INF/classes/<package>.<class>
.
<web-app name="<warfile.war>">
in the web-site.xml
file, which is packaged in the deployed corresponding application EAR file.
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>
The ejb-jar.xml
file contains the definitions for a container-managed persistent EJB. The myapp
EJB deployment descriptor contains the following:
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
.
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>
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
.
<application name="myapp" path="../myapp/myapp.ear"
auto-start="true" />
where
name
variable is the name of the application.
path
indicates the directory and filename for the EAR file.
auto-start
variable indicates if this application should be automatically started each time OC4J is started.
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" />
name
variable is the name of the WAR file, without the .WAR
extension.
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"
.
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>
Set the JNDI properties for a regular client so it finds the initial JNDI context factory in one of the following manners:
javax.naming.InitialContext.
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
Package your client module in a JAR file with the descriptor META-INF/application-client.xml
.
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
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
|
Copyright © 2002 Oracle Corporation. All Rights Reserved. |
|