How-To: HTTPClient in Oracle Application Server 10g (10.1.3)

First Publication: 10-Oct-05
Last Update: 16-Jan-06
Author:  Frances Zhao

Introduction

Oracle Application Server and OC4J 10g (10.1.3) provide the HTTPClient Java package as a complete HTTP client library. It currently implements most of the relevant parts of the HTTP/1.0 and HTTP/1.1 protocols, including the request methods HEAD, GET, POST and PUT, and automatic handling of authorization, redirection requests, and cookies. Furthermore the included Codecs class contains coders and decoders for the base64, quoted-printable, URL-encoding, chunked and the multipart/form-data encodings.

This how-to illustrates a few basic features of the HTTPClient package with different JSPs, like the GET method and cookies.

What are the Prerequisites?

What you should know?

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's JDK 1.5.0 or above, available from here
  • Apache Ant 1.6.2 or above, to build the application, available from here
  • 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?

General Information

Using the HTTPClient is quite simple and usually involves the following steps:

  • First add the import statement import HTTPClient.*; to your file(s).
  • Next you create an instance of HTTPConnection (you'll need one for every server you wish to talk to).
  • Requests can then be sent using one of the methods Head(), Get(), Post(), etc in HTTPConnection. These methods all return an instance of HTTPResponse.
  • Use HTTPResponse's methods for accessing the response headers (getHeader(), getHeaderAsInt(), etc), various response info (getStatusCode(), getReasonLine(), etc), the response data (getData(), getText(), and getInputStream()) and any trailers that might have been sent (getTrailer(), getTrailerAsInt(), etc).


Including HTTPClient in your application's classpath

You must include the %ORACLE_HOME%/j2ee/home/lib/http_client.jar in your application's classpath in order to use the HTTPClient package. This how-to uses JSPs that utilize the HTTPClient after deployment, thus making it necessary to add the above jar to this application's orion-application.xml, using the <library> element.

Here is the additional classpath declaration, which can be found in the orion-application.xml under %HOWTO_HOME%/etc.

<orion-application>
  <library path="../../lib/http_client.jar"/>
</orion-application>

JSP httpclient_basic.jsp

This JSP illustrates the basic features of HTTPClient. It uses the HTTP GET method to first retrieve an existing HTML page and displays it, and then retrieves a non-existing HTML page to correctly report an error. The JSP is under %HOWTO_HOME%/src/web/content/httpclient_basic.jsp.

Here are the key operations in this JSP code:

  • Construct an HTTPConnection object, with specified host and port information. For this how-to, the host is 127.0.0.1 and the port is the default 8888 for standalone OC4J. Modify the port to the http server port if you are using an OracleAS environment (see ant-oracle.properties for examples).
  • Obtain an HTTPResponse object by invoking the Get() method on this HTTPConnection, which effectively sends an HTTP request using the GET method.
  • From the HTTPResponse object, check the response status code using getStatusCode().
  • Retrieve the actual HTML page content with HTTPResponse.getText().


JSP httpclient_cookie.jsp

This JSP illustrates HTTPClient cookie handling functions, which are available in HTTPClient.CookieModule, such as cookie creation, storage, retrieval, and policy handler setting. The JSP is under %HOWTO_HOME%/src/web/content/httpclient_cookie.jsp.

Here are some key operations in this JSP code:

  • Construct a cookie HTTPClient.Cookie and pass it to HTTPClient.
  • Disable the default cookie policy handler so that all cookies are accepted. This is done by HTTPClient.setCookiePolicyHandler(null).
  • Send an HTTP request to invoke another JSP httpclient_svr.jsp, which will store a new cookie.
  • Checks all the stored cookies by invoking HTTPClient.CookieModule.listAllCookies(). This should reveal the new cookie stored by the separate JSP.


JSP httpclient_svr.jsp

This JSP is invoked by httpclient_cookie.jsp. It stores a new cookie with the HTTP response, for the invoking JSP to check. In doing so, it uses the standard javax.servlet.* APIs, and does not use the HTTPClient package. The JSP also outputs to OC4J console the cookies set from HTTPClient before sending response back.

More HTTPClient examples

For more examples on HTTPClient's basic and advanced features, check out the following link:



How to Run 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
    • how-to-httpclient.html - this How-to page
  • src - the source of the demo
    • web - contains HTML pages and the JSP 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".
%ORACLE_HOME%/ant/bin

Configuring the Environment for a Managed OracleAS Instance

g
  • 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

g

  • Stand Alone Installation: %ORACLE_HOME%/bin/oc4j start
    Note that the oc4j command expects the JAVA_HOME environment variable to point to a full JDK installation.

  • OracleAS Managed Installation: %ORACLE_HOME%/opmn/bin/opmnctl startall

Generating, Compiling and Deploying the Application

Build Script Setup

Ensure Ant 1.6.2 or above is installed on your machine and configured correctly. On some operating systems Ant does not currently support the use of environment variables. If this is the case for your operating system, please modify the common.xml file located in the top-level %HOWTO_HOME% directory.

Build the Application

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

  • ant

You should now have newly created httpclient_demo.ear in your %HOWTO_HOME%/dist 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:

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

There are two buttons shown. Clicking the first button would invoke a JSP testing the basic feature of HTTPClient; clicking the second button would invoke a JSP testing the cookie functions provided in HTTPClient. A new page would show the test logs, or if an exception has occurred. There would be a back link on the new page that brings you back to this page.

Summary

In this document, you should have:

  • Learned how to use HTTPClient provided by Oracle Application Server and OC4J 10g (10.1.3)

Left Curve
Popular Downloads
 Right Curve
Untitled Document