Skip navigation.
Downloads | Product Documentation | Support

Developing Web Applications, Servlets, and JSPs for WebLogic Server

# Creating and Configuring JSPs

The following sections describe how to create and configure JSPs.

- Configuring Java Server Pages (JSPs)
- Configuring JSP Tag Libraries
- Configuring Welcome Files
- Customizing HTTP Error Responses
- Determining the Encoding of an HTTP Request
- Mapping IANA Character Sets to Java Character Sets
- Configuring Implicit Includes at the Beginning and End of JSPs
- Configuring JSP Property Groups
- Writing JSP Documents Using XML Syntax

# Configuring Java Server Pages (JSPs)

In order to deploy Java Server Pages (JSP) files, you must place them in the root (or in a subdirectory below the root) of a Web application. You define JSP configuration parameters in subelements of the `jsp-descriptor` element in the WebLogic-specific deployment descriptor, `weblogic.xml`. These parameters define the following functionality:

- Options for the JSP compiler
- Debugging
- How often WebLogic Server checks for updated JSPs that need to be recompiled
- Character encoding

For a complete description of these subelements, see jsp-descriptor.

# Registering a JSP as a Servlet

You can register a JSP as a servlet using the `servlet` element of the J2EE standard deployment descriptor web.xml. (The `web.xml` file is located in the `WEB-INF` directory of your Web application.) A servlet container maintains a map of the servlets known to it. This map is used to resolve requests that are made to the container. Adding entries into this map is known as "registering" a servlet. You add entries to this map by referencing a `servlet` element in web.xml through the `servlet-mapping` entry.

A JSP is a type of servlet; registering a JSP is a special case of registering a servlet. Normally, JSPs are implicitly registered the first time you invoke them, based on the name of the JSP file. Therefore, the `myJSPfile.jsp` file would be registered as `myJSPfile.jsp` in the mapping table. You can implicitly register JSPs, as illustrated in the following example. In this example, you request the JSP with the name `/main` instead of the implicit name `myJSPfile.jsp`.

In this example, a URL containing `/main` will invoke `myJSPfile.jsp`:

>     <servlet>

>          <servlet-name>myFoo</servlet-name>

>          <jsp-file>myJSPfile.jsp</jsp-file>

>     </servlet>

>     <servlet-mapping>

>          <servlet-name>myFoo</servlet-name>

>          <url-pattern>/main</url-pattern>

>     </servlet-mapping>

Registering a JSP as a servlet allows you to specify the load order, initialization attributes, and security roles for a JSP, just as you would for a servlet.

# Configuring JSP Tag Libraries

Weblogic Server lets you create and use custom JSP tags. Custom JSP tags are Java classes you can call from within a JSP page. To create custom JSP tags, you place them in a tag library and define their behavior in a tag library descriptor (TLD) file. You make this TLD available to the Web application containing the JSP by defining it in the Web Application deployment descriptor. It is a good idea to place the TLD file in the `WEB-INF` directory of your Web application, because that directory is never available publicly.

In the Web Application deployment descriptor, you define a URI pattern for the tag library. This URI pattern must match the value in the taglib directive in your JSP pages. You also define the location of the TLD. For example, if the taglib directive in the JSP page is:

>     <%@ taglib uri="myTaglib" prefix="taglib" %>

and the `TLD` is located in the `WEB-INF` directory of your Web application, you would create the following entry in the Web Application deployment descriptor:

>     <jsp-config>

>     <taglib>

>     <taglib-uri>myTaglib</taglib-uri>

>     <tablig-location>WEB-INF/myTLD.tld</taglib-location>

>     </taglib>

>     </jsp-config>

You can also deploy a tag library as a `.jar` file.

For more information on creating custom JSP tag libraries, see Programming JSP Tag Extensions.

WebLogic Server also includes several custom JSP tags that you can use in your applications. These tags perform caching, facilitate query attribute-based flow control, and facilitate iterations over sets of objects. For more information, see:

- Using Custom WebLogic JSP Tags (cache, process, repeat).
- Using WebLogic JSP Form Validation Tags.

# Configuring Welcome Files

Web Application developers can define an ordered list of partial URIs called welcome files in the Web application deployment descriptor. The purpose of this mechanism is to allow the deployer to specify an ordered list of partial URIs for the container to use for appending to URIs when there is a request for a URI that corresponds to a directory entry in the WAR not mapped to a Web component. This feature can make your site easier to use, because the user can type a URL without giving a specific filename.

Note: Welcome files can be JSPs, static pages, or servlets.

Welcome files are defined at the Web application level. If your server is hosting multiple Web applications, you need to define welcome files separately for each Web application. You define Welcome files using the welcome-file-list element in `web.xml`. (The `web.xml` file is located in the `WEB-INF` directory of your Web application.) The following is an example Welcome file configuration:

Listing 5-1 Welcome File Example

>     <servlet>
>     	<servlet-name>WelcomeServlet</servlet-name>
>     	<servlet-class>foo.bar.WelcomeServlet</servlet-class>
>     </servlet>

>     <servlet-mapping>
>     	<servlet-name>WelcomeServlet</servlet-name>
>     	<url-pattern>*.foo</url-pattern>
>     </servlet-mapping>

>     <welcome-file-list>
>     	<welcome-file>/welcome.foo</welcome-file>
>     </welcome-file-list>

For more information on this subject, see section 9.10 of the Servlet 2.4 specification.

# Customizing HTTP Error Responses

You can configure WebLogic Server to respond with your own custom Web pages or other HTTP resources when particular HTTP errors or Java exceptions occur, instead of responding with the standard WebLogic Server error response pages.

You define custom error pages in the `error-page` element of the J2EE standard Web application deployment descriptor, `web.xml`. (The `web.xml` file is located in the `WEB-INF` directory of your Web application.)

# Determining the Encoding of an HTTP Request

WebLogic Server converts binary (bytes) data contained in an HTTP request to the correct encoding expected by the servlet. The incoming post data might be encoded in a particular encoding that must be converted to the correct encoding on the server side for use in methods such as request.getParameter(..).

There are two ways you can define the code set:

- For a POST operation, you can set the encoding in the HTML `<form>` tag. For example, this form tag sets `SJIS` as the character set for the content:

>     <form action="http://some.host.com/myWebApp/foo/index.html">
>       <input type="application/x-www-form-urlencoded; charset=SJIS">
>     </form>

When the form is read by WebLogic Server, it processes the data using the `SJIS` character set.

- Because all Web clients do not transmit the information after the semicolon in the above example, you can set the code set to be used for requests by using the `input-charset` element in the WebLogic-specific deployment descriptor, `weblogic.xml`.

The `java-charset-name` subelement defines the encoding used to convert data when the URL of the request contains the path specified with the `resource-path` subelement.

This following example ensures that all request parameters that map to the pattern /foo/* are encoded using the Java character set SJIS.

>     <input-charset>

>     <resource-path>/foo/*</resource-path>

>     <java-charset-name>SJIS</java-charset-name>

>     </input-charset>

This method works for both `GET` and `POST` operations.

# Mapping IANA Character Sets to Java Character Sets

The names assigned by the Internet Assigned Numbers Authority (IANA) to describe character sets are sometimes different from the names used by Java. Because all HTTP communication uses the IANA character set names and these names are not always the same, WebLogic Server internally maps IANA character set names to Java character set names and can usually determine the correct mapping. However, you can resolve any ambiguities by explicitly mapping an IANA character set to the name of a Java character set.

To map on IANA character set to a Java character, set the character set names in the `charset-mapping` element of the WebLogic-specific deployment descriptor, `weblogic.xml`. Define the IANA character set name in the iana-charset-name element and the Java character set name in the java-charset-name element. See charset-mapping.

For example:

>     <charset-mapping>
>         <iana-charset-name>Shift-JIS</iana-charset-name>
>         <java-charset-name>SJIS</java-charset-name>
>     </charset-mapping>

# Configuring Implicit Includes at the Beginning and End of JSPs

You can implicitly include preludes (also called headers) and codas (also called footers) for a group of JSP pages by adding <include-prelude> and <include-coda> elements respectively within a <jsp-property-group> element in the Web application web.xml deployment descriptor. Their values are context-relative paths that must correspond to elements in the Web application. When the elements are present, the given paths are automatically included (as in an include directive) at the beginning and end of each JSP page in the property group respectively. When there is more than one include or coda element in a group, they are included in the order they appear. When more than one JSP property group applies to a JSP page, the corresponding elements will be processed in the same order as they appear in the JSP configuration section.

Consider the following files: /template/prelude.jspf and /template/coda.jspf. These files are used to include code at the beginning and end of each file in the following example:

Listing 5-2 Implicit Includes

>     <jsp-config>

>       <jsp-property-group>

>         <display-name>WebLogicServer</display-name>

>         <url-pattern>*.jsp</url-pattern>

>         <el-ignored>false</el-ignored>

>         <scripting-invalid>false</scripting-invalid>

>         <is-xml>false</is-xml>

>         <include-prelude>/template/prelude.jspf</include-prelude>

>         <include-coda>/template/coda.jspf</include-coda>

>       </jsp-property-group>

>     </jsp-config>

# Configuring JSP Property Groups

A JSP property group is a collection of properties that apply to a set of files representing JSP pages. You define these properties in one or more subelements of the jsp-property-group element in the web.xml deployment descriptor.

Most properties defined in a JSP property group apply to an entire translation unit, that is, the requested JSP file that is matched by its URL pattern and all the files it includes by way of the include directive. The exception is the page-encoding property, which applies separately to each JSP file matched by its URL pattern. The applicability of a JSP property group is defined through one or more URL patterns. URL patterns use the same syntax as defined in chapter 11, "Mapping Requests to Servlets" of the Servlet 2.4 specification, but are bound at translation time. All the properties in the property group apply to the resources in the Web application that match any of the URL patterns. There is an implicit property—that of being a JSP file. JSP property groups do not affect tag files.

## JSP Property Group Rules

The following are some rules that apply to JSP property groups:

- If a resource matches a URL pattern in both a servlet-mapping and a jsp-property-group, the pattern that is most specific applies (following the same rules as the servlet specification).
- If the URL patterns are identical, the jsp-property-group takes precedence over the servlet-mapping.
- If at least one jsp-property-group contains the most specific matching URL pattern, the resource is considered to be a JSP file, and the properties in that jsp-property-group apply.
- If a resource is considered to be a JSP file, all include-prelude and include-coda properties apply from all the jsp-property-group elements with matching URL patterns. See Configuring Implicit Includes at the Beginning and End of JSPs.

## What You Can Do with JSP Property Groups

You can configure the jsp-property-group to do the following:

- Indicate that a resource is a JSP file (implicit).
- Control disabling of JSP expression language (JSP EL) evaluation.
- Control disabling of Scripting elements.
- Indicate page Encoding information.
- Prelude and Coda automatic includes.
- Indicate that a resource is a JSP document.

For more information on JSP property groups, see chapter 3, "JSP Configuration," of the JSP 2.0 specification.

# Writing JSP Documents Using XML Syntax

The JSP 2.0 specification has improved upon the concept of JSP documents by allowing them to leverage XML syntax. Also, JSP documents have been extended to use property groups. A JSP document is a JSP page written using XML syntax. JSP documents need to be described as such, either implicitly or explicitly, to the JSP container, which then processes them as XML documents, checking for well-formedness and applying requests like entity declarations, if present. JSP documents are used to generate dynamic content using the standard JSP semantics.

The following is an example of a simple JSP document that generates, using the JSP standard tag library, an XML document that has table as the root element. The table element has three row subelements containing values 1, 2, and 3. For more details and other examples, see section 6.4, "Examples of JSP Documents," of the JSP 2.0 specification.

Listing 5-3 Simple JSP Document

>     <table>

>     <c:forEach

>     xmlns:c="http://java.sun.com/jsp/jstl/core"

>     var="counter" begin="1" end="3">

>     <row>${counter}</row>

>     </c:forEach>

>     </table>

## How to Use JSP Documents

You can use JSP documents in a number of ways including the following:

- JSP documents can be passed directly to the JSP container. This is becoming more important as more and more content is authored in XML. The generated content may be sent directly to a client or it may be part of some XML processing pipeline.
- JSP documents can be manipulated by XML-aware tools.
- JSP documents can be generated from textual representations by applying an XML transformation, such as XSLT.
- A JSP document can be generated automatically, for example, by serializing some objects.

## Important Information about JSP Documents

The following are some important pieces of information pertaining to JSP documents:

- By default, files with the filename extension .jspx or .tagx are treated as JSP documents in the XML syntax.
- JSP property groups defined in the web.xml deployment descriptor can control which files in the Web application can be treated as being in the XML syntax. See Configuring JSP Property Groups.
- If a JSP file starts with <jsp:root>, then it is used in the XML syntax.
- XML namespaces are used instead of <%@taglib%> taglib tags (xmlns:prefix="...").
- The <jsp:scriptlet>, <jsp:declaration> and <jsp:expression> tags are used instead of <%...%>, <%!...%>, and <%=...%>.
- The <jsp:directive.page> and <jsp:directive.include> tags are used instead of <%@page%> and <%@include%>.
- Inside of attribute values, instead of using <%=...%> to denote an expression, only "%...%" is used.

For more information on JSP documents, see chapter 6, "JSP Documents," of the JSP 2.0 specification.