How-To: HTTPClient in Oracle Container
for Java EE 11 Technology Preview
First Publication: 10-Oct-05
Last Update: 20-Apr-07
Author: Frances Zhao
Introduction
Oracle Containers for Java EE 11 Technology Preview provides 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 Java EE 11 Technology
Preview, standalone version, with a web site configured
(default-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 Container for Java EE 11 Technology Preview.
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".
In addition, please make sure that the ant
command associated with the OC4J ant distribution is in your execution path (%ORACLE_HOME%/ant/bin).
Starting the OC4J Instance
Start a Oracle Containers for Java EE 11
Technology Preview instance as follows:
·
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.
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:
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:
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 Containers for Java EE 11 Technology Preview.
Bookmark
