10g (9.0.4)
Part Number B10322-01
 Home |
 Solution Area |
 Contents |
 Index |
| Oracle Application Server Containers for J2EE User's Guide 10g (9.0.4) Part Number B10322-01 |
|
This chapter demonstrates how to configure and execute OC4J as simply and quickly as possible. You installed OC4J with the Oracle Application Server 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 FAQ application demo.
This chapter includes the following topics:
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 Oracle Application Server 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.
Off the Application Server Control, you can drill down to any of the running OC4J instances by selecting the name of the instance (home, for example) in the System Components table. The Application Server Control displays the OC4J Home Page for that instance.
Figure 2-1 shows portions of the OC4J Home Page for the home instance.
The OC4J Home Page shows metrics on your OC4J instance and its applications. In addition, you can start, stop, and restart all OC4J processes configured to this instance.
From the OC4J Home Page, you can navigate to the following pages:
Figure 2-2 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 "Deploying Applications" for more information.
As an example, you can see how the FAQ application demo is configured and deployed to OC4J in "Configuring the FAQ Application Demo".
Figure 2-3 shows the Administration page. You can modify the following:
Details for each of these options are covered in "Configuring OC4J Using Oracle Enterprise Manager".
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 with one of the following methods:
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 any of the options off of the Administration page.
You can also start, stop, and restart using the DCM control command. See the Distributed Configuration Management Reference Guide for directions.
Start OC4J with the defaults, as follows:
http://<ohs_host>:7777/j2ee/j2ee-index.html
Substitute the name of the host where the OHS is installed for <ohs_host>.
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-4 demonstrates this structure.
Consider the following points regarding Figure 2-4:
META-INF, WEB-INF, application.xml, ejb-jar.xml, web.xml, and application-client.xml.
application.xml file, which acts as the standard J2EE application descriptor file, defines these modules.
ejb_module>, <web_module>, and <client_module>) can have arbitrary names. However, these names must match the values in the standard J2EE application descriptor 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 the FAQ J2EE demo application, which provides support for managing Frequently Asked Questions (FAQs) and storing/retrieving these FAQs from an Oracle database. 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.
FAQs are broadly categorized into Specialization Areas. Each Specialization Area is further sub-categorized into Topics. Each FAQ can be associated with multiple Specialization Areas, where each area has one or more Topics associated with them.
You can generate a list of FAQs (in HTML format) for a given Specialization Area for internal or external publication.
Within the demo, Areas, Topics, and FAQs are entered or updated in the database through Input/Update screens or through a Web service interface. Each Area, Topic and FAQ is uniquely identified by a primary key, which is automatically generated by the system.
This application is a J2EE 1.3 compliant application, developed utilizing the following technologies:
The following sections detail how to configure and deploy the FAQ demo application. In addition, the last section demonstrates how these steps relate to any application that you may wish to configure and deploy to OC4J:
In order to execute the FAQ demo, you must modify the back-end database to contain tables that the demo uses.
Add the FAQ user and tables, as follows:
faq user with password of faq in your database.
CreateTables.sql script, which is located at <FAQApp_home>/faq/sql/CreateTables.sql or can be downloaded with the rest of the FAQ application from OTN in the FAQApp.zip file.
In an Oracle database environment, you can execute the SQL script through SQL*Plus, connecting to the database and schema where you want the tables to be installed and executing @CreateTables. Please refer to the Oracle database documentation for further instructions on how to use SQL*Plus, running install scripts, creating database users/schemas, and so on.
In order for the FAQ demo to execute properly, the following system modification must be implemented:
OracleDS, to point to the back-end database.
jazn.com realm and assign it to the users role.
The directions for each of these steps are covered in the following sections:
In order to execute the FAQ application, you must have an Oracle database with the corresponding FAQ application database schema installed on it. The FAQ Application uses the default global data source named OracleDS that ships with the application server, which must be configured so that it connects to the database in which you created the FAQ tables.
OracleDS data source, click the Edit button. This brings up the configuration information for this data source. Modify the JDBC URL, driver, username, and password to point to your back-end database.
When finished, click the Apply button.
If your back-end database uses the thin JDBC driver, is located at myhost:1521:ORCL, and uses the username/password of faq/faq, then the j2ee/home/config/data-sources.xml file is modified to point to the database at the URL of jdbc:oracle:thin:@myhost:1521:ORCL, as follows:
<data-source class="com.evermind.sql.DriverManagerDataSource" name="OracleDS" location="jdbc/OracleCoreDS" xa-location="jdbc/xa/OracleXADS" ejb-location="jdbc/OracleDS" connection-driver="oracle.jdbc.driver.OracleDriver"username="faq"password="faq"url="jdbc:oracle:thin:@myhost:1521:ORCL"inactivity-timeout="30" />
See Chapter 4, "Data Sources Primer" for more information on data sources.
The FAQ demo uses Oracle Application Server Java Authentication and Authorization Service for authentication and user access control capabilities.
jazn.com realm.
When finished, click the Apply button.
Alternatively, an application user is added to the default jazn.com realm through the jazn.jar command line tool, as follows:
> java -jar jazn.jar -adduser jazn.com <username> <passwd>
> java -jar jazn.jar -grantrole users jazn.com <username>
The previous adds your user (given the username and password) to the jazn.com realm and then grants the users role to the new user. See the Oracle Application Server Containers for J2EE Security Guide for complete information on using OracleAS JAAS Provider as your security provider.
Download the FAQ demo application from OTN in the FAQApp.zip file.
<FAQApp_Home>.
FAQApp.ear file that you unzipped on your system. Type "FAQApp" in the application name field. Click the Continue button.
/FAQApp servlet context. Type "/FAQApp" in the URL mapping field and click the Next button.
FAQApp" in the Name column of the Applications section. This shows the configuration and all deployed modules of the FAQApp demo application. If the OC4J server is started, the application is automatically started.
http://<ohs_host>:7777/FAQApp
The FAQApp screen appears.
Although the development of J2EE applications is standardized and portable, the non-application (server) configuration is not. The necessary server configuration 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 the FAQ demo, you would configure the following:
META-INF/application.xml--The standard J2EE application descriptor for the application is contained within the application.xml file. This file must be properly configured and included within the J2EE EAR file that is to be deployed.
DataSource object in the Data Source configuration page for each database used within the application.
To create and deploy simple J2EE applications, perform the following basic steps:
The following steps describe what modifications to make to deploy the FAQ demo application into OC4J.
|
Note: Displays of the screens for each step of the deployment wizard are shown in "Deploying Applications". |
JAVA_HOME variable to the base directory of the Java 2 SDK.
<FAQAPP_Home> directory:
ant all
The ANT build.xml is included in the FAQ ZIP download. To learn more about the ANT file, go to the following Jakarta site:
http://jakarta.apache.org/ant/
http://oc4j_host:7777/FAQApp
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-2 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 standard J2EE application descriptor file.
Both of these buttons start an 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-6 shows the first page, which enables you to provide the following:
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> parent="applicationWithCommonClasses"
path=<path_EARfile> auto-start="true" />
where
name variable is the name of the application you provided.
parent is the name of the optional parent application. The default is the global application. Children see the namespace of its parent application. This setting is used to share services, such as EJBs among multiple applications.
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 Continue button to go to the next step in the wizard deployment process. The wizard uploads your EAR file and examines the application. Based on your configuration files and deployment descriptors, the wizard dynamically presents only the configuration screens your application needs. These screens are a subset of the steps presented in the following sections:
Map any Web modules in your application to a specific URL for its servlet context. 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.
The EJBs in your application can have IIOP stubs generated by selecting Generate IIOP Stubs. See the "Interoperability and RMI Tunneling" chapter in the Oracle Application Server Containers for J2EE Services Guide for information on IIOP stubs.
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.
If you have any MDBs in your EAR file, you may be required to add information about the subscriptions or topics. If you are defining DataSource objects for CMP entity beans, you are given the option to add a JNDI location for those DataSource objects.
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 OracleAS JAAS Provider XML User Manager.
As Figure 2-11 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.
principals.xml file.
For more information on security and User Managers, see the Oracle Application Server Containers for J2EE Security Guide.
Publish any OracleAS Web Services defined in your application. This feature requires the UDDI registry. OracleAS Web Services are not installed with a core install.
If you have defined any OracleAS Web Services, they are shown in the following screen:
If you want to publish these OracleAS Web Services, then click on the Publish button. This leads you through the process of publishing your OracleAS 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 review 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.
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 Server Properties. 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-2) 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 the Distributed Configuration Management Reference Guide for directions.
Note:
|
 Copyright © 2002, 2003 Oracle Corporation. All Rights Reserved. |
|