Oracle Application Server J2EE Demonstration

Publish Date: September 2003

Table of Contents

Demonstration Name

FAQ Application

Description

This FAQ application demo provides support for managing Frequently Asked Questions (FAQs) and storing/retrieving them from an Oracle database. FAQs are broadly categorized into Specialization Areas. Each Specialization Area is further sub-categorized into Topics. A FAQ can be associated with multiple Specialization Areas which in turn have multiple Topics associated with them.

FAQs are of two types - Internal (to be published for internal users only) and External (to be published on external forums). Internal FAQs will include all external FAQs + internal FAQs.

Areas, Topics and FAQs are entered or updated in the database via Input/Update screens or via a corresponding Web service interface. Each Area, Topic and FAQ is uniquely identified by a primary key which is automatically generated by the system.

You can generate a list of FAQs (in HTML format) for a given Specialization Area for internal or external publication.

This application is a J2EE 1.3 compliant application, developed utilizing the following technologies:

Software Required

Oracle Application Server Components Required

In order to run this demo, Oracle Application Server Mid Tier Instance should have the following components configured:

This application can also be deployed and executed on OC4J standalone.

Other Software Required

Additionally, in order to run this demo, the following software components are required:

Configuration Instructions

Before you deploy the demonstration please ensure that the required components are up and running and configured appropriately. Use the following set of instructions to perform and validate the settings.

These instructions are based on a default install of the Oracle Application Server. The instructions assume you will install the demo into the home system component that is provided with the default installation. You may choose to create a new OC4J instance and install the FAQ Application within that instance, or you may use an existing OC4J instance you have previously created. If you do use an OC4J instance other than home, substitute the name appropriately within these instructions.

Database Configuration
Security Configuration
Data source Configuration

Database Configuration

Create the applications database tables by running the SQL table creation script CreateTables.sql. This script is located at <FAQApp_Home>\sql\CreateTables.sql.

In an Oracle database environment this can be done by running SQL*Plus, connecting to the database and schema where you want the tables to be installed (e.g. SCOTT/TIGER) and executing @CreateTables.

Once you have installed the application, the SQL creation script can also be accessed from the following URLs:

Please refer to the Oracle database documentation for further instructions on how to use SQL*Plus, running install scripts, creating database users/schemas, etc.

Take careful note of the database instance and connection information used to create the required schema objects. A Data Source will be configured for OracleAS which will allow it to connect to this database schema and the FAQ Application will make use of the tables and other objects created.

Security Configuration

This application uses Oracle's JAAS Provider, JAZN, for authentication and user access control capabilities. The FAQ Application is pre-configured with a default user. The username is faq and the password is faq. The default user details can be altered using Application Server Control. Additional users can also be added and granted privileges to access the FAQ Application.

Default FAQ User

Username: faq
Password: faq

Data Source Configuration

The FAQ Application uses a database to maintain its collection of FAQ information. The database that is used for this purpose is specified using a data source name specified within the application descriptor files -- jdbc/OracleDS. The jdbc/OracleDS data source must be configured to correspond to the database instance and schema where FAQ tables were installed.

Using Enterprise Manager

Using Application Server Control navigate to the home system component of the Oracle Application Server instance.



Within the home systems component select Administration tab at the bottom of the page.

On the Administration tab select the Data Sources link under the Application Defaults heading.

Edit the OracleDS data source and configure its properties so that it points to the database instance and schema where the FAQ Application tables were installed


This will most likely require making changes to the JDBC URL and Data Source username and password properties. Do not make any changes to the JNDI locations fields.


For more information about configuring data sources using Enterprise Manager see the Oracle Application Server Services documentation.

Data Source Configuration for OC4J Standalone

Configuring the required data source for OC4J standalone is a manual process requiring the editing of the data source configuration file. In this case, the data source configuration for the FAQApp application will be located in an XML file, data-sources.xml, located in the directory <OC4J_Instance>\j2ee\home\config where <OC4J_Instance> represents the root directory of the OC4J installation.

Open this file using a text editor and update the following three attributes of the data source which has a name of OracleDS to match the database configuration setup previously.

username="<application_database_schema_user_name>"
password="<application_database_schema_password>"
url="jdbc:oracle:thin:@<hostname_or_IP_Address>:<TNS_Listener_Port>:<Database_SID>"

Deployment Instructions

The FAQ Application distribution contains a pre-built EAR file which can be directly deployed to an Oracle Application Server installation. The deployment options available are shown below.

Deploying to Oracle Application Server using Application Server Control
Deploying to Oracle Application Server using Command Line
Deploying to OC4J standalone

Deploying to Oracle Application Server using Application Server Control

The FAQ Application can be deployed to an Oracle Application Server instance using Oracle Enterprise Manager Application Server Control.

Using Application Server Control navigate to the home system component of the Oracle Application Server instance.

Select the Applications tab at the bottom of the page.

Select the Deploy EAR file button and provide the details of the FAQ Application to be deployed. The FAQ Application is packaged as a deployable J2EE archive named FAQApp.ear in the <FAQApp_Home>dist directory. Use the browse button to locate the file on your local file system.



Select the Finish button on the next page of the deployment wizard to finish entering the deployment details for the application.

Select the Deploy button to perform the installation of the EAR file.



The FAQApp will be deployed to the OC4J home instance. When it completes you will be notified by Application Server Control.


Deploying to Oracle Application Server using Command Line

The FAQ Application can be deployed to an Oracle Application Server instance using the command line utility dcmctl. To deploy the application, use the following command:

> <ORACLE_HOME>\dcm\bin\dcmctl deployapplication -file <FAQApp_Home>\dist\FAQApp.ear -a FAQApp

where <ORACLE_HOME> is where Oracle Application Server is installed. and <FAQApp_Home> is the directory created when the FAQ Application zip file was extracted.

Deploying to OC4J Standalone

The FAQ Application can be deployed to OC4J standalone using the supplied Ant build script. Perform the deployment by setting the environment up for performing a build and then typing the command:

> ant deploy

and pressing return. Please refer to the Build Instructions for setup information.

The FAQ Application can also be deployed to OC4J standalone by copying the FAQApp.ear file into the <OC4J_Instance>/j2ee/home/applications directory and editing two server configuration files to add the following lines:

Configuration File: <OC4J_Instance>/j2ee/home/config/server.xml:

<application name="FAQApp" path="../applications/FAQApp.ear" auto-star t="true" />

Configuration File: <OC4J_Instance>/j2ee/home/config/default-web-app.xml

<web-app application="FAQApp" name="FAQAppWeb" root="/FAQApp" />
<web-app application="FAQApp" name="FAQAppWebService" root="/FAQAppWebService" />

Running the Demonstration

Once the FAQ Application has been deployed, you can access the FAQ Application by opening the requisite URL shown below in a browser:

Re-Building Instructions

The FAQ Application is distributed with a pre-built EAR file which is ready to deploy -- there is no need to build the EAR file in order to deploy the application. These instructions are only necessary if you would like to change or update the functionality within the FAQ Application.

Downloading the Source Code
Build Instructions

Downloading the Source Code

The source code for the FAQ Application can be downloaded from the Oracle Technology Network (OTN). The FAQApp.zip file should be unzipped to a working directory, from this point forward referred to as <FAQApp_Home>. The source code for the application is contained in the src directory, corresponding to the modules within the application.

Build Instructions

The FAQApp application is designed to be compiled using the build tool Jakarta Ant. This can be downloaded from Jakarta Apache.

1. Edit the file <FAQApp_Home>\common.xml using a text editor to reflect the configuration changes:

a. JAVA_HOME - location of the Java Development Kit (JDK) that will be used to compile the application
b. ORACLE_HOME - location of where the Oracle Application Server is installed
c. J2EE_HOME - location of the Oracle Application Server J2EE files (normally <ORACLE_HOME>\j2ee\home)

2. If using OC4J standalone, edit the <FAQApp_Home>\build.xml using a text editor to reflect the following changes.

a. Update <property name="deploy.ormi" value="ormi://localhost" /> to reflect your host machine
b. Update <property name="deploy.username" value="admin" /> to relect your administrator account
c. Update the <property name="deploy.password" value="welcome" /> to reflect your administrator password

3. Set the environment variable JAVA_HOME to the location of the JDK that will be used to compile the application

4. In the <FAQApp_Home> directory type the command:

> ant

If any errors occur generally this is because of configuration errors in step one. Correct these and run until a successful build occurs.

Other Demonstrations of Interest

Please refer to the Oracle Application Server OC4J/J2EE demo download area on OTN for further OC4J/J2EE related demos.