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 DescriptorThe 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.xmlThe 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. ExampleThe 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 LocationIf 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). ExampleThis 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 LoaderThe 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 ApplicationAs 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 URIsA 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 FormatThis 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:
<!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:
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:
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:
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. |