Introduction
Application Overview
Software Requirements
Terminology
Configuring the Application
Deploying and Running the Application
Sample Application Files
TroubleShooting
Additional References

Introduction

• Prerequisite
  
  
• Technical Overview

Prerequisite

• JSP
  
  
• EJB

Technical Overview

In a typical enterprise J2EE application business entities are represented using Enterprise Java Beans. Application clients need access to business objects to fulfill their responsibilities and to meet user requirements. If EJB clients (swing, servlets, jsps etc) access entity beans directly over the network, the following problems may be observed :

• To carry out a workflow, client objects must make numerous remote calls to access the EJBs, leading to increased network traffic and reduced performance.
  
• Tight coupling makes the client directly dependent on the implementation of the business objects - meaning when an EJB's interface changes, client objects must also be updated
  
• As client requirements increase, the complexity of interaction between various business objects increases
  
• Lack of a uniform client access strategy, exposing business objects to misuse

• Reduces coupling and interdependencies thereby increases manageability
• Centralizes and aggregates all business logic that needs to be exposed to remote clients
• Improves performance by reducing fine-grained method access and provides coarse-grained access
• Centralizes security management
• Centralizes transaction control

Application Overview

This sample application demonstrates the use of Session Facade design pattern in a typical HR application. Two local CMP ( Container Managed Persistence ) EJBs, Employees and Departments are used to store and retrieve employee and department information from the database. All method calls to the entity beans are routed through the stateless session bean, HRSessionEJB, which acts as a facade over these two entity beans. This effectively reduces the network traffic, rather the client making many fine-grained method calls on the entity beans to retrieve or store data in the database.
In this application only the admin user is allowed to add a new department. In the ejb-jar.xml, the addNewDepartment() method is configured such that users only from the admin role are given the permission to access this method. When a user from any other role tries to access this method, the application throws a RemoteException, informing the user about the security restrictions. This is an example of using this pattern to centralize the security management.
In addition, the application allows the user to add a new department and assign existing employees to the newly added department. As this involves accessing two different entities, it should take place in one transaction. The addNewDepartment method in the session bean and create methods in the entity beans are configured with the 'Required' transaction attribute which makes sure that the data is committed only in case of a record is added or updated in both the tables successfully. This is an example of centralized transaction control.


The following class diagram shows the important classes and their relationship in the Session Facade design pattern. Here the JSPs invoke required methods on the ClientBean, which uses the HRSessionEJB to retrieve or update data from the Departments and Employee EJBs.

Software Requirements

List the softwares required for configuring and running this sample application.

• Oracle JDeveloper 10g
• Oracle Containers for J2EE (OC4J) - version 9.0.4
  and ANT - version 1.5 or above for building the EAR file
  and J2ESDK1.4.x
• Oracle Database 10g
  

Terminology

Term	Definition
<OC4J_HOME>	The directory where OC4J is installed. For e.g., D:\oc4j
<J2EE_HOME>	The directory j2ee/home under <OC4J_HOME>. For e.g., D:\oc4j\j2ee\home
<JAVA_HOME>	Directory where JAVA is installed
<ANT_HOME>	Directory where Apache Ant is installed
<ORACLE_HOME>	The directory where Oracle Database is installed

Configuring the Application

• Download, Unzip and extract the SessionFacade.zip file into your <SAMPLE_HOME> folder. This creates SessionFacade folder with all the source files.
• To setup the database connection, edit the data-sources.xml file under the <SAMPLE_HOME>\SessionFacade\src\META-INF directory.
  Replace <dbHostName>:<dbPort>:<dbSID> in the url, with your database values and save the file.
  
  

  dbHostName	=	hostname of the machine where Oracle database is running
  dbPort	=	port on the host machine on which the database listener is listening
  dbSID	=	SID of the database

  
  Note: This sample application uses HR sample schema in the database. If the HR account is locked, open the SQL command prompt, login as 'sys' user and issue the following command to unlock the HR account.
  SQL>ALTER USER hr ACCOUNT UNLOCK;
  

Deploying and Running the Application

The application can be deployed and run in either of the following ways:

• Run the Application using Oracle JDeveloper 10g
  
  
• Run the Application using standalone OC4J

Run the Application using JDeveloper 10g

This section describes the steps required in deploying and running this application inside embedded OC4J using Oracle JDeveloper 10g.

• To set password for the default user, open jazn-data.xml from the <JDEV_HOME>/jdev/system<version.number>/oc4j-config folder and edit the credentials for the "Default User" as below.
  Note: version.number is the version of your JDeveloper 10g. Example for JDeveloper version 10.1.3 build 223, the system folder may be system10.1.3.223
  

  <user>
     <name>user</name>
     <description>The default user</description>
     <credentials>!welcome</credentials>
  </user> 
       
  

• Open Oracle JDeveloper 10g and use File/Open option to select the SessionFacadeWS.jws from the SessionFacade directory
  
  
• Next, select Project/Make SessionFacade.jpr from main menu
  
  
• Now, select Run/Run SessionFacade.jpr from main menu which opens up the browser and runs the SessionFacade application
  
  
• You will be prompted for the UserName and Password. Enter user/welcome or admin/welcome and proceed.
  Note: When you login as user add a new department by assigning employees, you will get an exception because the security configuration do not allow the 'user' to access the addNewDepartment() method in the HRSessionEJB bean.
  
  
• If you encounter any problems refer to the TroubleShooting section

Run the Application using standalone OC4J

This section describes the steps required in deploying this application to the Standalone OC4J using ANT Tool and running using the browser.

Note: Make sure that the environment variables[<JAVA_HOME>, <ANT_HOME>/bin in the PATH;, <JAVA_HOME>/bin in the PATH] have been set before proceeding further. For more information on how to setup these environment variables, please refer environment set up readme document.

• To set password for the default user, open jazn-data.xml from the <J2EE_HOME>/config folder and edit the credentials for the "Default User" as below.

  <user>
     <name>user</name>
     <description>The default user</description>
     <credentials>!welcome</credentials>
  </user> 

• Ensure that OC4J is up and running. To start the OC4J server, navigate to <J2EE_HOME> and execute the following command,
  > java -jar oc4j.jar
• Open the SessionFacade/config/server.properties in a text editor. Change the following parameters to with your OC4J details.
  

  OC4J_HOME	=	Folder where OC4J is installed. Ex: e:/oc4j10g
  OC4J_HOST	=	Machine name or IP address on which OC4J is running
  OC4J_PORT	=	ORMI port on which your OC4J listens for ORMI requests
  OC4J_USERNAME	=	User name of OC4J server, default is admin.
  OC4J_PASSWORD	=	Password of OC4J server.

  
  
• Build and deploy the EAR file using ANT. From SessionFacade directory, execute the ant command,
  > ant
  
  
• Open your favorite browser and access the sample application, using the following URL,
  http://hostName:port/SessionFacade/addDepartments.jsp
  
  where,
  <host_name> is the machine on which OC4J is running and <port> is Port in which the OC4J server listens to HTTP requests. By default OC4J listens for HTTP requests in port # 8888
  Example:http://localhost:8888/SessionFacade/addDepartments.jsp
  
  You will be prompted for the UserName and Password. Enter user/welcome or admin/welcome and proceed.
  Note: When you login as user add a new department by assigning employees, you will get an exception because the security configuration does not allow the 'users' to access the addNewDepartment() method in the HRSessionEJB bean.
  
  
• If you encounter any problems refer to the Troubleshooting section
  

Sample Application Files 

This section provides a tabular listing of the sample application files, along with their respective directory locations and description.

Directory	File	Description
SessionFacade\doc	Readme.html	This file
SessionFacade\src\oracle\otnsamples\facade	*Java	Java source files used in this sample application
SessionFacade\src\oracle\otnsamples\facade\ejb	*Java	The EJB source files
SessionFacade\public_html	*.jsp	JSP files used in this sample application
SessionFacade\public_html\WEB-INF\web.xml	web.xml	Web deployment descriptor
SessionFacade\config	Connection.properties	The properties file that holds the database details
SessionFacade\src\META-INF	*.xml	Application deployment descriptors
SessionFacade	build.xml	The ANT build file

Troubleshooting 

Additional References 

• Java BluePrints - Session Facade
• Design Patterns for Optimizing the Performance of J2EE Applications
• Patterns repository on OTN
  
  

Please enter your comments about this sample application here.