How to retrieve HTTP
Request variable using ESI tags
After completing
this How-To you should be able to:
Use ESI tag to
retrieve the HTTP request variable.
Run the sample code to do the same using the
instructions provided.
Introduction
Edge
Side Includes (ESI) is XML based markup language used to define web page components
for dynamic assembly and delivery at the edge of the Internet. ESI compliant Servers
like OracleAS Web Cache caches and assembles partial pages defined by the ESI
tags. ESI supports some of the HTTP header variables to be processed in the ESI
Compliant servers. HTTP headers come along with the client request. These HTTP
headers can be used as ESI variables with the following convention.
"HTTP_" is prefixed to the HTTP variable name.
Dashes
(-) are replaced with underscore (_).
The
variable must be in upper case.
To refer
to a variable, you need to prefix these variables with the $ sign and surround
the variable name with parenthesis like $(HTTP_VARIABLE).
For
example, host variable is referred to as $(HTTP_HOST), referer variable is referred
to as $(HTTP_REFERER).
To access the substructure of a variable, append
the variable name with braces containing the key that can be accessed like $(HTTP_VARIABLE{key}).
Substructure makes sense for certain variables only like $(HTTP_COOKIE{cookieName}),
$(HTTP_USER_AGENT{browser}). Key based access
is allowed for all variables consisting of logical key-value pairs. The key is
case sensitive and optional and if the key is not specified, the environment variable
returns the whole content of the environment fragment.
For example, cookie variable is referred to as $(HTTP_COOKIE{cookieName}). This
will give the value of cookie, cookieName. ESI supports virtual keys like browser,
version and os, are accepted on HTTP_USER_AGENT. So $(HTTP_USER_AGENT{browser}), $(HTTP_USER_AGENT{version}),
$(HTTP_USER_AGENT{os}) will return the browser name, version and operating system
of the client respectively. When the key
values do not exist, logical 'OR'(|) operator can be used to set the default values
for these variables. For example, use $(HTTP_VARIABLE|default) for normal HTTP
variable and $(HTTP_VARIABLE{key}
| 'default value') form for substructured HTTP variables.
Description
This sample application has two web pages viz., welcome.html
and the display.jsp . Information like cookie value
and query string can be entered in the first page: welcome.html
. This page stores the cookie value in cookie named 'cookievariable' and query
string is stored in variable named 'query'. welcome.html
has a submit button which when pressed, submits the form and forwards the request
to display.jsp . display.jsp is dynamic web page that shows the information
stored in the HTTP header and the page generation time.
Without any
cache server, this page will be generated for every request. But by using these
ESI tag these requests are handled at OracleAS Web Cache itself. ESI Processor
retrieves the user information stored in the cookies/HTTP headers and substitutes
them in the dynamic page cached in the cache server. The dynamic content is requested
only once and served multiple times by the cache server. This can be visualized
by the time stamp generated in the dynamic page. In our example, we set this page
expiration time to 60 seconds but this could be changed according to the system
requirement. Any request that comes after this expiration time will be routed
to the origin server. The origin server regenerates the page again and caches
it in OracleAS Web Cache. Succeeding client requests for the page are served from
OracleAS Web Cache instead of serving it from the origin server.
Let us have a look at,
some of the code snippets that are used in the current application. Following
table shows how to retrieve HTTP request variables and display them using ESI
tags. These variables are interpreted only when they are enclosed within some
ESI tag like <esi:vars>, <esi:include> etc.
HTTP Header Variable
Description
Code Snippet
$(HTTP_COOKIE{hits}|''Cookie
Does Not Exist')
This variable will display the value of hits cookie. If hits cookie is not
found in the request header, then it's default value is printed.
<td align="left" valign="top"> <esi:vars>$(HTTP_COOKIE{hits}|"Cookie
Does Not Exist")</esi:vars>
</td>
$(HTTP_ACCEPT_LANGUAGE{en}|'No en Language')
This variable will display the value of language set for the client
browser. If the browser language is set to en, then the request header will contain
the expression like Accept-Language:en, so this variable will return en
in the output.
<td align="left" valign="top">
<esi:vars>$(HTTP_ACCEPT_LANGUAGE{en}|'No en Language')</esi:vars>
</td>
$(HTTP_HOST)
HTTP_HOST
request-header field specifies the host name and the port number of the client
request.
$(HTTP_USER_AGENT{version}|'Can Not Find The version')
This
variable specifies the browser version of the client. If the browser version could
not be found from the request header, its default value 'Cannot Find The version'
is displayed.
<td align="left" valign="top"> <esi:vars>$(HTTP_USER_AGENT{version}|'Can
Not Find The version')</esi:vars> </td>
$(HTTP_USER_AGENT{os}|'can Not Find The os')
Displays the operating system
of the browser like windows/Linux. And if os key is not found in User-Agent
request variable than its default value is displayed.
<td align="left" valign="top"> <esi:vars>$(HTTP_USER_AGENT{os}|'can
Not Find The os')</esi:vars> </td>
$(HTTP_HEADER{referer}|'referer
Not Found')
This
variable will display the HTTP header for a given key so this Will show the value
of HTTP request header variable whose key is referer. If the referer key is not
found, its default value is displayed.
<td align="left" valign="top"> <esi:vars>$(HTTP_HEADER{referer}|'referer
Not Found')</esi:vars> </td>
$(HTTP_HEADER{content-length}|'content-length
Not Found')
This variable shows the content-length
that comes in the HTTP header. If the content length is not specified,
its default value is shown.
<td align="left" valign="top"> <esi:vars>$(HTTP_HEADER{Content-length}|'content-length
Not Found')</esi:vars> </td>
$(QUERY_STRING{query}|'Query not
found')
'query'
is the name of parameter in query string, which returns the value of parameter
without URL encoding. The query string can be in URL or in request body. if 'query'
parameter is not found in the HTTP header, it shows its default value.
<td align="left" valign="top"> <esi:vars>$(QUERY_STRING{query}|'Query
not found')</esi:vars> </td>
<td align="left" valign="top"> <esi:vars>$(QUERY_STRING_DECODED{query}|'Query
not found')</esi:vars> </td>
$(QUERY_STRING_ENCODED{query})
Will
return the value of 'query' parameter with the URL encoding. The query string
can be in URL or in request body.
<td align="left" valign="top"> <esi:vars>$(QUERY_STRING_ENCODED{query}|'Query
not found')</esi:vars> </td>
HTTP Request variables supported by ESI
Detail explanation of all the HTTP request
variables used in the sample application is available here.
Pre-requisites
for running the example
You will
need the following software to run this example -
Oracle Application Server (9.0.3 or above). This can be downloaded from here
Oracle9i JDeveloper (9.0.3 or
above). This can be downloaded from here. This
is optional and required only if you wish to deploy from JDeveloper.
Deploying The Sample
The
complete source code for this sample is available for download.
This
section discusses the instructions to run the sample application
Step 1
Unjar
HttpRequestVariable.jar using Winzip, or using the following command:
> jar -xvf HttpRequestVariable.jar
This creates a directory : HttpRequestVariable.
Step 2
If you are using JDeveloper then, follow these steps
Open
Oracle9i JDeveloper and use 'File/Open' option to select the HttpRequestVariable.jws
from the HttpRequestVariable directory.
Next,
select Project/Make HttpRequestVariable.jpr from main menu.
Need to create
an application server connection in case if you don't have it.
Go to
Connections -> Application Server Connection. Right Click and 'click New connection'.
Enter connection name and select 'Oracle9i Application Server'.
Enter
user name and password
Enter Enterprise Manager's host name, port number
and Remote Application Server home directory (required only if deployed on remote
machine).
Click 'Next' and 'Test connection'. Click Finish button.
Now,
Right click HttpRequestVariable.deploy and select Deploy to <connection name>,
to the application server connection, which you have created in the previous step.
Step 3
To
deploy the application using EM, follow the steps.
Go to EM web site -> default oc4j home.
Choose Deploy EAR file
Enter
J2EE Application name, Click the Browse button and choose HttpRequestVariable.ear
from <SAMPLE_HOME>/deploy/HttpRequestVariable.ear.
Enter
the Application name as Personalize and click next
Enter URL mapping as
/HttpRequestVariable and click Finish
Click Deploy to deploy the application.
Running the sample
Access
the page on the browser, using the URL like following.
Where,
<host_name> is the machine on which OracleAS Web Cache is installed and
<port> is the port on which OracleAS Web Cache listener is running.
For Example, http://incq185b.idc.oracle.com:7777/HttpRequestVariable/welcome.html.
Steps
for running the sample application:
Open
up the browser.
Enter the URL" http://<host_name>:<port>/HttpRequestVariable/welcome.html"
in the address bar of the browser.
This page displays a HTML form to take
user inputs for 'Cookie value' and Query. Enter a value for 'Cookie Value' say
for example, VIJAY. Enter "What is your name" for 'Query'. Press
the Submit button to submit the form.
When welcome.html
page is submitted, display.jsp is displayed. This
page uses ESI tags to display HTTP request information like the number of visits
you made on this page, language enabled in the browser, host name, browser name,
version, os etc along with timestamp.
The number of visits made to the
display page (display.jsp ) is kept tracked using cookie named visits.
For every time, when the page is refreshed this cookie is incremented. The display
page is processed using the ESI tags at the OracleAS Web Cache itself, instead
of processing at origin server. This can be visualized by the time stamp displayed
in the display page. As the display page is cached for 60 seconds, all requests
within 60 seconds are processed in the web cache. After 60 seconds, the cached
page is invalidated and a new page is fetched from the origin server. The new
page stays in the cache for another 60 seconds.
To experiment with the
sample application, following things can be done, i) Edit the 'query'
parameter by changing the display page URL. example, http://incq185b.idc.oracle.com:2013/HttpRequestVariable/display.jsp?query=what+is+your+age
ii) add one more parameter 'query1' to the display page URL example,
http://incq185b.idc.oracle.com:2013/HttpRequestVariable/display.jsp?query=what+is+your+age&query1=added+query.
Note : ESI Processing of these variables are done at OracleAS Web Cache
and not at the origin server.
Points
to be noted
Variables are interpreted only when they are enclosed
within ESI tags.
Keys are used to access all the variables having
substructure type list or directory.
Dictionary keys are case sensitive.
All the variables taken from HTTP request header
are prefixed by "HTTP_ ", except for variables that start with QUERY_STRING.
You cannot set the default values for HTTP_HOST
and HTTP_REFERER variables.
Bookmark
