Oracle JavaServer Pages Developer's Guide and Reference Release 8.1.7 Part Number A83726-01 |
|
You have seen a simple example of JSP syntax in "What a JSP Page Looks Like"; now here is a top-level list of syntax categories and topics:
This section introduces each category, including basic syntax and a few examples. For more information, see the Sun Microsystems JavaServer Pages Specification, Version 1.1.
Notes: There are XML-compatible alternatives to the syntax for JSP directives, declarations, expressions, and scriptlets. See "XML-Alternative Syntax". |
Directives provide instruction to the JSP container regarding the entire JSP page. This information is used in translating or executing the page. The basic syntax is as follows:
<%@ directive attribute1="value1" attribute2="value2"... %>
The JSP 1.1 specification supports the following directives:
page
--Use this directive to specify any of a number of page-dependent attributes, such as the scripting language to use, a class to extend, a package to import, an error page to use, or the JSP page output buffer size. For example:
<%@ page language="java" import="packages.mypackage" errorPage="boof.jsp" %>
Or, to set the JSP page output buffer size to 20kb (the default is 8kb):
<%@ page buffer="20kb" %>
Or, to unbuffer the page:
<%@ page buffer="none" %>
include
--Use this directive to specify a resource that contains text or code to be inserted into the JSP page when it is translated. Specify the path of the resource relative to the URL specification of the JSP page.
Example:
<%@ include file="/jsp/userinfopage.jsp" %>
The include
directive can specify either a page-relative or context-relative location (see "Requesting a JSP Page" for related discussion).
Notes:
|
taglib
--Use this directive to specify a library of custom JSP tags that will be used in the JSP page. Vendors can extend JSP functionality with their own sets of tags. This directive indicates the location of a tag library description file and a prefix to distinguish use of tags from that library.
Example:
<%@ taglib uri="/oracustomtags" prefix="oracust" %>
Later in the page, use the oracust
prefix whenever you want to use one of the tags in the library (presume this library includes a tag dbaseAccess
):
<oracust:dbaseAccess> ... </oracust:dbaseAccess>
As you can see, this example uses XML-style start-tag and end-tag syntax.
JSP tag libraries and tag library description files are introduced later in this chapter, in "Tag Libraries", and discussed in detail in Chapter 7, "JSP Tag Libraries and the Oracle JML Tags".
JSP scripting elements include the following categories of snippets of Java code that can appear in a JSP page:
A JSP declaration uses standard Java syntax within the <%!...%>
declaration tags to declare a member variable or method. This will result in a corresponding declaration in the generated servlet code. For example:
<%! double f1=0.0; %>
This example declares a member variable, f1
. In the servlet class code generated by the JSP translator, f1
will be declared at the class top level.
A JSP expression does not end in a semi-colon, and is contained within <%=...%>
tags.
Example:
<P><B> Today is <%= new java.util.Date() %>. Have a nice day! </B></P>
A scriptlet, or code fragment, may consist of anything from a partial line to multiple lines of Java code. You can use them within the HTML code of a JSP page to set up conditional branches or a loop, for example.
A JSP scriptlet is contained within <%...%>
scriptlet tags, using normal Java syntax.
Example 1:
<% if (pageBean.getNewName().equals("")) { %> I don't know you. <% } else { %> Hello <%= pageBean.getNewName() %>. <% } %>
Three one-line JSP scriptlets are intermixed with two lines of HTML (one of which includes a JSP expression, which does not require a semi-colon). Note that JSP syntax allows HTML code to be the code that is conditionally executed within the if
and else
branches (inside the Java brackets set out in the scriptlets).
The preceding example assumes the use of a JavaBean instance, pageBean
.
Example 2:
<% if (pageBean.getNewName().equals("")) { %> I don't know you. <% empmgr.unknownemployee(); } else { %> Hello <%= pageBean.getNewName() %>. <% empmgr.knownemployee(); } %>
This example adds more Java code to the scriptlets, assuming the use of a JavaBean instance, pageBean
, and assuming that some object, empgr
, was previously instantiated and has methods to execute appropriate functionality for a known employee or an unknown employee.
Note: Use a JSP scriptlet to declare method variables, as opposed to member variables, as in the following example: <% double f2=0.0; %>
This scriptlet declares a method variable, Member variables are declared in JSP declarations as described above. For a comparative discussion, see "Method Variable Declarations Versus Member Variable Declarations". |
Comments are contained within <%--...--%>
tags. Unlike HTML comments, these comments are not visible when a user views the page source.
Example:
<%-- Execute the following branch if no user name is entered. --%>
In this document, the term JSP object refers to a Java class instance declared within or accessible to a JSP page. JSP objects can be either:
scope
setting you choose.
or:
scope
setting of the particular object type.
Scopes are discussed below, in "Object Scopes".
Explicit objects are typically JavaBean instances declared and created in jsp:useBean
action statements. The jsp:useBean
statement and other action statements are described in "JSP Actions and the <jsp: > Tag Set", but an example is also shown here:
<jsp:useBean id="pageBean" class="mybeans.NameBean" scope="page" />
This statement defines an instance, pageBean
, of the NameBean
class that is in the mybeans
package. The scope parameter is discussed in the next section, "Object Scopes".
You can also create objects within Java scriptlets or declarations, just as you would create Java class instances in any Java program.
Objects in a JSP, whether explicit or implicit, are accessible within a particular scope. In the case of explicit objects, such as a JavaBean instance created in a jsp:useBean
action statement, you can explicitly set the scope with the following syntax (as in the example in the preceding section, "Explicit Objects"):
scope="scopevalue"
There are four possible scopes:
scope="page"
--The object is accessible only from within the JSP page where it was created.
Note that when the user refreshes the page while executing a JSP page, new instances will be created of all page-scope objects.
scope="request"
--The object is accessible from any JSP page servicing the same HTTP request that is serviced by the JSP page that created the object.
scope="session"
--The object is accessible from any JSP page sharing the same HTTP session as the JSP page that created the object.
scope="application"
--The object is accessible from any JSP page used in the same Web application (within any single Java virtual machine) as the JSP page that created the object.
JSP technology makes available to any JSP page a set of implicit objects. These are Java class instances that are created automatically by the JSP mechanism and that allow interaction with the underlying servlet environment.
The following implicit objects are available. For information about methods available with these objects, refer to the Sun Microsystems Javadoc for the noted classes and interfaces at the following location:
http://java.sun.com/products/servlet/2.2/javadoc/index.html
page
This is an instance of the JSP page implementation class that was created when the page was translated; page
is synonymous with this
within a JSP page.
request
This represents an HTTP request and is an instance of a class that implements the javax.servlet.http.HttpServletRequest
interface, which extends the javax.servlet.ServletRequest
interface.
response
This represents an HTTP response and is an instance of a class that implements the javax.servlet.http.HttpServletResponse
interface, which extends the javax.servlet.ServletResponse
interface.
The response
and request
objects for a particular request are associated with each other.
pageContext
This represents the page context of a JSP page, which is provided for storage and access of all page
scope objects of a JSP page instance. A pageContext
object is an instance of the javax.servlet.jsp.PageContext
class.
The pageContext
object has page
scope, making it accessible only to the JSP page instance with which it is associated.
session
This represents an HTTP session and is an instance of the javax.servlet.http.HttpSession
class.
application
This represents the servlet context for the Web application and is an instance of the javax.servlet.ServletContext
class.
The application
object is accessible from any JSP page instance running as part of any instance of the application within a single JVM. (The programmer should be aware of the server architecture regarding use of JVMs. For example, in the Oracle Servlet Engine architecture, each user runs in his or her own JVM.)
out
This is an object that is used to write content to the output stream of a JSP page instance. It is an instance of the javax.servlet.jsp.JspWriter
class, which extends the java.io.Writer
class.
The out
object is associated with the response
object for a particular request.
config
This represents the servlet configuration for a JSP page and is an instance of a class that implements the javax.servlet.ServletConfig
interface. (Generally speaking, servlet containers use ServletConfig
instances to provide information to servlets during initialization. Part of this information is the appropriate ServletContext
instance.)
exception
(JSP error pages only)
This implicit object applies only to JSP error pages--these are pages to which processing is forwarded when an exception is thrown from another JSP page; they must have the page
directive isErrorPage
attribute set to true
.
The implicit exception
object is a java.lang.Exception
instance that represents the uncaught exception that was thrown from another JSP page and that resulted in this error page being invoked.
The exception
object is accessible only from the JSP error page instance to which processing was forwarded when the exception was encountered.
For an example of JSP error processing and use of the exception
object, see "JSP Runtime Error Processing".
Any of the implicit objects discussed in the preceding section may be useful. The following example uses the request
object to retrieve and display the value of the username
parameter from the HTTP request:
<H3> Welcome <%= request.getParameter("username") %> ! <H3>
JSP action elements result in some sort of action occurring while the JSP page is being executed, such as instantiating a Java object and making it available to the page. Such actions may include the following:
Action elements use a set of standard JSP tags that begin with <jsp:
syntax. Although the tags described earlier in this chapter that begin with <%
syntax are sufficient to code a JSP page, the <jsp:
tags provide additional functionality and convenience.
Action elements also use syntax similar to that of XML statements, with similar "begin" and "end" tags such as in the following example:
<jsp:sampletag attr1="value1" attr2="value2" ... attrN="valueN"> ...body... </jsp:sampletag>
Or, where there is no body, the action statement is terminated with an empty tag:
<jsp:sampletag attr1="value1", ..., attrN="valueN" />
The JSP specification includes the following standard action tags, which are introduced and briefly discussed here:
jsp:useBean
The jsp:useBean
action creates an instance of a specified JavaBean class, gives the instance a specified name, and defines the scope within which it is accessible (such as from anywhere within the current JSP page instance).
Example:
<jsp:useBean id="pageBean" class="mybeans.NameBean" scope="page" />
This example creates a page-scoped instance pageBean
of the mybeans.NameBean
class. This instance is accessible only from the JSP page instance that creates it.
jsp:setProperty
The jsp:setProperty
action sets one or more bean properties. (The bean must have been previously specified in a useBean
action.) You can directly specify a value for a specified property, or take the value for a specified property from an associated HTTP request parameter, or iterate through a series of properties and values from the HTTP request parameters.
The following example sets the user
property of the pageBean
instance (defined in the preceding useBean
example) to a value of "Smith":
<jsp:setProperty name="pageBean" property="user" value="Smith" />
The following example sets the user
property of the pageBean
instance according to the value set for a parameter called username
in the HTTP request:
<jsp:setProperty name="pageBean" property="user" param="username" />
Or, if the bean property and request parameter have the same name (user
), you can simply set the property as follows:
<jsp:setProperty name="pageBean" property="user" />
The following example results in iteration over the HTTP request parameters, matching bean property names with request parameter names and setting bean property values according to the corresponding request parameter values:
<jsp:setProperty name="pageBean" property="*" />
jsp:getProperty
The jsp:getProperty
action reads a bean property value, converts it to a Java string, and places the string value into the implicit out
object so that it can be displayed as output. (The bean must have been previously specified in a jsp:useBean
action.) For the string conversion, primitive types are converted directly and object types are converted using the toString()
method specified in the java.lang.Object
class.
The following example puts the value of the user
property of the pageBean
bean into the out
object:
<jsp:getProperty name="pageBean" property="user" />
jsp:param
You can use the jsp:param
action in conjunction with jsp:include
, jsp:forward
, or jsp:plugin
actions (described below).
For jsp:forward
and jsp:include
statements, a jsp:param
action optionally provides key/value pairs for parameter values in the HTTP request object. New parameters and values specified with this action are added to the request object, with new values taking precedence over old.
The following example sets the request object parameter username
to a value of Smith
:
<jsp:param name="username" value="Smith" />
jsp:include
The jsp:include
action inserts additional static or dynamic resources into the page at request time as the page is displayed. Specify the resource with a relative URL (either page-relative or application-relative).
As of the Sun Microsystems JavaServer Pages Specification, Version 1.1, you must set flush
to true
, which results in the buffer being flushed to the browser when a jsp:include
action is executed. (The flush
attribute is mandatory, but a setting of false
is currently invalid.)
You can also have an action body with jsp:param
settings, as shown in the second example.
Examples:
<jsp:include page="/templates/userinfopage.jsp" flush="true" />
or:
<jsp:include page="/templates/userinfopage.jsp" flush="true" > <jsp:param name="username" value="Smith" /> <jsp:param name="userempno" value="9876" /> </jsp:include>
Note that the following syntax would work as an alternative to the preceding example:
<jsp:include page="/templates/userinfopage.jsp?username=Smith&userempno=9876" flush="true" />
Notes:
|
jsp:forward
The jsp:forward
action effectively terminates execution of the current page, discards its output, and dispatches a new page--either an HTML page, a JSP page, or a servlet.
The JSP page must be buffered (you cannot set buffer="none"
) to use a jsp:forward
action. The action will clear the buffer (not outputting contents to the browser).
As with jsp:include
, you can also have an action body with jsp:param
settings, as shown in the second example.
Examples:
<jsp:forward page="/templates/userinfopage.jsp" />
or:
<jsp:forward page="/templates/userinfopage.jsp" > <jsp:param name="username" value="Smith" /> <jsp:param name="userempno" value="9876" /> </jsp:forward>
jsp:plugin
The jsp:plugin
action results in the execution of a specified applet or JavaBean in the client browser, preceded by a download of Java plugin software if necessary.
Specify configuration information, such as the applet to run and the codebase, using jsp:plugin
attributes. The JSP container might provide a default URL for the download, but you can also specify attribute nspluginurl="
url
"
(for a Netscape browser) or iepluginurl="
url
"
(for an Internet Explorer browser).
Use nested jsp:param
actions within <jsp:params>
and </jsp:params>
start and end tags to specify parameters to the applet or JavaBean. (Note that these jsp:params
start and end tags are not necessary when using jsp:param
in a jsp:include
or jsp:forward
action.)
Use <jsp:fallback>
and </jsp:fallback>
start and end tags to delimit alternative text to execute if the plugin cannot run.
The following example, from the Sun Microsystems JavaServer Pages Specification, Version 1.1, shows use of an applet plugin:
<jsp:plugin type=applet code="Molecule.class" codebase="/html" > <jsp:params> <jsp:param name="molecule" value="molecules/benzene.mol" /> </jsp:params> <jsp:fallback> <p> Unable to start the plugin. </p> </jsp:fallback> </jsp:plugin>
Many additional parameters--such as ARCHIVE
, HEIGHT
, NAME
, TITLE
, and WIDTH
--are allowed in the jsp:plugin
action statement as well. Use of these parameters is according to the general HTML specification.
In addition to the standard JSP tags discussed previously in this section, the JSP specification lets vendors define their own tag libraries and also lets vendors implement a framework allowing customers to define their own tag libraries.
A tag library defines a collection of custom tags and can be thought of as a JSP sub-language. Developers can use tag libraries directly, in manually coding a JSP page, but they might also be used automatically by Java development tools. A tag library must be portable between different JSP container implementations.
Import a tag library into a JSP page using the taglib
directive, introduced in "Directives".
Key concepts of standard JavaServer Pages support for JSP tag libraries include the following topics:
A tag handler describes the semantics of the action that results from use of a custom tag. A tag handler is an instance of a Java class that implements either the Tag
or BodyTag
interface (depending on whether the tag uses a body between a start tag and an end tag) in the standard javax.servlet.jsp.tagext
package.
Custom tag actions can create server-side objects available for use by the tag itself or by other scripting elements such as scriptlets. This is accomplished by creating or updating scripting variables.
Details regarding scripting variables that a custom tag defines must be specified in a subclass of the standard javax.servlet.jsp.tagext.TagExtraInfo
abstract class. This document refers to such a subclass as a tag-extra-info class. The JSP container uses instances of these classes during translation.
A tag library description (TLD) file is an XML document that contains information about a tag library and about individual tags of the library. The file name of a TLD has the .tld
extension.
A JSP container uses the TLD file in determining what action to take when it encounters a tag from the library.
web.xml
for tag libraries
The Sun Microsystems Java Servlet Specification, Version 2.2 describes a standard deployment descriptor for servlets--the web.xml
file. JSP applications can use this file in specifying the location of a JSP tag library description file.
For JSP tag libraries, the web.xml
file can include a taglib
element and two subelements: taglib-uri
and taglib-location
.
For information about these topics, see "Standard Tag Library Framework".
For information about the sample tag library provided with OracleJSP, see "Overview of the JSP Markup Language (JML) Sample Tag Library"
For further information, see the Sun Microsystems JavaServer Pages Specification, Version 1.1.
|
![]() Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
|