The following sections describe how to create and configure JSPs.
WebLogic JSP supports the JSP 2.1 specification at http://java.sun.com/products/jsp/ from Sun Microsystems. The main theme for Java EE is ease of development. The platform's Web tier contributes significantly to ease of development in two ways. First, the platform now includes the JavaServer Pages Standard Tag Library (JSTL) and JavaServer Faces technology. Second, all the Web-tier technologies offer a set of features that make development of Web applications on Java EE much easier, such as complete alignment of JavaServer Faces technology tags and JavaServer Pages (JSP) software code.
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 Appendix B, "jsp-descriptor,".
You can register a JSP as a servlet using the servlet element of the Java EE 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.
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 for Oracle WebLogic Server.
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:
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:
Example 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 at http://java.sun.com/products/servlet/download.html#specs.
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 Java EE standard Web application deployment descriptor, web.xml. (The web.xml file is located in the WEB-INF directory of your Web application.)
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.
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 Appendix B, "charset-mapping,".
For example:
<charset-mapping>
<iana-charset-name>Shift-JIS</iana-charset-name>
<java-charset-name>SJIS</java-charset-name>
</charset-mapping>
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:
<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>
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.5 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.
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.
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.1 specification at http://java.sun.com/products/jsp/.
The JSP 2.1 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," at http://java.sun.com/products/jsp/.
Example 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>
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.
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.1 specification at http://java.sun.com/products/jsp/.