JSP.2.7 Directives


Directives are messages to the JSP container. In JSP 1.1, directives have this syntax:

  <%@ directive { attr="value" }* %>  

There may be optional white space after the "<%@" and before "%>".

This syntax is easy to type and concise but it is not XML-compatible. Chapter JSP.7 describes the mapping of directives into XML elements.

Directives do not produce any output into the current out stream.

The remainder of this section describes the standard directives that are available on all conforming JSP 1.1 implementations .

JSP.2.7.1 The page Directive

The page directive defines a number of page-dependent attributes and communicates these to the JSP container.

A translation unit (JSP source file and any files included via the include directive) can contain more than one instance of the page directive; all the attributes will apply to the complete translation unit (i.e., page directives are position independent). However, there shall be only one occurrence of any attribute/value defined by this directive in a given translation unit with the exception of the import attribute; multiple uses of this attribute are cumulative (with ordered set union semantics). Other such multiple attribute/value (re)definitions result in a fatal translation error.

The attribute/value namespace is reserved for use by this, and subsequent , JSP specification(s).

Unrecognized attributes or values result in fatal translation errors.

Examples

The following directive provides some user -visible information on this JSP page:

 <%@ page info="my latest JSP Example V1.1" %> 

The following directive requests no buffering, indicates that the page is thread safe, and provides an error page.

 <%@ page buffer="none" isThreadSafe="yes"     errorPage="/oops.jsp" %> 

The following directive indicates that the scripting language is based on Java, that the types declared in the package com.myco are directly available to the scripting code, and that a buffering of 16K should be used.

 <%@ page language="java" import="com.myco.*" buffer="16k" %> 
JSP.2.7.1.1 Syntax
 <%@  page page_directive_attr_list  %>  page_directive_attr_list  ::=  { language="  scriptingLanguage  "}                                { extends="  className  "         }                                { import="  importList  "         }                                { session="truefalse"        }                                { buffer="none  sizekb  "        }                                { autoFlush="true  false  "      }                                { isThreadSafe="truefalse"   }                                { info="  info_text  "            }                                { errorPage="  error_url  "       }                                { isErrorPage="truefalse"    }                                { contentType="ctinfo"        } 

The details of the attributes are given in Table JSP.2-1.

Table JSP.2-1. Attributes of the page Directive

language

Defines the scripting language to be used in the scriptlets, expression scriptlets, and declarations within the body of the translation unit (the JSP page and any files included using the include directive below).

In JSP 1.1, the only defined and required scripting language value for this attribute is " java ." This specification only describes the semantics of scripts for when the value of the language attribute is "java."

When " java " is the value of the scripting language, the Java programming language source code fragments used within the translation unit are required to conform to the Java Programming Language Specification in the way indicated in Chapter JSP.4.

All scripting languages must provide some implicit objects that a JSP page author can use in declarations, scriptlets, and expressions. The specific objects that can be used are defined in Section JSP.2.8, "Implicit Objects."

All scripting languages must support the Java runtime environment (JRE). All scripting languages must expose the Java technology object model to the script environment, especially implicit variables , JavaBeans component properties, and public methods .

Future versions of the JSP specification may define additional values for the language attribute and all such values are reserved.

It is a fatal translation error for a directive with a non- "java" language attribute to appear after the first scripting element has been encountered .

extends

The value is a fully qualified Java programming language class name that names the superclass of the class to which this JSP page is transformed (see Chapter JSP.3).

This attribute should not be used without careful consideration as it restricts the ability of the JSP container to provide specialized superclasses that may improve on the quality of rendered service. See Section JSP.5.8.1 for an alternate way to introduce objects into a JSP page that does not have this drawback.

import

An import attribute describes the types that are available to the scripting environment. The value is as in an import declaration in the Java programming language, i.e., a (comma separated) list of either a fully qualified Java programming language type name denoting that type, or of a package name followed by the ".*" string, denoting all the public types declared one in that package. The import list shall be imported by the translated JSP page implementation and is thus available to the scripting environment.

The default import list is java.lang.* , javax.servlet.* , javax.servlet.jsp.* , and javax.servlet.http.* .

This value is currently defined only when the value of the language directive is " java ."

session

Indicates that the page requires participation in an (HTTP) session.

If " true " then the implicit script language variable named " session " of type javax.servlet.http.HttpSession references the current/new session for the page.

If " false " then the page does not participate in a session; the " session " implicit variable is unavailable, and any reference to it within the body of the JSP page is illegal and shall result in a fatal translation error.

Default is " true ."

buffer

Specifies the buffering model for the initial " out " JspWriter to handle content output from the page.

If " none ," then there is no buffering and all output is written directly through to the ServletResponse PrintWriter .

If a buffer size is specified (e.g., 12kb ) then output is buffered with a buffer size not less than that specified.

Depending upon the value of the " autoFlush " attribute, either the contents of this buffer are automatically flushed or an exception is raised when overflow would occur.

The default is buffered with an implementation buffer size of not less than 8kb .

autoFlush

Specifies whether the buffered output should be flushed automatically (" true " value) when the buffer is filled, or whether an exception should be raised (" false " value) to indicate buffer overflow.

The default is " true ."

Note

It is illegal to set autoFlush to "false " when "buffer=none ."


isThreadSafe

Indicates the level of thread safety implemented in the page.

If " false " then the JSP container shall dispatch multiple outstanding client requests, one at a time, in the order they were received, to the page implementation for processing.

If " true " then the JSP container may choose to dispatch multiple outstanding client requests to the page simultaneously .

Page authors using " true " must ensure that they properly synchronize access to page shared state.

Default is " true ."

Note that even if the isThreadSafe attribute is " false ," the JSP page author must ensure that access to any shared objects shared in either the ServletContext or the HttpSession are properly synchronized. See Section JSP.2.7.2

info

Defines an arbitrary string that is incorporated into the translated page, that can subsequently be obtained from the page's implementation of the Servlet.getServletInfo() method.

isErrorPage

Indicates if the current JSP page is intended to be the URL target of another JSP page's errorPage .

If " true ," then the implicit script language variable " exception " is defined and its value is a reference to the offending Throwable from the source JSP page in error.

If " false " then the " exception " implicit variable is unavailable, and any reference to it within the body of the JSP page is illegal and shall result in a fatal translation error.

Default is " false ."

errorPage

Defines a URL to a resource to which any Java programming language Throwable object(s) thrown but not caught by the page implementation are forwarded for error processing.

The provided URL spec is as in Section JSP.2.5.2.

The resource named has to be a JSP page in this version of the specification.

If the URL names another JSP page, then when invoked that JSP page's exception implicit script variable shall contain a reference to the originating uncaught Throwable .

The default URL is implementation dependent.

Note the Throwable object is transferred by the throwing page implementation to the error page implementation by saving the object reference on the common ServletRequest object using the setAttribute() method, with a name of

 "javax.servlet.jsp.jspException." 

Note

If autoFlush=true then if the contents of the initial JspWriter have been flushed to the ServletResponse output stream, any subsequent attempt to dispatch an uncaught exception from the offending page to an errorPage may fail.


contentType

Defines the character encoding for the JSP page and for the response of the JSP page and the MIME type for the response of the JSP page.

Values are either of the form " TYPE " or " TYPE; charset=CHARSET " with an optional white space after the ";". CHARSET , if present, must be the IANA value for a character encoding. TYPE is a MIME type; see the IANA registry for useful values.

The default value for TYPE is " text/html "; the default value for the character encoding is ISO-8859-1.

See Section JSP.2.7.4 for complete details on character encodings.

JSP.2.7.2 Synchronization Issues

JSP Pages inherit the servlet semantics as described in the Servlet 2.2 specification. In this section we briefly summarize the threading and distribution issues from that specification, as they apply to JSP pages.

A distributed container is one capable of distributing web components that are tagged as distributable across different multiple Java virtual machines, perhaps running in different hosts . A distributable application is one tagged as such in its web deployment descriptor. A distributable JSP page is one in a distributable application.

By default, there must be only one instance of a JSP page implementation class per JSP page definition in a container (Section SRV.3.2 of Servlet 2.2 spec). By default, an instance of a web application must be run on only one Java virtual machine at any one time. This behavior can be overridden by declaring the application to be distributable (Chapter SRV.9 of Servlet 2.2. specification).

A single threaded JSP page is one with a false value for its isThreadSafe attribute of a page directive. If isThreadSafe="false , " the JSP page implementation shall implement javax.servlet.SingleThreadModel , thus indicating that all requests dispatched to that instance shall be delivered serially to the service() method of the page implementation class (Section SRV.3.3.3.1 of Servlet 2.2 spec).

However, some implementations may additionally use a pool consisting of multiple page implementation class instances to do load balancing. Therefore, even when indicating that the page is not thread safe, a page author cannot assume that all requests mapped to a particular JSP page shall be delivered to the same instance of that page's implementation class. The consequence of this is that an author must assume that any mutable resources not private/unique to a particular page's instance may be accessed/updated simultaneously by two or more instances; thus any static field values, objects with session or application scope, or objects shared through some other (unspecified) mechanism by such instances must be accessed appropriately synchronized to avoid non-deterministic behaviors (Section SRV.3.2.1 of Servlet 2.2 spec).

In the case of a distributable JSP page, there is one instance of its JSP page implementation class per web component definition per Java virtual machine in a distributed container (Section SRV.3.2 of Servlet 2.2 spec).

If multiple web component definitions in the deployment descriptor indicate the same JSP page, there will be multiple instances of the JSP page implementation class, with different initialization parameters (Section SRV.3.3.1 of Servlet 2.2 spec).

There is only one instance of the ServletContext interface associated with each web application deployed into a web container. In cases where the container is distributed over many Java virtual machines, there is one instance per web application per Java virtual machine (Section SRV.4.1 of Servlet 2.2 spec).

Context attributes exist locally to the Java virtual machine in which they were created and placed. This prevents the ServletContext from being used as a distributed shared memory store. If information needs to be shared between servlets run-ning in a distributed environment, that information should be placed in a session, a database, or in an Enterprise JavaBean (Section SRV.4.3.1 of Servlet 2.2 spec).

Within an application that is marked as distributable, all requests that are part of a session can be handled on only a single Java virtual machine at any one time. In addition, all objects placed into the session must implement the Serializable interface. The servlet container may throw an IllegalArgumentException if a non-serializable object is placed into the session (Section SRV.7.7.2 in Servlet 2.2 spec).

JSP.2.7.3 Specifying Content Types

A JSP page can use the contentType attribute of the page directive to indicate the content type of the response it provides to requests. Since this value is part of a directive, a given page will always provide the same content type. If a page determines that the response should be of a different content type, it should do so "early," determine what other JSP page or servlet will handle this request, and forward the request to the other JSP page or servlet.

A registry of content type names is kept by IANA. See:

ftp://venera.isi.edu/in-notes/iana/assignments/media-types/media-types

JSP.2.7.4 Delivering Localized Content

The Java platform support for localized content is based on a uniform representation of text internally as Unicode 2.0 (ISO010646) characters and the support for a number of character encodings to and from Unicode.

Any Java virtual machine (JVM) must support Unicode and Latin-1 encodings but most support many more. The character encodings supported by the JVM from Sun are described at:

http://java.sun.com/products/jdk/1.1/docs/guide/intl/encoding.doc.html

The JSP 1.1 specification assumes that JSP pages that will deliver content in a given character encoding will be written in that character encoding. In particular, the contentType attribute of the page directive describes both the character encoding of the JSP page and the character encoding of the resulting stream.

The valid names to describe the character encodings are those of IANA. They are described at:

ftp://venera.isi.edu/in-notes/iana/assignments/character-sets

The contentType attribute must be used only when the character encoding is organized such that ASCII characters stand for themselves , at least until the contentType attribute is found. The directive containing the contentType attribute should appear as early as possible in the JSP page.

The default character set encoding is ISO-8859-1 (also known as latin-1).

A JSP container may use some implementation-dependent heuristics and/or structure to determine the expected character encoding of a JSP page and then verify that contentType attribute is as expected.

A JSP container will raise a translation-time error if an unsupported character encoding is requested .

See Section JSP.B.1 for some implementation notes.

JSP.2.7.5 Including Data in JSP Pages

Including data is a significant part of the tasks in a JSP page. Accordingly, the JSP 1.1 specification has two include mechanisms suited to different tasks . A summary of their semantics is shown in Table JSP.2-2.

Table JSP.2-2. Summary of Include Mechanisms in JSP 1.1

Syntax

What

Phase

Spec

Object

Description

Section

<%@ include file=... %>

directive

translation-time

virtual

static

Content is parsed by JSP container.

JSP.2.7.6

<jsp:include page= />

action

request-time

virtual

static and dynamic

Content is not parsed; it is included in place.

JSP.2.13.4

The Spec column describes what type of specification is valid to appear in the given element. The JSP specification requires a relative URL spec as described in Section JSP.2.5.2. The reference is resolved by the web/application server and its URL map is involved.

An include directive regards a resource like a JSP page as a static object; i.e., the bytes in the JSP page are included. An include action regards a resource like a JSP page as a dynamic object; i.e., the request is sent to that object and the result of processing it is included.

JSP.2.7.6 The include Directive

The include directive is used to substitute text and/or code at JSP page translation time. The <%@ include file="relativeURLspec" %> directive inserts the text of the specified resource into the . jsp file. The included file is subject to the access control available to the JSP container. The file attribute is as in Section JSP.2.5.2.

A JSP container can include a mechanism for being notified if an included file changes, so the container can recompile the JSP page. However, the JSP 1.1 specification does not have a way of directing the JSP container that included files have changed.

Examples

The following example requests the inclusion, at translation time, of a copyright file. The file may have elements which will be processed too.

 <%@ include file="copyright.html" %> 
JSP.2.7.6.1 Syntax
 <%@ include file="  relativeURLspec  " %> 

JSP.2.7.7 The taglib Directive

The set of significant tags a JSP container interprets can be extended through a "tag library."

The taglib directive in a JSP page declares that the page uses a tag library, uniquely identifies the tag library using a URI, and associates a tag prefix that will distinguish usage of the actions in the library.

The URI identifying a tag library may be any valid URI as long as it can be used to uniquely identify the semantics of the tag library. A common mechanism is to encode the version of a tag library into its URI.

If a JSP container implementation cannot locate (following the rules described in Section JSP.5.3.1) a tag library description for a given URI, a fatal translation error shall result.

It is a fatal translation error for the taglib directive to appear after actions using the prefix introduced by the taglib directive.

See Chapter JSP.5 for more specification details, and Section JSP.B.2 for an implementation note.

Examples

In the following example, a tag library is introduced and made available to this page using the super prefix; no other tag libraries should be introduced in this page using this prefix. In this particular case, we assume the tag library includes a doMagic element type, which is used within the page.

 <%@ taglib uri="http://www.mycorp/supertags" prefix="super" />  ...  <super:doMagic>  ...  </super:doMagic> 
JSP.2.7.7.1 Syntax
 <%@ taglib uri="  tagLibraryURI  " prefix="  tagPrefix  " %> 

where the attributes are given in Table JSP.2-3.

Table JSP.2-3. Attributes of the taglib Directive

uri

Either an absolute URI or a relative URI specification to be interpreted as in Section JSP.2.5.2 that uniquely identifies the tag library descriptor associated with this prefix.

The URI is used to locate a description of the tag library as indicated in Chapter JSP.5.

tagPrefix

Defines the prefix string in <prefix>:< tagname > that is used to distinguish a custom action, e.g., <myPrefix:myTag> .

Prefixes jsp:, jspx:, java:, javax:, servlet:, sun:, and sunw: are reserved. Empty prefixes are illegal in this version of the specification.

A fatal translation-time error will result if the JSP page translator encounters a tag with name prefix:Name using a prefix introduced using the taglib directive, and Name is not recognized by the corresponding tag library.



Java 2 Platform, Enterprise Edition. Platform and Component Specifications
Java 2 Platform, Enterprise Edition: Platform and Component Specifications
ISBN: 0201704560
EAN: 2147483647
Year: 2000
Pages: 399

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net