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 DirectiveThe 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. ExamplesThe 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
JSP.2.7.2 Synchronization IssuesJSP 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 TypesA 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 ContentThe 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 PagesIncluding 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
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 DirectiveThe 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. ExamplesThe 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 DirectiveThe 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. ExamplesIn 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
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. |