Release 2 (9.0.2)
Part Number A95880-01
 Home |
 Solution Area |
 Contents |
 Index |
| Oracle9iAS Containers for J2EE User's Guide Release 2 (9.0.2) Part Number A95880-01 |
|
This chapter demonstrates how to configure and execute OC4J as simply and quickly as possible. You installed OC4J with the Oracle9iAS installation.
Within OC4J, you can execute servlets, JSP pages, EJBs, and SQLJ. As an example of deploying an application to OC4J, this chapter describes how to configure the familiar Pet Store demo.
This chapter includes the following topics:
OC4J is a lightweight container that is J2EE-compliant. It is configured with powerful and practical defaults and is ready to execute after installation. OC4J is installed with Oracle9iAS; therefore, see the Oracle9i Application Server Installation Guide for details on OC4J installation.
OC4J is installed within Oracle9iAS with the goal of managing J2EE enterprise systems. Oracle9iAS can manage multiple clustered OC4J processes. Oracle9iAS, which includes OC4J, is managed and configured through the Oracle Enterprise Manager, which can manage and configure your OC4J processes across multiple application server instances and hosts. Thus, you cannot locally manage your OC4J process using the admin.jar tool or by hand editing a single OC4J process' configuration files. This undermines the enterprise management provided by the Enterprise Manager.
You can still execute OC4J as you have in the past. For those who want a single OC4J instance for development environments or simple business needs, you can download OC4J in standalone mode--complete with documentation.
This following sections discusses both management options in the following sections:
Also, the following section describes how to understand the OC4J documentation set:
You manage Oracle9iAS, including OC4J, using Enterprise Manager within an enterprise system. This includes clustering, high availability, load balancing, and failover.
You configure each OC4J instance and its properties--within the context of an application server instance--using Enterprise Manager. After configuration, you start, manage, and control all OC4J instances through Enterprise Manager. You can group several OC4J processes in a cluster. You must use either the Enterprise Manager management tool or its command-line tools for starting, stopping, restarting, configuring, and deploying applications.
|
Note:
You cannot use the OC4J standalone tool--
You can modify the XML files locally. If you do so, you must notify Enterprise Manager that these files have been hand edited through the Distributed Configuration Managment (DCM) component tool-- DCM controls and manages configuration for Oracle9iAS instances and its Oracle HTTP Server and OC4J components. For more information on DCM, see Appendix A, "DCM Command-Line Utility (dcmctl)". |
This book discusses how to start, stop, manage, and configure OC4J in an enterprise environment.
You can still use a single OC4J--outside of the Oracle9iAS environment. After downloading OC4J in oc4j_extended.zip from OTN, you can start, manage, and control all OC4J instances through oc4j.jar and the admin.jar command-line tool. You configure either through the admin.jar command or by modifying the XML files by hand.
Any standalone OC4J process is not managed by Enterprise Manager and cannot be used within an Oracle9iAS enterprise environment. Typically, you would use standalone for development or for a simple single OC4J instance Web solution.
Download the OC4J Standalone User's Guide for information on how to start, stop, configure, and manage your standalone process.
Aside from this book, the rest of the OC4J documentation set was written with a standalone mindset. These other books may refer to modifying XML files by hand and to using admin.jar for managing the instance. This book provides a good overview and familiarization of the Enterprise Manager configuration pages. It also guides you to understand the relationship of each Enterprise Manager page to its XML counterpart. Use the familiarity of the Enterprise Manager when reading the other OC4J books. You should be able to look at an XML representation and match it to the relevant Enterprise Manager field names.
Also, the Distributed Configuration Management (DCM) utility, dcmctl, provides a command-line alternative to using Enterprise Manager for some management tasks. The dcmctl tool uses the same distributed architecture and synchronization features as Enterprise Manager, thereby providing identical functionality in a format that is ideal for scripting and automation.
The following functions can be managed through DCM:
For other DCM commands that relate to OC4J, see Appendix A, "DCM Command-Line Utility (dcmctl)".
For HTTP applications, OC4J is preconfigured to execute behind the Oracle HTTP Server (OHS). You use the Oracle HTTP Server as a front-end listener and OC4J as the back-end J2EE application server.
However, for RMI-based applications--such as EJB and JMS--clients should send their requests directly to OC4J. See "Understanding and Configuring OC4J Listeners" for directions.
For all incoming HTTP communication within the application server environment, you use the OHS as a front-end listener and OC4J as the back-end J2EE application server. Figure 2-1 illustrates this as follows:
The mod_oc4j module is preconfigured to direct all incoming HTTP requests under the j2ee/ Web context to OC4J. This is to separate incoming requests for JServ from those directed to OC4J. Thus, if you want to use the default routing, you can deploy your Web application into a servlet context that includes as its prefix j2ee/. However, any URL mapping you provide in the deployment wizard is automatically added to the mod_oc4j module. See "Configuring Oracle HTTP Server With Another Web Context" for information on what is added to mod_oc4j for you during deployment. For additional information on the mod_oc4j module, see the Oracle HTTP Server Administration Guide.
For optimum performance, run OC4J with the JDK that is installed with Oracle9iAS Release 2, which is JDK 1.3.x.
It is not necessary to add anything to your CLASSPATH to run OC4J, because it loads the Java JAR and class files directly from the installation directory, from the lib/ subdirectory, and from the deployed application EAR files.
To use the Oracle Enterprise Manager Home Pages, you must start the Oracle Enterprise Manager Web site. The Web site is automatically started after you install the application server. You must start it manually after each system reboot, or create a script to automatically start it during system boot.
If you need to start or stop the Management Server, use the commands shown in Table 2-1.
The emctl command is available in the ORACLE_HOME/bin directory after you install Oracle9iAS.
You can also verify the Enterprise Manager Web Site is started by pointing your browser to the Web site URL. For example:
http://hostname:1810
A default OC4J instance is installed with the name of OC4J_home. You can create additional instances, each with a unique name within this application server instance.
To create a new OC4J instance, do the following:
A new OC4J instance is created with the name you provided. This OC4J instance shows up on the application server instance page in the Component section.
To delete an OC4J instance, select the radio button next to the OC4J instance you wish to delete, then click Delete.
Most of the configuration and management of your OC4J instance occurs off its OC4J Home Page. When you create an OC4J instance off of the Oracle9iAS Instance Home Page, it creates an OC4J Home Page for configuration and management of your OC4J instance. Each OC4J instance has its own OC4J Home Page.
To navigate to an OC4J Home Page, do the following:
The OC4J Home Page consists of the following three sections:
To navigate to the OC4J instance home page, start Enterprise Manager and navigate to the application server instance page. From this page, select any configured OC4J instance or create a new instance.
Figure 2-2 shows the General and Status sections of the OC4J Home Page. In this section, you can view metrics on your OC4J instance and its applications. In addition, you can start, stop, and restart all OC4J processes configured to this instance.
Figure 2-3 shows the Deployed Applications section. In this section, you can deploy applications using the Deploy EAR file or Deploy WAR file buttons. After deployment, you can modify configuration for each application. See "Configuring the Pet Store Web Application Demo" or "Deploying Applications" for more information.
Figure 2-4 shows the Administration section. This section enables you to modify the global configuration values. This includes configuration of OC4J services, such as RMI, JMS, and Web sites. In addition, you can configure data sources and security values that can be used by all deployed applications in this OC4J instance.
OC4J is installed with a default configuration that includes a default Web site and a default application. Therefore, you can start OC4J immediately without any additional configuration.
From the Oracle Enterprise Manager Web site, you can start, stop, and restart OC4J on one of two pages:
OC4J automatically detects changes made to deployed applications and reloads these applications automatically. Therefore, you do not need to restart the server when redeploying an application. However, you may have to restart OC4J if you modify fields in the RMI, data sources, or security configuration.
You can also start, stop, and restart using the DCM control command. See Appendix A, "DCM Command-Line Utility (dcmctl)" for directions.
Start OC4J with the defaults through Enterprise Manager as follows:
http://<ohs_host>:7777/j2ee
Substitute the name of the host where the OHS is installed for <ohs_host>. This command displays index.html.
http://<ohs_host>:7777/j2ee/servlet/HelloWorldServlet
This command returns a "Hello World" page. The HelloWorldServlet is automatically deployed with the OC4J installation.
When developing your application, Oracle recommends that you use consistent and meaningful naming conventions. As an example, you could develop your application as modules within a directory named after your application. All the subdirectories under this directory could be consistent with the structure for creating JAR, WAR, and EAR archives. Thus, when you have to archive the source, it is already in the required archive format. Figure 2-5 demonstrates this structure.
Consider the following points regarding Figure 2-5:
META-INF, WEB-INF, application.xml, ejb-jar.xml, web.xml, and application-client.xml.
application.xml file, which acts as the manifest file, defines these modules.
<ejb_module>, <web_module>, and <client_module>) can have arbitrary names. However, these names must match the values in the manifest file--the local application.xml file.
'myapp.ejb.Demo' is expected to be located in <appname>/<ejb_module>/myapp/ejb/Demo.class.
This section describes how to configure and deploy Pet Store, which is a J2EE demo application from Sun Microsystems. All OC4J server configuration and modifications to the Pet Store application configuration have been performed for you. You can execute the Pet Store demo with minimal effort to see how OC4J works.
|
Note: Displays of the screens for each step of the deployment wizard are shown in "Deploying Applications". |
Download the Pet Store application from OTN in the jps112.zip file, which downloads version 1.1.2 of the Pet Store demo. This ZIP file contains an annotated version of this application, along with preconfigured OC4J XML files.
You must have a working Oracle database and an OC4J installation. You should use this installation for demonstration purposes only and not in a production environment. In this simplified version, we have pre-built the Pet Store demo using the Oracle database (instead of the default Cloudscape) and edited the configuration files to make the setup easy.
jps112.zip from OTN. This ZIP file contains an annotated version of this application, along with preconfigured OC4J XML files.
jps112.zip file, which contains the following:
steps.html--Steps on how to deploy the Pet store demo in standalone mode. This HTML file does not contain directions on how to deploy using the Oracle Enterprise Manager. The steps in this manual instruct you on how to deploy using Enterprise Manager.
petstore.ear--The Pet Store demo is contained in petstore.ear.
config.zip--OC4J server XML configuration files are provided for you in config.zip file.
config.zip file to retrieve the server.xml, default-web-site.xml, and data-sources.xml files.
data-sources.xml to point to your database by replacing the host, port, and sid in the url attribute for the database in this file, as follows:
url="jdbc:oracle:thin:@<host>:<port>:<sid>"
estoreuser, and grant this user privileges to connect as SYSDBA to your database. You can create the user and grant privileges through the following command:
SQL> grant connect, resource to estoreuser identified by estore;
Since the data sources are provided in a data-sources.xml file, add these data sources using the XML editor within Enterprise Manager. Select data-sources.xml in the filename column. This brings up a screen with XML in a text window. Merge in the data sources from the data-sources.xml that was provided within the config.zip of the Petstore download into this window. Do not overwrite other data sources already configured in this file. When finished, click the Apply button.
petstore.ear file that you downloaded to your system. Type "petstore" in the application name field. Click the Next button.
/estore servlet context. Type "/estore" in the URL mapping field and click the Next button.
petstore" in the Name column of the Applications section. This shows the configuration and all deployed modules of the Petstore demo application. If the OC4J server is started, the application is automatically started.
http://<ohs_host>:<ohs_port>/estore
The Pet Store splash screen appears. Follow the instructions provided by the Pet Store application to load the Java Pet Store database tables.
You may be curious as to what is the difference between the 1.1.2 Pet Store demo available off of the Sun Microsystems site and the modified one we have provided. This section will discuss the modifications we made.
Although the development of J2EE applications is standardized and portable, the XML configuration files are not. You may have to configure multiple XML files before deploying any application to OC4J. The configuration necessary depends on the services that your application uses. For example, if your application uses a database, you must configure its DataSource object.
For basic applications, such as Pet Store, you normally deploy the application using the wizard and configure any DataSource necessary for this application. Before deployment, you must create a manifest for the application within the application.xml file. This can be included in addition to or in replacement of a MANIFEST.MF file. This file must be properly configured and included within the J2EE EAR file that is to be deployed.
Simple applications--including the Pet Store application--require the following basic steps:
The following steps describe what modifications to make to deploy the Pet Store application into OC4J.
JAVA_HOME variable to the base directory of the Java 2 SDK.
<%@ page import ="java.io.*" isErrorPage="true" %> to the jps1.1.2/src/petstore/src/docroot/errorpage.jsp file.
This command prevents the Pet Store error page from throwing a "PrintWriter class not found exception".
jps1.1.2/src/petstore/src/docroot/WEB-INF/web.xml, replace "Java 2 Enterprise Edition Reference Implementation" with "Oracle9iAS Containers for J2EE".
This step, which is optional, updates the application server type of OC4J.
In jps1.1.2/src/components/customer/src/customer_ejb.xml, replace OrderDAOCS with OrderDAOOracle.
application.xml to act as the manifest file for the Pet Store demo and place it into the jps1.1.2/src/petstore/src/ directory. OC4J uses the application.xml file as the manifest file. See the application.xml file that was downloaded in the jps112.zip from OTN.
/src/petstore/src/build.xml to build the EAR file with the OC4J modifications.
jps1.1.2/src/petstore/src/build.bat in a DOS shell.
You can also double-click on the build.bat file in Windows Explorer to execute this file. The build.bat file uses ANT. To learn more about the ANT file, go to the following Jakarta site:
http://jakarta.apache.org/ant/
DataSource definition.
data-sources.xml file contained in the config.zip into the Enterprise Manager data source configuration.
estoreuser and grant it privileges by executing the following SQL command:
grant connect, resource, create session to estoreuser
identified by estore
For instructions on configuring and starting the OHS, see the Oracle HTTP Server Administration Guide.
http://<ohs_host>:<ohs_port>/estore
The Pet Store splash screen appears. Follow the instructions provided by the Pet Store application to load the Java Pet Store database tables.
This section describes how to deploy a J2EE application to the OC4J server. When you deploy an application using the deployment wizard, the application is deployed to the OC4J instance and any Web application is bound to a URL context so that you can access the application from OC4J.
To deploy your application, drill down to the OC4J Home Page and scroll to the Deployed Applications section. Figure 2-3 shows this section.
|
Note:
You can also deploy simple applications with the |
Your J2EE application can contain the following modules:
The Web applications module (WAR files) includes servlets and JSP pages.
The EJB applications module (EJB JAR files) includes Enterprise JavaBeans (EJBs).
Archive the JAR and WAR files that belong to an enterprise Java application into an EAR file for deployment to OC4J. The J2EE specifications define the layout for an EAR file.
The internal layout of an EAR file should be as follows:
Archive these files using the JAR command in the <appname> directory, as follows:
% jar cvfM <appname>.EAR .
Note that the application.xml file acts as a manifest file.
Both of these buttons start an eight-step application deployment wizard, which guides you through deploying an application. In the case of the WAR file, the application.xml file is created for the Web application. Whereas, you must create the application.xml file within the EAR file. Thus, deploying a WAR file is an easier method for deploying a Web application.
Figure 2-7 shows the eight steps required for application deployment:
The first page is an introduction to these steps. It reminds you to provide an EAR file with any OC4J-specific XML configuration files, if necessary. It also outlines some of the other steps in the deployment process.
Click the Next button to go to the next step in the wizard deployment process.
Figure 2-8 shows the second page, which enables you to browse your system for the EAR file to be deployed. In addition, provide a name to be identified with this application. The application name is user-created and will be the identifier for the application in the OC4J Home page.
When the application is deployed, the information in this step enables the following:
/applications directory.
server.xml for the application, as follows:
<application name=<app_name> path=<path_EARfile> auto-start="true"
/>
where
name variable is the name of the application you provided.
path indicates the directory and filename where the EAR file is deployed.
auto-start variable indicates if this application should be automatically restarted each time OC4J is restarted.
For a description of the elements in server.xml, see "Elements in the server.xml File".
Click the Next button to go to the next step in the wizard deployment process.
Map any Web modules in your application to a specific URL for its servlet context. All OC4J servlet contexts must be prefixed with a slash "/". When you try to access any Web applications, you provide the host, port, and Web context.
For all Web modules, your URL mapping for this module includes the URL you bind in this screen. Thus, for the URL http://<host>:<port>/url_name, provide /url_name in the URL mapping screen of the wizard.
Click the Next button to go to the next step in the wizard deployment process.
Map any references resources in your application, such as data sources or mail queues, to physical entities currently present on the OC4J container. Note that if you need a specific resource, you must have already added this to the OC4J container before you deploy your application in order for you to match them in this step.
For most applications, the resource reference you must designate is the data source JNDI name. This screen does not configure the data source information, it only designates an already configured data source or a data source that you will be configuring later. Designate the JNDI location name of the data source that the application will be using.
Click the Next button to go to the next step in the wizard deployment process.
You can specify what User Manager to use for security. For complete security, we recommend that you choose the JAZN XML User Manager.
As Figure 2-9 demonstrates, you must already have your User Manager set up and configured. Most of the entries requires an XML file that designates the security roles, users, and groups for your security mappings.
jazn-data.xml file.
principal.xml file.
For more information on security and User Managers, see both the Chapter 8, "Security" and the Security chapters in the Oracle9iAS Containers for J2EE Services Guide.
Map any security roles defined in your application to existing users and groups. If you have defined a security role within your application, you can map this role to a security group or role. You do not define security groups and users in this screen. Users and groups are obtained from your user manager.
Click the Next button to go to the next step in the wizard deployment process.
For more information on security roles, see both the Chapter 8, "Security", the Security chapters in the Oracle9iAS Containers for J2EE Services Guide and the Oracle9iAS Containers for J2EE Enterprise JavaBeans Developer's Guide and Reference.
Publish any Web services defined in your application. This feature requires the UDDI registry. Web services are not installed with a core install.
If you have defined any Web services, they are shown in the following screen:
If you want to publish these Web services, then click on the Publish button. This leads you through the process of publishing your Web services. When finished, it brings you back to this screen.
Click the Next button to go to the next step in the wizard deployment process.
At this point, you will receive a summary of your application deployment modules and configuration, as follows:
In order to deploy this application, click on the Deploy button. A message will be displayed that tells you that your application deployed. It may also mention if you did or did not publish any Web services.
You can modify any fields and add additional configuration by returning to the OC4J Home page, select the application name in the Applications section. This brings you to a screen with the details of the deployed application.
From within this screen, you can view the Web and EJB modules. In addition, you can add and modify application-specific properties, resources, and security options in the Administration section. It is in this Administration section, that you can add application-specific data sources or security groups or users mentioned in the deployment wizard.
If the deployment process is interrupted for any reason, you may need to clean up the temp directory, which by default is /var/tmp, on your system. 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.
To change the temp directory, set the command-line option for the OC4J process to java.io.tmpdir=<new_tmp_dir>. You can set this command-line option in the Server Properties page. Drill down to the OC4J Home Page. Scroll down to the Administration Section. Select the Server Properties page. On this page, Scroll down to the Command Line Options section and add the java.io.tmpdir variable definition to the OC4J Options line. All new OC4J processes will start with this property.
You can remove a J2EE Web application from the OC4J Web server by selecting the application in the Applications section of the OC4J Home Page (see Figure 2-3) and clicking the Undeploy button. This command removes the deployed J2EE application and results in the following:
You can also undeploy applications with the DCM command. See Appendix A, "DCM Command-Line Utility (dcmctl)" for directions.
Note:
|
 Copyright © 2002 Oracle Corporation. All Rights Reserved. |
|