JSP.5.3 Tag Library Descriptor


The tag library descriptor (TLD) is an XML document that describes a tag library. The TLD for a tag library is used by a JSP container to interpret pages that include taglib directives referring to that tag library. The TLD is also used by JSP page authoring tools that will generate JSP pages that use a library, and by authors who do the same manually.

The TLD includes documentation on the library as a whole and on its individual tags, version information on the JSP container and on the tag library, and information on each of the actions defined in the tag library.

Each action in the library is described by giving its name , the class for its tag handler, optional information on a TagExtraInfo class, and information on all the attributes of the action. Each valid attribute is mentioned explicitly, with indication of whether it is mandatory or not, whether it can accept request-time expressions, and additional information.

A TLD file is useful as a descriptive mechanism for providing information on a tag library. It has the advantage that it can be read by tools without having to instantiate objects or load classes. The approach we follow conforms to the conventions used in other J2EE technologies.

The DTD to the tag library descriptor is organized so that interesting elements have an optional ID attribute. This attribute can be used by other documents, like vendor-specific documents, to provide annotations of the TLD information. An alternative approach, based on XML name spaces, has some interesting properties but it was not pursued in part for consistency with the rest of the J2EE descriptors.

The official DTD is described at "http://java.sun.com/j2ee/dtds/web-jsptaglibrary_1_1.dtd."

JSP.5.3.1 Locating a Tag Library Descriptor

The URI describing a tag library is mapped to a tag library descriptor file though two mechanisms: a map in web.xml described using the taglib element, and a default mapping.

JSP.5.3.1.1 taglib Map in web.xml

The map in web.xml is described using the taglib element of the web application deployment descriptor in WEB-INF/web.xml , as described in the Servlet 2.2 spec and in "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd."

A taglib element has two subelements: taglib-uri and taglib-location .

taglib

A taglib is a subelement of web-app :

 <!ELEMENT web-app .... taglib* .... > 

The taglib element provides information on a tag library that is used by a JSP page within the web application.

A taglib element has two subelements and one attribute:

 <!ELEMENT taglib ( taglib-uri, taglib-location ) >  <!ATTLIST taglib id ID #IMPLIED> 

taglib-uri

A taglib-uri element describes a URI identifying a tag library used in the web application.

 <!ELEMENT taglib-uri (#PCDATA) >  PCDATA ::= a URI spec. It may be either an absolute URI specification, or a relative URI as in Section JSP.2.5.2. 

taglib-location

A taglib-location contains the location (as a resource) where the tag library descriptor file for this tag library can be found.

 <!ELEMENT taglib-location (#PCDATA) >  PCDATA ::= a resource location, as indicated in Section JSP.2.5.2, where to find the tag library descriptor file. 
Example

The use of relative URI specifications enables very short names in the taglib directive. For example:

 <%@ taglib uri="/myPRlibrary" prefix="x" %> 

and then

 <taglib>    <taglib-uri>/myPRlibrary</taglib-uri>    <taglib-location>/WEB-INF/tlds/PRlibrary_1_4.tld</taglib-uri>  </taglib> 
JSP.5.3.1.2 Default Location

If there is no taglib-uri subelement that matches the URI used in a taglib directive, the tag library descriptor will be searched in the location indicated by the URI itself.

This rule applies only to URIs that are relative URI specifications (as in Section JSP.2.5.2).

Example

This rule allows a taglib directive to refer directly to the TLD. This arrangement is very convenient for quick development at the expense of less flexibility and accountability. For example, in the case above it enables:

 <%@ taglib uri="/tlds/PRlibrary_1_4.tld" prefix="x" %> 

JSP.5.3.2 Translation-Time Class Loader

The set of classes available at translation time is the same as that available at runtime: the classes in the underlying Java platform, those in the JSP container, and those in the class files in WEB-INF/classes , in the JAR files in WEB-INF/lib , and, indirectly through the use of the class- path attribute in the META-INF/MANIFEST file of these JAR files.

JSP.5.3.3 Assembling a Web Application

As part of the process of assembling a web application, the application assembler will create a WEB-INF/ directory, with appropriate lib/ and classes/ subdirectories, place JSP pages, servlet classes, auxiliary classes, and tag libraries in the proper places and then create a WEB-INF/web.xml that ties everything together.

Tag libraries that have been delivered in the standard format can be dropped directly into WEB-INF/lib . The assembler may create taglib entries in web.xml for each of the libraries that are to be used.

Part of the assembly (and later the deployment) may create and/or change information that customizes a tag library; see Section JSP.5.8.3.

JSP.5.3.4 Well-Known URIs

A JSP container may "know of" some specific URIs and may provide alternate implementations for the tag libraries described by these URIs, but the user must see the same behavior as that described by the, required, portable tag library description described by the URI.

A JSP container must always use the mapping specified for a URI in the web.xml deployment descriptor if present. If the deployer wants to use the platform-specific implementation of the well-known URI, the mapping for that URI should be removed at deployment time.

If there is no mapping for a given URI and the URI is not well-known to the JSP container, a translation-time error will occur.

There is no guarantee that this "well-known URI" mechanism will be preserved in later releases of the JSP specification. As experience accumulates on how to use tag extensions, the JSP specification may incorporate new functionality that will make the "well-known URI" mechanism unnecessary; at that point it may be removed.

JSP.5.3.5 The Tag Library Descriptor Format

This section describes the DTD for the tag library descriptor. This is the same DTD as "http://java.sun.com/j2ee/dtds/web-jsptaglibrary_1_1.dtd" except for some formatting changes to extract comments and make them more readable.

Notation
 <!NOTATION WEB-JSPTAGLIB.1_1 PUBLIC "-//Sun Microsystems, Inc.//DTD JSP Tag Library 1.1//EN"> 

taglib

The taglib element is the document root. A taglib has two attributes.

 <!ATTLIST  taglib  id             ID             #IMPLIED     xmlns             CDATA             #FIXED             "http://java.sun.com/j2ee/dtds/web-jsptaglibrary_1_1.dtd"  > 

A taglib element also has several subelements that define:

tlibversion

the version of the tag library implementation

jspversion

the version of JSP specification the tag library depends upon

shortname

a simple default short name that could be used by a JSP page authoring tool to create names with a mnemonic value; for example, it may be used as the preferred prefix value in taglib directives.

uri

a uri uniquely identifying this taglib .

info

a string describing the "use" of this taglib

 <!ELEMENT  taglib  (tlibversion, jspversion?,      shortname, uri?, info?,      tag+) > 

tlibversion

Describes this version (number) of the tag library.

The syntax is:

 <!ELEMENT  tlibversion  (#PCDATA) >  #PCDATA ::= [0-9]*{ "."[0-9] }0..3 

jspversion

Describes the JSP specification version (number) this tag library requires in order to function. The default is 1.1

The syntax is:

 <!ELEMENT  jspversion  (#PCDATA) >  #PCDATA ::= [0-9]*{ "."[0-9] }0..3. 

shortname

Defines a simple default short name that could be used by a JSP page authoring tool to create names with a mnemonic value; for example, it may be used as the preferred prefix value in taglib directives and/or to create prefixes for IDs. Do not use white space, and do not start with digits or underscore .

The syntax is

 <!ELEMENT  shortname  (#PCDATA) >  #PCDATA ::= NMTOKEN 

uri

Defines a public URI that uniquely identifies this version of the tag library. It is recommended that the URI identifying a tag library is actually a URL to the tag library descriptor for this specific version of the tag library.

 <!ELEMENT  uri  (#PCDATA) > 

info

Defines an arbitrary text string describing the tag library.

 <!ELEMENT  info  (#PCDATA) > 

tag

The tag defines an action in this tag library. It has one attribute:

 <!ATTLIST  tag  id ID #IMPLIED > 

The tag may have several subelements defining:

name

the unique action name

tagclass

the tag handler class implementing javax.servlet.jsp. tagext .Tag

teiclass

an optional subclass of javax.servlet.jsp.tagext.TagExtraInfo

bodycontent

the body content type

info

optional tag-specific information

attribute

all attributes of this action

The element syntax is as follows :

 <!ELEMENT  tag  (name, tagclass, teiclass?,      bodycontent?, info?, attribute*) > 

tagclass

Defines the tag handler class implementing the javax.serlvet.jsp.tagext.Tag interface. This element is required.

The syntax is:

 <!ELEMENT  tagclass  (#PCDATA) >  #PCDATA ::= fully qualified Java class name. 

teiclass

Defines the subclass of javax.servlet.jsp.tagext.TagExtraInfo for this tag. This element is optional.

The syntax is:

 <!ELEMENT  teiclass  (#PCDATA) >   #PCDATA ::= fully qualified Java class name 

bodycontent

Provides a hint as to the content of the body of this action. Primarily intended for use by page composition tools.

There are currently three values specified:

tagdependent

The body of the action is interpreted by the tag handler itself, and is most likely in a different "language," e.g., embedded SQL statements. The body of the action may be empty.

JSP

The body of the action contains elements using the JSP syntax. The body of the action may be empty.

empty

The body must be empty

The default value is "JSP."

The syntax is:

 <!ELEMENT  bodycontent  (#PCDATA) >  #PCDATA ::=  tagdependent  JSP  empty. 

attribute

Provides information on an attribute of this action. Attribute defines an id attribute for external linkage.

 <!ATTLIST  attribute  id   ID#IMPLIED> 

The subelements of attribute are of the form:

name

the attribute's name (required)

required

if the attribute is required or optional (optional)

rtexprvalue

if the attributes value may be dynamically calculated at runtime by a scriptlet expression (optional)

The syntax is:

 <!ELEMENT  attribute  (name, required?,     rtexprvalue?) > 

name

Defines the canonical name of a tag or attribute being defined

The syntax is:

 <!ELEMENT  name  (#PCDATA) >  #PCDATA ::= NMTOKEN 

required

Defines if the nesting attribute is required or optional.

The syntax is:

 <!ELEMENT  required  (#PCDATA) >  #PCDATA ::= true  false  yes  no 

If not present then the default is "false," i.e., the attribute is optional.

rtexprvalue

Defines if the nesting attribute can have scriptlet expressions as a value, i.e., the value of the attribute may be dynamically calculated at request time, as opposed to a static value determined at translation time.

The syntax is:

 <!ELEMENT  rtexprvalue  (#PCDATA) >  #PCDATA ::= true  false  yes  no 

If not present then the default is "false," i.e., the attribute has a static value.



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