How-To Use Servlet 2.4 Features in OC4J 10g (10.1.3)

First Publication: 01-Nov-04
Last Update: 16-Jan-06
Author: Frances Zhao

• Introduction
• What are the Prerequisites?
  • What Should You Know?
  • What are the Software Requirements?
  • What are the Notations?
• How to Build the Application?
  • Setting a Servlet as Welcome File
  • Using New Listener Interfaces
  • Using New Methods in ServletRequest
• How to Run the Application?
  • Examining the How to Distribution
  • Setting up the Application
  • Running an OC4J Instance
  • Generating, Compiling and Deploying the Application
  • Running the Application
• Summary

Introduction

This demo illustrates some of the Servlet 2.4 features supported by OC4J:

• Servlet as welcome file
• New listener interfaces like ServletRequestListener
• New methods in ServletRequest

What are the Prerequisites?

What you should know

• You should be familiar with these technologies: Servlet, JSP;
• Link to other OC4J Howto's on OTN

What are the Software Requirements?

This demo requires that the following sofware components are installed and configured correctly:

• Oracle Containers for J2EE 10g (10.1.3) , standalone version, with a web site configured (example http-web-site)
• Sun JDK 1.4_02 or above.
• Any HTML browser like Mozilla, Microsoft Internet Explorer, Netscape, etc.

What are the Notations?

• %ORACLE_HOME% - The directory where you installed OC4J.
• %JAVA_HOME% - The directory where your JDK is installed
• %HOWTO_HOME% - The directory where this demo is unzipped

How to Build the Application?

Setting a Servlet as Welcome File

With Servlet 2.4, you can now have a servlet as a welcome file, which is useful for applications that use servlets as "Front Controllers". To do that, you first define the servlet in web.xml. From the web.xml file in this How-to:

 <servlet>
  <servlet-name>DemoServlet</servlet-name>
  <servlet-class>web.DemoServlet</servlet-class>
 </servlet>
 <!-- optional -->
 <servlet-mapping>
  <servlet-name>DemoServlet</servlet-name>
  <url-pattern>/demoservlet</url-pattern>
 </servlet-mapping>

Then you create a welcome-file element in web.xml that specifies the above servlet name. Like:

<welcome-file-list>
  <welcome-file>DemoServlet</welcome-file>
</welcome-file-list>

As shown in the %HOWTO_HOME%/etc/web.xml, you can also define an alternative welcome file at the same time, which will be used if the servlet can not be found in the web application.

Using New Listener Interfaces

Servlet 2.4 provides two new listener interfaces that you can use for HTTP requests: javax.servlet.ServletRequestListener and javax.servlet.ServletRequestAttributeListener. This demo application only implements the former and would print out log messages to the OC4J console whenever the configured servlet DemoServlet is activated.

For the implemented listener, each time the web application receives a new request, the listener is notified and its requestInitialized() method is called. This method's parameter is a javax.servlet.ServletRequestEvent type. Calling this object's getServletRequest() method gives the developer access to the new request, a javax.servlet.ServletRequest type (to do whatever they want with the new request). See %HOWTO_HOME%/src/web/java/ServletReqLsnr.java for details.

The implemented listener must also have a constructor with no arguments. You define your implemented listener in web.xml, like:

<listener>
  <listener-class>web.ServletReqLsnr</listener-class>
</listener>

Using New Methods in ServletRequest

Servlet 2.4 adds some new methods to the ServletRequest interface:

• getRemotePort(): Returns the IP source port of the client or last proxy that sent the request
• getLocalName(): Returns the host name of the IP interface on which the request was received
• getLocalAddr(): Returns the IP address of the interface on which the request was received
• getLocalPort(): Returns the IP port number of the interface on which the request was received

These methods provide a mechanism to query the low-level IP connection details and understand how the connection routed. This How-to application also calls these methods as illustration, as in %HOWTO_HOME%/src/web/java/DemoServlet.java.

How to Build the Application?

The following instructions are for running this demonstration on a standalone instance of Oracle Containers for J2EE 10g (10.1.3).

Examining the How to Distribution

• build - temporary directory created during the build
• log - temporary directory holding build/deploy logs
• etc - all necessary files to package the application
• lib - holds the application archives that could be deployed (e.g., ear, war, rar, jar files)
• doc - the How-to document and Javadoc's
• • javadoc - the javadoc of the different source files
  • how-to-web-servlet-intro..html - this How-to page
• src - the source of the demo
  • web - contains HTML pages and Servlet code

Setting Up the Application

Environment Configuration

Please check to make sure that the following properties are configured correctly in the ant-oracle.properties file located in the root of the sample's distribution (NOTE:  Some of these properties will default to the values of corresponding environment variables as noted below.  If you have these variables setup in your environment you may not have to alter the values in the file).  If necessary, modify these variable to the proper values for you environment:

• oracle.home - the root directory of oracle installation.  Defaults to ORACLE_HOME environment variable.
• java.home -  the root directory of JDK installation.  Defaults to JAVA_HOME environment variable.
• oracleas.host - the hostname of the platform on which the OC4J instance is running.  Defaults to localhost.
• oracleas.http.port - the port on which the OC4J HTTP listener is listening.  Defaults to 8888.
• oracleas.admin.port  - the port on which the OC4J administration processor is listening.  Defaults to 23791.
• oracleas.admin.user - the name of the OC4J administrator.  Defaults to " oc4jadmin".
• oracleas.admin.password - the password for the OC4J administrator.  Defaults to " welcome".
• oracleas.binding.module - the name of the HTTP web site to which the deployed application is bound.  Defaults to " default-web-site".

Configuring the Environment for a Managed OracleAS Instance

• oracleas.http.port - the port on which the Oracle HTTP Server (OHS) is listening.
• oracleas.admin.port  - The OPMN request port, as specified in opmn.xml, the default value is 6003.  You can also check the OPMN request port using the following command: %ORACLE_HOME%/opmn/bin/opmnctl status -port
• oracleas.admin.user - the name of the OC4J administrator.  Defaults to " oc4jadmin".
• oracleas.deployer.uri - the URI to use to do the different administration operation (deployment, undeployment). The file contains different URI depending of the topology of your application: stand alone OC4J, Managed Single Node or Managed Cluster. You just need to un-comment the URI that matches your toplogy.
• oracleas.oc4j.instance - This is the managed OC4J instance where the application will be deployed or undeployed.

Starting the OC4J Instance

Generating, Compiling and Deploying the Application

Build the Application

In the top-level %HOWTO_HOME% directory, type the command:

• ant

You should now have newly created servlet_demo.ear and servlet_demo-web.war in your %HOWTO_HOME%/lib directory.

This command would also attempt to deploy the application if the build is successful. It will first test whether OC4J is running.

Deploy and Bind the Application

You can also deploy and bind the application separately by using the following command. Make sure the %ORACLE_HOME% environment variable is defined. In the top-level %HOWTO_HOME% directory, type the command:

• ant bind-web-app

Running the Application

In a browser window, browse to:

• http://localhost:8888/servlet_demo

If the website hostname or port number are different, then use those values instead.

Alternatively, you can use this link to access the demo servlet. Reload the page several times. Check the result page, but also watch the demo listener updating the log in the OC4J console.

Summary

In this document, you should have:

• Known that OC4J 10.1.3 fully supports Servlet 2.4
• Learned how to use some of the Servlet 2.4 features that OC4J supports