APPENDIX A JSP Syntax Reference THISAPPENDIX DESCRIBES the syntax for JavaServer Pages (JSP) 2.0. Dur intention is to provide you with a reference that's complete and useful but more compact than the specification. (The JSP 2.0 specification weighs in at 478 pages!) NOTE j5P specifica tions front version 2.0 011 are avai/able by visiting http://java .sun .com/products/jsp/. This appendix looks in turn at the following: • Various preliminary details: The notation we use, how you specify uniform resource locators (URLs) in JSP code, and the various types ofcommenting you can use. • The JSP directives: The page, taglib, and include directives. • JSP scripting elements: Declarations, scriptlets, and expressions. • JSP standard actions: The <jsp :useBean>, <jsp :setProperty>, <jsp :getProperty>, <jsp :include>, and <jsp :forward> actions. • Tag libraries: A briefreview ofthe syntax for using tag libraries. • Implicit objects: The implicit objects that are available within a JSP page such as request, response, session, and application. Appendix B covers these in more detail. • Attributes:Various predefined request and application attributes that you may find useful. 363 AppendixA Preliminaries Before getting stuck in the details, the following sections make a few miscelIa­ neous observations. Notation This appendix uses the following notation: • ltalics show what you'll have to specify. • Bold shows the default value of an attribute. Attributes with default values are optional ifyou're using the default; sometimes, where the default value is a little complicated, we use default to indicate that the default is described in the following text. • When an attribute has a set of possible values, those are delimited by I: import="package .dass, package . *, session="truelfalse" URL Specifications URLsspecified within JSP tags can be of two sorts: • Context-relative paths start with /; the base URLis provided by theWeb appli­ cation to which the JSPpage belongs. For example, in aWeb application hosted at http://localhost:8080/begjsp-appendixA/, the URL/pageurl. jsp would be equivalenttohttp://localhost:8080/begjsp-appendixA/pageurl.jsp. • Page-relative paths are relative to the JSP page in which they occur. Unlike context-relative paths, page-relative paths don't start with /; for instance, a page application hosted at http://localhost:808o/begjsp-appendixA/ morespecs/urlspec .jsp might give a page as subfolder/urlspec.jsp, which would be equivalent to http://localhost:808o/begjsp-appendixA/morespecs/ subfolder/urlspec.jsp. 364 JSPSyntax Reference Comments Two sorts of comments are allowed in JSP code: JSPand HTMLcomments: <!-- HTML comments remain in the final client page . They can contain JSP expressions, which will be processed by the JSP container. --> <%-- JSP comments are hidden from the final client page --%> Remember too that within scriptlets (inside <% %» , you can use standard Java comments: <% /* This Java comment starts with a slash asterisk, and continues until we come to a closing asterisk slash */ // Comments starting with a double slash continue to the end of the line %> Directives Directives are instructions to the JSP container regarding setting page properties, importing tag libraries, and including content within a JSP; because directives are instructions rather than in-out processes, they can't produce any output via the out stream. The page Directive The pagedirective specifies attributes for the page; all the attributes are optional, and the essential ones have default values, shown in bold: <%@ page language="java" extends="package .dass" import="package .dass, package .*, session="trueIfalse" buffer="noneldefaultlsizekb" autoFlush="true Ifalse" isThreadSafe="truelfalse" info="Sample JSP to show tags" 365 AppendixA isErrorPage="trueI false" errorPage="ErrorPage .jsp" contentType= "TYPEI TYPE; charset=CHARSETI text/html; charset=ISO-8859-1" pageEncoding="default" isELIgnored="trueI false" %> Bear the following in mind when using this directive: • The default buffer size is defined to be at least 8 kilobytes (KB) . • The errorPage attribute contains the relative URLfor the error page to which this page should go if there's an unhandled error on this page. • The specified error page file must declare isErrorPage="true" to have access to the Exception object. • The contentType attribute sets the MIMEtype and the character set for the response. The default value is "t ext / html" for standard JSP pages and "text/xml " when implementing JSP documents in Extensible Markup Language (XML) format. • The pageEncoding attribute defines the character encoding for the JSP page. The default is that specified in the contentType attribute or "150-8859-1" if none was specified there. This is an example of the code that may be used for an error page: <%@ page language="java" isErrorPage="true" %> <html> <body> <! -- This displays the fully-qualified name of the exception and its message--> <%= exception.toString() %> cbr» <!-- This displays the exception's descriptive message --> <%= exception .getMessage() %> </body> </html> The page will print the error message received . 366 JSPSyntax Reference This directive can also switch on support for scripting and EL in the JSP document, using the isELIgnored attribute, which sets Expression Language (EL) support. Settings in web. xml may influence the behavior of this attribute. For this attribute, a value of true enables support, and false disables it. The default value is true. The taglib Directive A tag library is a collection of tags used to extend a JSPcontainer functional model. The taglib directive defines a tag library namespace for the page, mapping the uniform resource indicator (UR!) of the tag library descriptor to a preflx that can be used to reference tags from the library on this page. <%@ taglib ( uri="tagLibraryURI" I tagdir="tagDir" ) prefix="tagPrefix" %> <tagPrefix :tagName attributeName="attributeValue" > JSP content <ltagPrefix:tagName> <tagPrefix :tagName attributeName="attributeValue" I> Youcan assume that the tag library descriptor (TLD) defines a tagName element. tagdir indicates this prefix is for identifying tag extensions installed in the IWEB-INF/tagsl directory or a subdirectory. Ifa TLD is present in the specified directory, it's used. Otherwise, an implicit tag library descriptor, generated by the container, is used.A translation error must occur if the value doesn't start with IWEB-INF/tags/. A translation error must occur ifthe value doesn't point to a directory that exists. A translation error must occur if used in conjunction with the uri attribute. The tag Directive Youcan use most JSPdirectives in simple tag handler code files. Note that the page directive itself isn't used; instead, you use the tag directive, which may only be used in tag files. Here's the syntax: 367 AppendixA tag_directive_attr_list ::= { display-name="display-name" } { body-content="scriptlessltagdependentlempty" } { dynamic-attributes="name" } { small-icon="small-icon" } { large-icon="large-icon" } { description="description" } { example="example" } { language="scriptingLanguage" } { import="imporUist" } { pageEncoding="peinfo" } { isELIgnored="truelfalse" } This is an example tag directive: <%@ tag name="msg" display-name= "Message" body-content="scriptless" dynamic-attributes="user" small-icon="/WEB-INF/small-icon.jpg" large-icon="/WEB-INF/large-icon .jpg" description="Simple usage of a tag directive" %> The include Directive There are two include tags: the include directive and the j sp: include action. The include directive includes a static file at translation time, adding any JSP in that file to this page for run-time processing: <%@ include file="header .html" %> See also the jsp:include action. The attribute Directive The attribute directive is analogous to the cattr.ibutes element in the TLDand allows you to declare custom action attributes. This is the syntax: 368 JSPSyntax Reference <%@ attribute attribute_directive_attr_list %> attribute-directive--attr list ..- name= "attribute-name" { required="true Ifalse" } { fragment="truelfalse" } { rtexprvalue="truelfalse" } { type="type" } { description="description" } The variable Directive The variable directive is analogous to the <variable> element in the TLD and allows you to define a variable exposed by the tag handler. This is the syntax: <%@ variable variable_directive_attr_list %> variable- directive--attr list :: = ( name -given="output-name" I ( name-from-attribute="attr-name" alias="local-name"» { variable-class="output -type" } { declare="truelfalse" } { scope= "AT_BEGINIAT_ENDINESTED"} { description="description" } Scripting Elements Youuse scripting elements to include snippets of Java code within a JSP:to declare variables and methods, to execute arbitrary Java code, and to display the result of Java expressions. Declarations The following syntax allows you to declare variables and methods for the page. These are placed in the generated servlet outside the _jspService() method; in other words, variables declared here will be instance variables of the servlet. Declarations don't produce any output. This is an example of declaring a variable: <%1 String message; %> 369 AppendixA The following code declares a variable and initializes it: <% 1 String message = "variable declarared"; %> You can define a method for use on the global page like so: <% 1 public String showMessage() { return message; } %> Declaration tags are mainly used in conjunction with scriptlets. Scriptlets Scriptlets enclose Java code (on