11.5 URL Actions

JSTL provides URL actions that let you import content from absolute and relative URLs in addition to resources from foreign contexts. You can also redirect HTTP responses and create URLs with automatic URL rewriting and request parameter encoding, as necessary. The JSTL URL actions are listed in Table 11.12.

Table 11.12. URL Actions

Action	Description
<c:import>	Imports the content of a URL-based resource.
<c:redirect>	Redirects an HTTP response.
<c:url>	Creates a URL, applying URL rewriting as necessary.
<c:param>	Encodes a request parameter for <c:import>, <c:redirect>, or <c:url>.

The <c:import> and <c:redirect> actions import content from URLs and redirect HTTP responses, respectively. Those actions provide the main functionality of the JSTL URL actions. The <c:url> and <c:param> actions provide a support role by creating URLs with URL rewriting incorporated as necessary and by encoding request parameters, respectively.

The JSTL URL actions do not expose any classes or interfaces.

<c:import>

Imports the content of a URL-based resource

Syntax: ^[9]

^[9] Items in brackets are optional.

Syntax #1: The content of the specified URL is sent to the current JspWriter or stored as a string in a scoped variable

 <c:import url [context] [var] [scope] [charEncoding]>  optional <c:param> actions  </c:import> 

Syntax #2: The content of the specified URL is only available within the body of the action through a reader

 <c:import url varReader [context] [charEncoding]>  body content that presumably extracts information from varReader  </c:import> 

Description:

The <c:import> action is similar to the <jsp:include> action, but it offers more features and flexibility. The <c:import> action can perform the following functions:

• Import content from a resource specified with a relative URL

• Import content from a resource in a foreign context ^[10]

  ^[10] A foreign context is another Web application in the same website.

• Import content from a resource specified with an absolute URL

• Store imported content in a string referenced by a scoped variable

• Provide access to imported content with a reader ^[11]

  ^[11] The reader option offers better performance than that obtained by storing content in a string.

• Specify a character encoding for imported content

• Specify URLs, foreign contexts, and character encodings with the JSTL expression language

The <jsp:include> action can only perform the first function listed above.

Attributes:

Attribute [a]	Type	Description
url	String	The <c:import> action imports content from a resource. This attribute specifies a URL that points to that resource.
context	String	The <c:import> action can import content from a resource in a foreign context (meaning another Web application). This attribute specifies that foreign context.
charEncoding	String	This attribute specifies a character encoding, such as ISO-8859-1 or UTF-8, used to decode imported content.
var	String	The name of a scoped variable that references a string containing the imported content.
scope	String	The scope of the scoped variable whose name is specified by the var attribute; default is page scope.
varReader	String	Instead of storing content in a string referenced by a scoped variable, you can access that content through a reader, thereby improving performance. This attribute specifies the name of that reader.

^[a] static dynamic

Constraints and Error Handling:

• If you specify a null value, an empty string, or an invalid value for the url attribute, <c:import> will throw a JspException .

• If you specify a null value or an empty string for the charEncoding attribute, that attribute is ignored.

• If a request dispatcher cannot be found for an internal resource, <c:import> throws a JspException with the resource path included in the exception's message.

• If the request the dispatcher's include method throws an exception when trying to access an internal resource, <c:import> throws a JspException with the caught exception as the root cause.

• If accessing a resource results in a response status code outside the range of 200 “299 (that range represents a successful operation), <c:import> throws a JspException with the resource path and status code in the exception's message.

• For external resources, if the URLConnection class throws an IOException or a RuntimeException , <c:import> throws a JspException that contains the original exception's message. That JspException also includes the original exception as the root cause.

In a Nutshell:

The <c:import> action provides the most features of any of the JSTL URL actions and is the most heavily used. By default, <c:import> writes its content to the current JspWriter , but if you specify the var attribute (and optionally the scope attribute), <c:import> will store its imported content in a string instead. You can access that string through a scoped variable whose name corresponds to the value that you specified for the var attribute.

Besides storing imported content in a string, you can also access that content directly with a reader whose name you specify with the varReader attribute. Accessing imported content with a reader is more efficient than storing it in a string, because the content is not buffered, so you may opt for the reader option when importing a resource that has a lot of content. Readers created by <c:import> are only available within the body of the <c:import> action because the <c:import> end tag is responsible for closing the reader. Because of that requirement, the reader must be available immediately after the <c:import> start tag; therefore, you cannot specify <c:param> actions in the body of the <c:import> action that was specified with a varReader attribute, as you can when content is imported directly or stored in a string.

If you specify a relative URL with the url attribute that points to a resource in the same context (Web application), <c:import> imports content in exactly the same manner as does <jsp:include>. In that case, you can specify a context-relative path, which starts with a forward slash and specifies a path to a resource from the application's top-level directory, or you can specify a page-relative path that does not begin with a forward slash and that specifies a path relative to the JSP page in which the <c:import> action resides. When you import content from a relative URL in the same context, the entire environment of the importing JSP page is available to the imported resource, including request attributes, session attributes, and request parameters of the importing page.

You can import resources from a foreign context by specifying the url and context attributes. In that case, the url attribute's value must be a context-relative path and the context attribute must be the context of the foreign context. Both of those attributes must start with a forward slash. When you import the content of a resource in a foreign context, only the request environment of the importing page is available to that resource. Note that not all JSP containers support accessing resources that reside in foreign contexts; if that is the case for your JSP container, you can use an absolute URL to access those resources.

Besides importing resources in the same context and resources in a foreign context, <c:import> can also import content from resources specified with absolute URLs. If you specify an absolute URL for the url attribute, none of the execution environment of the importing JSP page is available to that resource for security reasons, even if that absolute URL resolves to a resource in the same context.

Finally, you can specify a character encoding, for example Shift_JIS or UTF-8, that <c:import> uses to decode characters from the imported resource. You specify that encoding with the charEncoding attribute.

<c:redirect>

Redirects an HTTP response to a specified URL

Syntax: ^[12]

^[12] Items in brackets are optional.

Syntax #1: Without a body

 <c:redirect url [context]/> 

Syntax #2: With a body that specifies parameters

 <c:redirect url [context]>  <c:param> actions  </c:redirect> 

Description:

The <c:redirect> action redirects an HTTP response to a specified URL and aborts processing of the JSP page in which the <c:redirect> action resides.

Attributes:

Attribute [a]	Type	Description
url	String	The <c:redirect> action redirects an HTTP response to a URL specified with this attribute.
context	String	If the url attribute specifies a url in a foreign context, this attribute specifies that foreign context.

^[a] static dynamic

In a Nutshell:

The url attribute must specify a relative URL or an absolute URL. If the URL points to a resource in a foreign context, you must specify the context attribute in addition to the url attribute, and the values for both of those attributes must start with a forward slash. Like <c:import>, <c:redirect> will rewrite the URL to maintain a session, as appropriate, when you redirect to a relative resource.

<c:url>

Creates a URL that's rewritten if necessary

Syntax: ^[13]

^[13] Items in brackets are optional.

Syntax #1: Without a body

 <c:url value [context] [var] [scope]/> 

Syntax #2: With a body that specifies parameters

 <c:url value [context] [var] [scope]>  <c:param> actions  </c:url> 

Description:

The <c:url> action processes a URL and rewrites relative URLs to maintain session information, as appropriate.

Attributes:

Attribute [a]	Type	Description
value	String	The URL that <c:url> processes.
context	String	If the URL specified with the value attribute represents a resource in a foreign context, you must also specify this attribute, which represents that foreign context.
var	String	The name of a scoped variable that references the processed URL.
scope	String	The scope of the scoped variable whose name is specified by the var attribute; default is page scope.

^[a] static dynamic

In a Nutshell:

You specify a URL with the <c:url> action's value attribute (and the context attribute if the URL points to a resource in a foreign context); <c:url> modifies that URL so that it's suitable for submission to a browser. You can also specify request parameters with nested <c:param> actions.

The <c:url> action will apply URL rewriting, if necessary, to maintain session information for relative URLs only; for security reasons, <c:url> will not apply URL rewriting to absolute URLs.

You can specify a page-relative URL, context-relative URL, or an absolute URL for the value attribute. You can also specify a URL that points to a resource in a foreign context by specifying both the value and context attributes. If you specify a URL that points to a resource in a foreign context, the value that you specify for the value attribute must be a context-relative URL and the value that you specify for the context attribute must begin with a forward slash.

If you specify <c:param> actions inside the body of a <c:url> action, the request parameters that you specify with those <c:param> actions will be properly encoded; however, if the original URL that you specify with the value attribute contains characters, such as spaces, which should be encoded, you must make sure that they are encoded to begin with.

By default, the <c:url> action writes the processed URL to the current JspWriter , but <c:url> will store its URL in a scoped variable if you specify the var attribute (and optionally, the scope attribute). The name of that scoped variable is the value that you specify for the var attribute.

The <c:url> action prepends the context path of the current Web application to relative URLs that you specify with the value attribute. Because the <c:import> action also prepends the context path to relative URLs, you must not use the URL created by <c:url> to specify a URL for <c:import> for relative URLs. See "The <c:url> Action" on page 208 for more information about this restriction.

<c:param>

Encodes a request parameter and adds it to a URL

Syntax:

Syntax #1: Without a body, specifying a value with the value attribute

 <c:param name value/> 

Syntax #2: With a body, specifying a value in the body of the action

 <c:param name>  value  </c:param> 

Description:

The <c:param> action encodes a request parameter that you specify with the name and value attributes. That encoded request parameter is added to a URL created by <c:import>, <c:url>, or <c:redirect>.

Attributes:

Attribute [a]	Type	Description
name	String	The name of the request parameter.
value	String	The value of the request parameter.

^[a] static dynamic

Constraints and Error Handling:

• If you specify a null value or an empty string for the name attribute, the <c:param> action does nothing.

• If you specify a null value for the value attribute, <c:param> processes that value as an empty value.

In a Nutshell:

All <c:param> actions must be nested in <c:import>, <c:url>, or <c:redirect> actions. The <c:param> action is analogous to <jsp:param>, which specifies parameters for the <jsp:include> action.