Jakarta Project: Response Tag library

Version: 1.0.1

Overview
Requirements
Configuration
Tag Summary
Tag Reference
HTTP Error and Status Codes
Examples
Javadocs
Revision History

Overview

The RESPONSE custom tag library contains tags which can be used to set all the information for an HTTP response for a JSP page.

This includes creating cookies and setting their values, setting HTTP headers, returning back an HTTP error, or sending an HTTP redirect.

Requirements

This custom tag library requires no software other than a servlet container that supports the JavaServer Pages Specification, version 1.1 or higher.

Configuration

Follow these steps to configure your web application with this tag library:

Copy the tag library descriptor file to the /WEB-INF subdirectory of your web application.
Copy the tag library JAR file to the /WEB-INF/lib subdirectory of your web application.

Add a <taglib> element to your web application deployment descriptor in /WEB-INF/web.xml like this:

<taglib>
  <taglib-uri>http://jakarta.apache.org/taglibs/response-1.0</taglib-uri>
  <taglib-location>/WEB-INF/response.tld</taglib-location>
</taglib>

To use the tags from this library in your JSP pages, add the following directive at the top of each page:

<%@ taglib uri="http://jakarta.apache.org/taglibs/response-1.0" prefix="res" %>

where "res" is the tag name prefix you wish to use for tags from this library. You can change this value to any prefix you like.

Tag Summary

Response Tags

encodeRedirectUrl	Encode a URL with the JSESSIONID for use with sendRedirect.
encodeUrl	Encode a URL with the JSESSIONID if necessary.
flushBuffer	Forces any content in the buffer to be written to the client.
isCommitted	Tests whether the HTTP Response has been committed to the client.
sendError	Return an HTTP error as the HTTP Response.
sendRedirect	Send a redirect to a URL as the HTTP Response.
setContentType	Sets the content type of the response being sent to the client.
setStatus	Set the status code for the HTTP Response.
skipPage	Skips the remainder of the JSP page.

Response Cookie Tags

addCookie	Add a cookie to an Http Response.
comment	Set a cookie comment.
domain	Set a cookie domain.
maxAge	Set the cookies maximum age.
path	Set a cookie path.
secure	Set whether cookie is secure.
value	Set a cookie value.
version	Set the cookie version.

Response Header Tags

addHeader	Add a single HTTP header.
addDateHeader	Add a single HTTP date header.
addIntHeader	Add a single HTTP integer header.
containsHeader	Test whether the HTTP Response contains an HTTP header.
setHeader	Set a single HTTP header.
setDateHeader	Set a single HTTP date header.
setIntHeader	Set a single HTTP integer header.

Tag Reference

encodeRedirectUrl		Availability: 1.0
Encode a URL with the JSESSIONID for use with sendRedirect. Uses the tag body as the URL to encode, outputs the URL after encoding it.
Tag Body	JSP
Restrictions	None
Attributes	None
Variables	None
Examples	Encode the URL and redirect to index.html
	`<res:sendRedirect> <res:encodeRedirectUrl>index.html</res:encodeRedirectUrl> </res:sendRedirect>`

encodeUrl		Availability: 1.0
Encode a URL with the JSESSIONID if necessary. Uses the tag body as the URL to encode, outputs the URL after encoding it.
Tag Body	JSP
Restrictions	None
Attributes	None
Variables	None
Examples	Encode the URL myapp.jsp
	`Go to <a href="<res:encodeUrl>/myapp.jsp</res:encodeUrl>"> My Application</a>.`

flushBuffer		Availability: 1.0
Forces any content in the buffer to be written to the client.
Tag Body	empty
Restrictions	None
Attributes	None
Variables	None
Examples	Flush output buffer to client
	`<res:flushBuffer/>`

isCommitted				Availability: 1.0
Includes tag body if the HTTP Response has been committed to the client.
Tag Body	JSP
Restrictions	None
Attributes	Name	Required	Runtime Expression Evaluation	Availability
	value	No	No	1.0
	If value is set to false the iscommitted tag includes body of tag if the response is not yet committed. Default is true.
Variables	None
Examples	See if response output is committed
	`<res:isCommitted> Response is already committed! </res:isCommitted> <res:isCommitted value="false"> Response is not committed yet. </res:isCommitted>`

sendError				Availability: 1.0
Return an HTTP error as the HTTP Response.
Tag Body	JSP
Restrictions	None
Attributes	Name	Required	Runtime Expression Evaluation	Availability
	error	Yes	No	1.0
	The HTTP error status code to return, for example SC_UNAUTHORIZED. See the HTTP Error and Status Codes for a list of values this can be set to.
	reset	No	No	1.0
	Set to true or false. If set to true the buffer, headers, and status code will be reset. Default is false.
Variables	None
Examples	Send back an HTTP error that user is not authorized
	`<res:sendError error="SC_UNAUTHORIZED">Not Authorized!</res:sendError>`

sendRedirect		Availability: 1.0
Send a redirect to a URL as the HTTP Response. Tag body is used as URL to redirect to.
Tag Body	JSP
Restrictions	None
Attributes	None
Variables	None
Examples	Redirect back to the site root index.html
	`<res:sendRedirect> <res:encodeRedirectUrl>/index.html</res:encodeRedirectUrl> </res:sendRedirect>`

setContentType		Availability: 1.0
Sets the content type of the response being sent to the client. Content Type is set to the contents of the tag body.
Tag Body	JSP
Restrictions	None
Attributes	None
Variables	None
Examples	Set the content type to text/html
	`<res:setContentType>text/html</res:setContentType>`

setStatus				Availability: 1.0
Set the status code for the HTTP Response.
Tag Body	empty
Restrictions	None
Attributes	Name	Required	Runtime Expression Evaluation	Availability
	status	Yes	No	1.0
	The HTTP status code to return, for example SC_OK. See the HTTP Error and Status Codes for a list of values this can be set to.
Variables	None
Examples
	`<res:setstatus status="SC_OK"/>`

skipPage		Availability: 1.0
Skips the remainder of the JSP page.
Tag Body	empty
Restrictions	None
Attributes	None
Variables	None
Examples	Skip the remainder of the JSP page
	`<res:skipPage/>`

addCookie				Availability: 1.0
Creates a cookie, a small amount of information sent by a JSP page to a Web browser, saved by the browser, and later sent back to the server. A cookie's value can uniquely identify a client, so cookies are commonly used for session management. A cookie has a name, a single value, and optional attributes such as a comment, path and domain qualifiers, a maximum age, and a version number. Some Web browsers have bugs in how they handle the optional attributes, so use them sparingly to improve the interoperability of your JSP pages. Cookie attributes such as the comment, value, etc. can be set statically by using the corresponding addCookie tag attribute. Or dynamically using the corresponding tag in the body of the addCookie tag.
Tag Body	JSP
Restrictions	None
Attributes	Name	Required	Runtime Expression Evaluation	Availability
	comment	No	No	1.0
	Specifies a comment that describes a cookie's purpose. The comment is useful if the browser presents the cookie to the user. Comments are not supported by Netscape Version 0 cookies.
	domain	No	No	1.0
	Specifies the domain within which this cookie should be presented. The form of the domain name is specified by RFC 2109. A domain name begins with a dot (.foo.com) and means that the cookie is visible to servers in a specified Domain Name System (DNS) zone (for example, www.foo.com, but not a.b.foo.com). By default, cookies are only returned to the server that sent them.
	maxAge	No	No	1.0
	Sets the cookie maximum age in seconds. A positive value indicates that the cookie will expire after that many seconds have passed. Note that the value is the maximum age when the cookie will expire, not the cookie's current age. A negative value means that the cookie is not stored persistently and will be deleted when the Web browser exits. A zero value causes the cookie to be deleted. Default value is -1.
	name	Yes	No	1.0
	Sets the name of the cookie.
	path	No	No	1.0
	Specifies a path for the cookie to which the client should return the cookie. The cookie is visible to all the pages in the directory you specify, and all the pages in that directory's subdirectories. Consult RFC 2109 (available on the Internet) for more information on setting path names for cookies.
	secure	No	No	1.0
	Indicates to the browser whether the cookie should only be sent using a secure protocol, such as HTTPS or SSL. Can be set to true or false. The default value is false.
	value	No	No	1.0
	Assigns a new value to a cookie after the cookie is created. If you use a binary value, you may want to use BASE64 encoding. With Version 0 cookies, values should not contain white space, brackets, parentheses, equals signs, commas, double quotes, slashes, question marks, at signs, colons, and semicolons. Empty values may not behave the same way on all browsers.
	version	No	No	1.0
	Sets the version of the cookie protocol this cookie complies with. Version 0 complies with the original Netscape cookie specification. Version 1 complies with RFC 2109. Since RFC 2109 is still somewhat new, consider version 1 as experimental; do not use it yet on production sites. Default version is 0.
Variables	None
Examples	Return a test cookie
	`<res:addCookie name="test" value="Yes" comment="Test"/>`

comment		Availability: 1.0
Specifies a comment that describes a cookie's purpose. Cookie comment is set to the tag body. The comment is useful if the browser presents the cookie to the user. Comments are not supported by Netscape Version 0 cookies.
Tag Body	JSP
Restrictions	Must be nested inside an addCookie tag.
Attributes	None
Variables	None
Examples	Return a test cookie
	`<res:addCookie name="test"> <res:value>Yes</res:value> <res:comment>Test Cookie</res:comment> </res:addCookie>`

domain		Availability: 1.0
Specifies the domain within which this cookie should be presented. Cookie domain is set to the tag body. The form of the domain name is specified by RFC 2109. A domain name begins with a dot (.foo.com) and means that the cookie is visible to servers in a specified Domain Name System (DNS) zone (for example, www.foo.com, but not a.b.foo.com). By default, cookies are only returned to the server that sent them.
Tag Body	JSP
Restrictions	Must be nested inside an addCookie tag.
Attributes	None
Variables	None
Examples	Return a test cookie
	`<res:addCookie name="test"> <res:value>Yes</res:value> <res:domain>www.foo.com</res:domain> </res:addCookie>`

maxAge		Availability: 1.0
Sets the cookie maximum age in seconds. Cookie maximum age is set to the tag body. A positive value indicates that the cookie will expire after that many seconds have passed. Note that the value is the maximum age when the cookie will expire, not the cookie's current age. A negative value means that the cookie is not stored persistently and will be deleted when the Web browser exits. A zero value causes the cookie to be deleted.
Tag Body	JSP
Restrictions	Must be nested inside an addCookie tag.
Attributes	None
Variables	None
Examples	Return a test cookie
	`<res:addCookie name="test"> <res:value>Yes</res:value> <res:maxAge>-1</res:maxAge> </res:addCookie>`

path		Availability: 1.0
Specifies a path for the cookie to which the client should return the cookie. Cookie path is set to the tag body. The cookie is visible to all the pages in the directory you specify, and all the pages in that directory's subdirectories. Consult RFC 2109 (available on the Internet) for more information on setting path names for cookies.
Tag Body	JSP
Restrictions	Must be nested inside an addCookie tag.
Attributes	None
Variables	None
Examples	Return a test cookie
	`<res:addCookie name="test"> <res:value>Yes</res:value> <res:path>/response-examples/</res:path> </res:addCookie>`

secure		Availability: 1.0
Indicates to the browser whether the cookie should Cookie secure is set to the tag body. only be sent using a secure protocol, such as HTTPS or SSL. Can be set to true or false. The default value is false.
Tag Body	JSP
Restrictions	Must be nested inside an addCookie tag.
Attributes	None
Variables	None
Examples	Return a test cookie
	`<res:addCookie name="test"> <res:value>Yes</res:value> <res:secure>true</res:secure> </res:addCookie>`

value		Availability: 1.0
Assigns a new value to a cookie after the cookie is created. Cookie value is set to the tag body. If you use a binary value, you may want to use BASE64 encoding. With Version 0 cookies, values should not contain white space, brackets, parentheses, equals signs, commas, double quotes, slashes, question marks, at signs, colons, and semicolons. Empty values may not behave the same way on all browsers.
Tag Body	JSP
Restrictions	Must be nested inside an addCookie tag.
Attributes	None
Variables	None
Examples	Return a test cookie
	`<res:addCookie name="test"> <res:value>Yes</res:value> </res:addCookie>`

version		Availability: 1.0
Sets the version of the cookie protocol this cookie complies with. Cookie version is set to the tag body. Version 0 complies with the original Netscape cookie specification. Version 1 complies with RFC 2109. Since RFC 2109 is still somewhat new, consider version 1 as experimental; do not use it yet on production sites. Default version is 0.
Tag Body	JSP
Restrictions	Must be nested inside an addCookie tag.
Attributes	None
Variables	None
Examples	Return a test cookie
	`<res:addCookie name="test"> <res:value>Yes</res:value> <res:version>1</res:version> </res:addCookie>`

addHeader				Availability: 1.0
Adds a response header with the given name and a value. This method allows response headers to have multiple values. Header value is set to content of the tag body.
Tag Body	JSP
Restrictions	None
Attributes	Name	Required	Runtime Expression Evaluation	Availability
	name	Yes	No	1.0
	Sets the name of the header.
Variables	None
Examples	Add the HTTP Header Cache-Control set to no-cache
	`<res:addHeader name="Cache-Control">no-cache</res:addHeader>`

addDateHeader				Availability: 1.0
Adds a response header with the given name and date value. The date is specified in terms of milliseconds since Jan 1, 1970 GMT. This method allows response headers to have multiple values. Header value is set to content of the tag body.
Tag Body	JSP
Restrictions	None
Attributes	Name	Required	Runtime Expression Evaluation	Availability
	name	Yes	No	1.0
	Sets the name of the header.
Variables	None
Examples	Add an HTTP Header Expires set to the current time
	`<res:addDateHeader name="Expires"> <dt:currentTime/> </res:addDateHeader>`

addIntHeader				Availability: 1.0
Adds a response header with the given name and an integer value. This method allows response headers to have multiple values. Header value is set to content of the tag body.
Tag Body	JSP
Restrictions	None
Attributes	Name	Required	Runtime Expression Evaluation	Availability
	name	Yes	No	1.0
	Sets the name of the header.
Variables	None
Examples	Add the HTTP Header Expires set to 0
	`<res:addIntHeader name="Expires">0</res:addIntHeader>`

containsHeader				Availability: 1.0
Includes the tag body if the HTTP Response contains an HTTP header.
Tag Body	JSP
Restrictions	None
Attributes	Name	Required	Runtime Expression Evaluation	Availability
	name	Yes	No	1.0
	Sets the name of the header.
	value	No	No	1.0
	If value is set to false the containsHeader tag includes body of tag if the HTTP header has not been set. Default is true.
Variables	None
Examples	Set the Expires HTTP header if it doesn't exist
	`<res:containsHeader name="Expires"> Expires header already exists! </res:containsHeader> <res:containsHeader name="Expires" value="false"> Set Expires HTTP Header to 0: <res:setIntHeader name="Expires">0</res:setIntHeader> </res:containsHeader>`

setHeader				Availability: 1.0
Set a response header with the given name to a value. If the header had already been set, the new value overwrites the previous one. Header value is set to content of the tag body.
Tag Body	JSP
Restrictions	None
Attributes	Name	Required	Runtime Expression Evaluation	Availability
	name	Yes	No	1.0
	Sets the name of the header.
Variables	None
Examples	Set the HTTP Header Cache-Control set to no-cache
	`<res:setHeader name="Cache-Control">no-cache</res:setHeader>`

setDateHeader				Availability: 1.0
Set a response header with the given name to a date specified as the number of milliseconds since Jan 1, 1970 GMT. If the header had already been set, the new value overwrites the previous one. Header value is set to content of the tag body.
Tag Body	JSP
Restrictions	None
Attributes	Name	Required	Runtime Expression Evaluation	Availability
	name	Yes	No	1.0
	Sets the name of the header.
Variables	None
Examples	Set an HTTP Header Expires set to the current time
	`<res:setDateHeader name="Expires"> <dt:currentTime/> </res:setDateHeader>`

setIntHeader				Availability: 1.0
Set a response header with the given name to an integer value. If the header had already been set, the new value overwrites the previous one. Header value is set to content of the tag body.
Tag Body	JSP
Restrictions	None
Attributes	Name	Required	Runtime Expression Evaluation	Availability
	name	Yes	No	1.0
	Sets the name of the header.
Variables	None
Examples	Set the HTTP Header Expires set to 0
	`<res:setIntHeader name="Expires">0</res:setIntHeader>`

HTTP Error and Status Codes

SC_ACCEPTED
Status code (202) indicating that a request was accepted for processing, but was not completed.

SC_BAD_GATEWAY
Status code (502) indicating that the HTTP server received an invalid response from a server it consulted when acting as a proxy or gateway.

SC_BAD_REQUEST
Status code (400) indicating the request sent by the client was syntactically incorrect.

SC_CONFLICT
Status code (409) indicating that the request could not be completed due to a conflict with the current state of the resource.

SC_CONTINUE
Status code (100) indicating the client can continue.

SC_CREATED
Status code (201) indicating the request succeeded and created a new resource on the server.

SC_EXPECTATION_FAILED
Status code (417) indicating that the server could not meet the expectation given in the Expect request header.

SC_FORBIDDEN
Status code (403) indicating the server understood the request but refused to fulfill it.

SC_GATEWAY_TIMEOUT
Status code (504) indicating that the server did not receive a timely response from the upstream server while acting as a gateway or proxy.

SC_GONE
Status code (410) indicating that the resource is no longer available at the server and no forwarding address is known.

SC_HTTP_VERSION_NOT_SUPPORTED
Status code (505) indicating that the server does not support or refuses to support the HTTP protocol version that was used in the request message.

SC_INTERNAL_SERVER_ERROR
Status code (500) indicating an error inside the HTTP server which prevented it from fulfilling the request.

SC_LENGTH_REQUIRED
Status code (411) indicating that the request cannot be handled without a defined Content-Length.

SC_METHOD_NOT_ALLOWED
Status code (405) indicating that the method specified in the Request-Line is not allowed for the resource identified by the Request-URI.

SC_MOVED_PERMANENTLY
Status code (301) indicating that the resource has permanently moved to a new location, and that future references should use a new URI with their requests.

SC_MOVED_TEMPORARILY
Status code (302) indicating that the resource has temporarily moved to another location, but that future references should still use the original URI to access the resource.

SC_MULTIPLE_CHOICES
Status code (300) indicating that the requested resource corresponds to any one of a set of representations, each with its own specific location.

SC_NO_CONTENT
Status code (204) indicating that the request succeeded but that there was no new information to return.

SC_NON_AUTHORITATIVE_INFORMATION
Status code (203) indicating that the meta information presented by the client did not originate from the server.

SC_NOT_ACCEPTABLE
Status code (406) indicating that the resource identified by the request is only capable of generating response entities which have content characteristics not acceptable according to the accept headerssent in the request.

SC_NOT_FOUND
Status code (404) indicating that the requested resource is not available.

SC_NOT_IMPLEMENTED
Status code (501) indicating the HTTP server does not support the functionality needed to fulfill the request.

SC_NOT_MODIFIED
Status code (304) indicating that a conditional GET operation found that the resource was available and not modified.

SC_OK
Status code (200) indicating the request succeeded normally.

SC_PARTIAL_CONTENT
Status code (206) indicating that the server has fulfilled the partial GET request for the resource.

SC_PAYMENT_REQUIRED
Status code (402) reserved for future use.

SC_PRECONDITION_FAILED
Status code (412) indicating that the precondition given in one or more of the request-header fields evaluated to false when it was tested on the server.

SC_PROXY_AUTHENTICATION_REQUIRED
Status code (407) indicating that the client MUST first authenticate itself with the proxy.

SC_REQUEST_ENTITY_TOO_LARGE
Status code (413) indicating that the server is refusing to process the request because the request entity is larger than the server is willing or able to process.

SC_REQUEST_TIMEOUT
Status code (408) indicating that the client did not produce a requestwithin the time that the server was prepared to wait.

SC_REQUEST_URI_TOO_LONG
Status code (414) indicating that the server is refusing to service the request because the Request-URI is longer than the server is willing to interpret.

SC_REQUESTED_RANGE_NOT_SATISFIABLE
Status code (416) indicating that the server cannot serve the requested byte range.

SC_RESET_CONTENT
Status code (205) indicating that the agent SHOULD reset the document view which caused the request to be sent.

SC_SEE_OTHER
Status code (303) indicating that the response to the request can be found under a different URI.

SC_SERVICE_UNAVAILABLE
Status code (503) indicating that the HTTP server is temporarily overloaded, and unable to handle the request.

SC_SWITCHING_PROTOCOLS
Status code (101) indicating the server is switching protocols according to Upgrade header.

SC_UNAUTHORIZED
Status code (401) indicating that the request requires HTTP authentication.

SC_UNSUPPORTED_MEDIA_TYPE
Status code (415) indicating that the server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method.

SC_USE_PROXY
Status code (305) indicating that the requested resource MUST be accessed through the proxy given by the Location field.

Examples

See the example application response-examples.war for examples of the usage of the tags from this custom tag library.

Java Docs

Java programmers can view the java class documentation for this tag library as javadocs.

Revision History

Review the complete revision history of this tag library.