Release 1.1.2.3
Part Number A90208-01
 Home |
 Book List |
 Contents |
 Index |  Master Index |  Feedback |
| OracleJSP Support for JavaServer Pages Developer's Guide and Reference Release 1.1.2.3 Part Number A90208-01 |
|
This chapter discusses custom tag libraries, covering the basic framework that vendors can use to provide their own libraries and documenting the JML tag library that OracleJSP provides as a sample. This discussion includes the following topics:
Standard JavaServer Pages technology allows vendors to create custom JSP tag libraries.
A tag library defines a collection of custom actions. The tags can be used directly by developers in manually coding a JSP page, or automatically by Java development tools. A tag library must be portable between different JSP container implementations.
For information beyond what is provided here regarding tag libraries and the standard JavaServer Pages tag library framework, refer to the following resources:
javax.servlet.jsp.tagext package, at the following Web site:
http://java.sun.com/j2ee/j2sdkee/techdocs/api/javax/servlet/jsp/tagext/package-summary.html
A custom tag library is imported into a JSP page using a taglib directive of the following general form:
<%@ taglib uri="URI" prefix="prefix" %>
Note the following:
taglib directive specifies where to find the tag library description file, as described in "The taglib Directive". It is possible to use URI shortcuts, as described in "Use of web.xml for Tag Libraries".
taglib directive is a string of your choosing that you use in your JSP page with any tag from the library.
Assume the taglib directive specifies a prefix oracust:
<%@ taglib uri="URI" prefix="oracust" %>
Further assume that there is a tag mytag in the library. You might use mytag as follows:
<oracust:mytag attr1="...", attr2="..." />
Using the oracust prefix informs the JSP translator that mytag is defined in the tag library description file that can be found at the URI specified in the above taglib directive.
mytag does), and the names of those attributes.
As seen above, a tag without a body is used as in the following example:
<oracust:mytag attr1="...", attr2="..." />
By contrast, a tag with a body is used as in the following example:
<oracust:mytag attr1="...", attr2="..." > ...body... </oracust:mytag>
Details regarding the scripting variables that a custom tag uses are defined in a tag-extra-info class. This is described in "Scripting Variables and Tag-Extra-Info Classes".
A tag can create scripting variables with syntax such as in the following example, which creates the object myobj:
<oracust:mytag id="myobj" attr1="...", attr2="..." />
The sections that follow provide more information about these 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 one of two standard Java interfaces, depending on whether the tag processes a body of statements (between a start tag and an end tag).
Each tag has its own handler class. By convention, the name of the tag handler class for a tag abc, for example, is AbcTag.
The tag library description (TLD) file of a tag library specifies the name of the tag handler class for each tag in the library. (See "Tag Library Description Files".)
A tag handler instance is a server-side object used at request time. It has properties that are set by the JSP container, including the page context object for the JSP page that uses the custom tag, and a parent tag handler object if the use of this custom tag is nested within an outer custom tag.
See "Sample Tag Handler Class: ExampleLoopTag.java" for sample code of a tag handler class.
Custom tags, like standard JSP tags, may or may not have a body. And in the case of a custom tag, even when there is a body, it may not need special handling by the tag handler.
There are three possible situations:
In this case, there is just a single tag, as opposed to a start tag and end tag. Following is a general example:
<oracust:abcdef attr1="...", attr2="..." />
In this case, there is a start tag and end tag with a body of statements in between, but the tag handler does not have to process the body--body statements are passed through for normal JSP processing only. Following is a general example:
<foo:if cond="<%= ... %>" > ...body executed if cond is true, but not processed by tag handler... </foo:if>
In this case also, there is a start tag and end tag with a body of statements in between; however, the tag handler must process the body.
<oracust:ghijkl attr1="...", attr2="..." > ...body processed by tag handler... </oracust:ghijkl>
The tag handling interfaces that are described in the following sections specify a doStartTag() method (further described below) that you must implement to return an appropriate int constant, depending on the situation. The possible return values are as follows:
SKIP_BODY if there is no body or if evaluation and execution of the body should be skipped
EVAL_BODY_INCLUDE if there is a body that does not require special handling by the tag handler
EVAL_BODY_TAG if there is a body that requires special handling by the tag handler
For a custom tag that does not have a body, or has a body that does not need special handling by the tag handler, the tag handler class implements the following standard interface:
The following standard support class implements the Tag interface and can be used as a base class:
The Tag interface specifies a doStartTag() method and a doEndTag() method. The tag developer provides code for these methods in the tag handler class, as appropriate, to be executed as the start tag and end tag, respectively, are encountered. The JSP page implementation class generated by the OracleJSP translator includes appropriate calls to these methods.
Action processing--whatever you want the action tag to accomplish--is implemented in the doStartTag() method. The doEndTag() method would implement any appropriate post-processing. In the case of a tag without a body, essentially nothing happens between the execution of these two methods.
The doStartTag() method returns an integer value. For a tag handler class implementing the Tag interface (either directly or indirectly), this value must be either SKIP_BODY or EVAL_BODY_INCLUDE (described in "Integer Constants for Body Processing" above). EVAL_BODY_TAG is illegal for a tag handler class implementing the Tag interface.
For a custom tag with a body that requires special handling by the tag handler, the tag handler class implements the following standard interface:
The following standard support class implements the BodyTag interface and can be used as a base class:
The BodyTag interface specifies a doInitBody() method and a doAfterBody() method in addition to the doStartTag() and doEndTag() methods specified in the Tag interface.
Just as with tag handlers implementing the Tag interface (described in the preceding section, "Handlers for Tags That Do Not Process a Body"), the tag developer implements the doStartTag() method for action processing by the tag, and the doEndTag() method for any post-processing.
The doStartTag() method returns an integer value. For a tag handler class implementing the BodyTag interface (directly or indirectly), this value must be either SKIP_BODY or EVAL_BODY_TAG (described in "Integer Constants for Body Processing"). EVAL_BODY_INCLUDE is illegal for a tag handler class implementing the BodyTag interface.
In addition to implementing the doStartTag() and doEndTag() methods, the tag developer, as appropriate, provides code for the doInitBody() method, to be invoked before the body is evaluated, and the doAfterBody() method, to be invoked after each evaluation of the body. (The body could be evaluated multiple times, such as at the end of each iteration of a loop.) The JSP page implementation class generated by the OracleJSP translator includes appropriate calls to all of these methods.
After the doStartTag() method is executed, the doInitBody() and doAfterBody() methods are executed if the doStartTag() method returned EVAL_BODY_TAG.
The doEndTag() method is executed after any body processing, when the end tag is encountered.
For custom tags that must process a body, the javax.servlet.jsp.tagext.BodyContent class is available for use. This is a subclass of javax.servlet.jsp.JspWriter that can be used to process body evaluations so that they can re-extracted later. The BodyTag interface includes a setBodyContent() method that can be used by the JSP container to give a BodyContent handle to a tag handler instance.
A custom tag action can create one or more server-side objects, known as scripting variables, that are available for use by the tag itself or by other scripting elements, such as scriptlets and other tags.
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 tag-extra-info instances during translation. (The tag library description file, specified in the taglib directive that imports the library into a JSP page, specifies the tag-extra-info class to use, if applicable, for any given tag.)
A tag-extra-info class has a getVariableInfo() method to retrieve names and types of the scripting variables that will be assigned during HTTP requests. The JSP translator calls this method during translation, passing it an instance of the standard javax.servlet.jsp.tagext.TagData class. The TagData instance specifies attribute values set in the JSP statement that uses the custom tag.
This section covers the following topics:
Objects that are defined explicitly in a custom tag can be referenced in other actions through the page context object, using the object ID as a handle. Consider the following example:
<oracust:foo id="myobj" attr1="..." attr2="..." />
This statement results in the object myobj being available to any scripting elements between the tag and the end of the page. The id attribute is a translation-time attribute. The tag developer provides a tag-extra-info class that will be used by the JSP container. Among other things, the tag-extra-info class specifies what class to instantiate for the myobj object.
The JSP container enters myobj into the page context object, where it can later be obtained by other tags or scripting elements using syntax such as the following:
<oracust:bar ref="myobj" />
The myobj object is passed through the tag handler instances for foo and bar. All that is required is knowledge of the name of the object (myobj).
Specify the scope of a scripting variable in the tag-extra-info class of the tag that creates the variable. It can be one of the following int constants:
NESTED--if the scripting variable is available between the start tag and end tag of the action that defines it
AT_BEGIN--if the scripting variable is available from the start tag until the end of the page
AT_END--if the scripting variable is available from the end tag until the end of the page
You must create a tag-extra-info class for any custom tag that creates scripting variables. The class describes the scripting variables and must be a subclass of the standard javax.servlet.jsp.tagext.TagExtraInfo abstract class.
The key method of the TagExtraInfo class is getVariableInfo(), which is called by the JSP translator and returns an array of instances of the standard javax.servlet.jsp.tagext.VariableInfo class (one array instance for each scripting variable the tag creates).
The tag-extra-info class constructs each VariableInfo instance with the following information regarding the scripting variable:
See "Sample Tag-Extra-Info Class: ExampleLoopTagTEI.java" for sample code of a tag-extra-info class.
Where nested custom tags are used, the tag handler instance of the nested tag has access to the tag handler instance of the outer tag, which may be useful in any processing and state management performed by the nested tag.
This functionality is supported through the static findAncestorWithClass() method of the javax.servlet.jsp.tagext.TagSupport class. Even though the outer tag handler instance is not named in the page context object, it is accessible because it is the closest enclosing instance of a given tag handler class.
Consider the following JSP code example:
<foo:bar1 attr="abc" > <foo:bar2 /> </foo:bar1>
Within the code of the bar2 tag handler class (class Bar2Tag, by convention), you can have a statement such as the following:
Tag bar1tag = TagSupport.findAncestorWithClass(this, Bar1Tag.class);
The findAncestorWithClass() method takes the following as input:
this object that is the class handler instance from which findAncestorWithClass() was called (a Bar2Tag instance in the example)
bar1 tag handler class (presumed to be Bar1Tag in the example), as a java.lang.Class instance
The findAncestorWithClass() method returns an instance of the appropriate tag handler class, in this case Bar1Tag, as a javax.servlet.jsp.tagext.Tag instance.
It is useful for a Bar2Tag instance to have access to the outer Bar1Tag instance in case the Bar2Tag needs the value of a bar1 tag attribute or needs to call a method on the Bar1Tag instance.
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 name of a TLD file 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.
A tag entry in the TLD file includes the following:
Here is a sample TLD file entry for the tag myaction:
<tag> <name>myaction</name> <tagclass>examples.MyactionTag</tagclass> <teiclass>examples.MyactionTagExtraInfo</teiclass> <bodycontent>JSP</bodycontent> <info> Perform a server-side action (one mandatory attr; one optional) </info> <attribute> <name>attr1</name> <required>true</required> </attribute> <attribute> <name>attr2</name> <required>false</required> </attribute> </tag>
According to this entry, the tag handler class is MyactionTag and the tag-extra-info class is MyactionTagExtraInfo. The attribute attr1 is required; the attribute attr2 is optional.
The bodycontent parameter indicates how the tag body (if any) should be processed. There are three valid values:
empty indicates that the tag uses no body.
JSP indicates that the tag body should be processed as JSP source and translated.
tagdependent indicates that the tag body should not be translated. Any text in the body is treated as static text.
The taglib directive in a JSP page informs the JSP container where to find the TLD file. (See "The taglib Directive".)
For more information about tag library description files, see the Sun Microsystems JavaServer Pages Specification, Version 1.1.
The Sun Microsystems Java Servlet Specification, Version 2.2 describes a standard deployment descriptor for servlets--the web.xml file. JSP pages 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:
The taglib-location subelement indicates the application-relative location (by starting with "/") of the tag library description file.
The taglib-uri subelement indicates a "shortcut" URI to use in taglib directives in your JSP pages, with this URI being mapped to the TLD file location specified in the accompanying taglib-location subelement. (The term URI, universal resource indicator, is somewhat equivalent to the term URL, universal resource locator, but is more generic.)
Following is a sample web.xml entry for a tag library description file:
<taglib> <taglib-uri>/oracustomtags</taglib-uri> <taglib-location>/WEB-INF/oracustomtags/tlds/MyTLD.tld</taglib-location> </taglib>
This makes /oracustomtags equivalent to /WEB-INF/oracustomtags/tlds/MyTLD.tld in taglib directives in your JSP pages. See "Using a Shortcut URI for the TLD File" below for an example.
See the Sun Microsystems Java Servlet Specification, Version 2.2 and the Sun Microsystems JavaServer Pages Specification, Version 1.1 for more information about the web.xml deployment descriptor and its use for tag library description files.
Import a custom library into a JSP page using a taglib directive, of the following form:
<%@ taglib uri="URI" prefix="prefix" %>
For the URI, you have the following options:
web.xml file (see "Use of web.xml for Tag Libraries" above).
Assume the following web.xml entry for a tag library defined in the tag library description file MyTLD.tld:
<taglib> <taglib-uri>/oracustomtags</taglib-uri> <taglib-location>/WEB-INF/oracustomtags/tlds/MyTLD.tld</taglib-location> </taglib>
Given this example, the following directive in your JSP page results in the JSP container finding the /oracustomtags URI in web.xml and, therefore, finding the accompanying name and location of the tag library description file (MyTLD.tld):
<%@ taglib uri="/oracustomtags" prefix="oracust" %>
This statement allows you to use any of the tags of this custom tag library in a JSP page.
If you do not want your JSP application to depend on a web.xml file for its use of a tag library, taglib directives can fully specify the name and location of the tag library description file, as follows:
<%@ taglib uri="/WEB-INF/oracustomtags/tlds/MyTLD.tld" prefix="oracust" %>
The location is specified as an application-relative location (by starting with "/", as in this example). See "Requesting a JSP Page" for related discussion.
Alternatively, you can specify a .jar file instead of a .tld file in the taglib directive, where the .jar file contains a tag library description file. The tag library description file must be located and named as follows when you create the JAR file:
META-INF/taglib.tld
Then the taglib directive might be as follows, for example:
<%@ taglib uri="/WEB-INF/oracustomtags/tlds/MyTLD.jar" prefix="oracust" %>
This section provides an end-to-end example of the definition and use of a custom tag, loop, that is used to iterate through the tag body a specified number of times.
Included in the example are the following:
Following is a sample JSP page that uses the loop tag, specifying that the outer loop be executed five times and the inner loop three times:
examplestag.jsp <%@ taglib prefix="foo" uri="/WEB-INF/exampletag.tld" %> <% int num=5; %>
<br> <pre> <foo:loop index="i" count="<%=num%>"> body1here: i expr: <%=i%> i property: <jsp:getProperty name="i" property="value" /> <foo:loop index="j" count="3"> body2here: j expr: <%=j%> i property: <jsp:getProperty name="i" property="value" /> j property: <jsp:getProperty name="j" property="value" /> </foo:loop> </foo:loop> </pre>
This section provides source code for the tag handler class, ExampleLoopTag. Note the following:
doStartTag() method returns the integer constant EVAL_BODY_TAG, so that the tag body (essentially, the loop) is processed.
doAfterBody() method increments the counter. It returns EVAL_BODY_TAG if there are more iterations left and SKIP_BODY after the last iteration.
Here is the code:
package examples; import javax.servlet.jsp.*; import javax.servlet.jsp.tagext.*; import java.util.Hashtable; import java.io.Writer; import java.io.IOException; import oracle.jsp.jml.JmlNumber; public class ExampleLoopTag extends BodyTagSupport { String index; int count; int i=0; JmlNumber ib=new JmlNumber(); public void setIndex(String index) { this.index=index; } public void setCount(String count) { this.count=Integer.parseInt(count); } public int doStartTag() throws JspException { return EVAL_BODY_TAG; } public void doInitBody() throws JspException { pageContext.setAttribute(index, ib); i++; ib.setValue(i); } public int doAfterBody() throws JspException { try { if (i >= count) { bodyContent.writeOut(bodyContent.getEnclosingWriter()); return SKIP_BODY; } else pageContext.setAttribute(index, ib); i++; ib.setValue(i); return EVAL_BODY_TAG; } catch (IOException ex) { throw new JspTagException(ex.toString()); } } }
This section provides the source code for the tag-extra-info class that describes the scripting variable used by the loop tag.
A VariableInfo instance is constructed that specifies the following for the variable:
index attribute.
oracle.jsp.jml.JmlNumber (this must be specified as a fully qualified class name).
NESTED.
In addition, the tag-extra-info class has an isValid() method that determines whether the count attribute is valid--it must be an integer.
package examples; import javax.servlet.jsp.tagext.*; public class ExampleLoopTagTEI extends TagExtraInfo { public VariableInfo[] getVariableInfo(TagData data) { return new VariableInfo[] { new VariableInfo(data.getAttributeString("index"), "oracle.jsp.jml.JmlNumber", true, VariableInfo.NESTED) }; } public boolean isValid(TagData data) { String countStr=data.getAttributeString("count"); if (countStr!=null) // for request time case { try { int count=Integer.parseInt(countStr); } catch (NumberFormatException e) { return false; } } return true; } }
This section presents the tag library description (TLD) file for the tag library. In this example, the library consists of only the one tag, loop.
This TLD file specifies the following for the loop tag:
examples.ExampleLoopTag
examples.ExampleLoopTagTEI
bodycontent specification of JSP
This means the JSP translator should process and translate the body code.
index and count, both mandatory
The count attribute can be a request-time JSP expression.
Here is the TLD file:
<?xml version="1.0" encoding="ISO-8859-1" ?> <!DOCTYPE taglib PUBLIC "-//Sun Microsystems, Inc.//DTD JSP Tag Library 1.1//EN" "http://java.sun.com/j2ee/dtds/web-jsptaglibrary_1_1.dtd"> <!-- a tab library descriptor --> <taglib> <!-- after this the default space is "http://java.sun.com/j2ee/dtds/jsptaglibrary_1_2.dtd" --> <tlibversion>1.0</tlibversion> <jspversion>1.1</jspversion> <shortname>simple</shortname> <!-- there should be no <urn></urn> here --> <info> A simple tab library for the examples </info> <!-- example tag --> <!-- for loop --> <tag> <name>loop</name> <tagclass>examples.ExampleLoopTag</tagclass> <teiclass>examples.ExampleLoopTagTEI</teiclass> <bodycontent>JSP</bodycontent> <info>for loop</info> <attribute> <name>index</name> <required>true</required> </attribute> <attribute> <name>count</name> <required>true</required> <rtexprvalue>true</rtexprvalue> </attribute> </tag> </taglib>
OracleJSP supplies the JSP Markup Language (JML) sample tag library, which is portable to any standard JSP environment. JML tags, as with those of any standard tag library, are completely compatible with regular JSP script and can be used in any JSP page.
Many of the JML tags are intended to simplify coding syntax for JSP developers who are not proficient with Java. There are also tags for XML transformations (as described in "JML Tags for XSL Stylesheets"), bean binding, and general utility.
The following topics are covered here:
Note the following requirements for using JML tags:
ojsputil.jar and include it in your classpath. This file is provided with the OracleJSP installation.
jml.tld, is deployed with the application and is in the location specified in the taglib directives of your JSP pages. See "JML Tag Library Description File and taglib Directive".
Notes:
JavaServer Pages technology is intended for two separate developer communities:
The JML tag library is designed to allow most Web developers, with little or no knowledge of Java, to assemble JSP applications with a full complement of program flow-control features.
This model presumes that the business logic is contained in JavaBeans that are developed separately by a Java developer.
The JML tag library covers a wide feature set. The major functional categories are summarized in Table 7-1.
| Tag Categories | Tags | Functionality |
|---|---|---|
|
bean binding tags |
useVariable |
These tags are to declare or undeclare a JavaBean at a specified JSP scope. See "Bean Binding Tag Descriptions". |
|
logic/flow control tags |
if |
These tags offer simplified syntax to define code flow, such as for iterative loops or conditional branches. See "Logic and Flow Control Tag Descriptions". |
|
XML transformation tags |
transform |
These synonymous tags simplify the process of applying an XSL stylesheet to all or part of JSP page output. See "JML Tags for XSL Stylesheets". (The tags are identical in effect. You need only one or the other.) |
As with any tag library following the JSP 1.1 specification, the tags of the JML library are specified in an XML-style tag library description (TLD) file.
This TLD file is provided with the OracleJSP sample applications. It must be deployed with any JSP application that uses JML tags, and specified in a taglib directive for any page using JML tags.
A JSP page using JML tags must specify the TLD file in a taglib directive that supplies a standard universal resource indicator (URI) to locate the file. The URI syntax is typically application-relative, such as in the following example:
<%@ taglib uri="/WEB-INF/jml.tld" prefix="jml" %>
Alternatively, instead of using the full path to the TLD file, as in this example, you can specify a URI shortcut in the web.xml file then use the shortcut in your taglib directives. See "Use of web.xml for Tag Libraries".
For general information about tag library description files, see "Tag Library Description Files".
This section lists the entire TLD file for the JML tag library, as supported in OracleJSP release 1.1.2.x.
<?xml version="1.0" encoding="ISO-8859-1" ?> <!DOCTYPE taglib PUBLIC "-//Sun Microsystems, Inc.//DTD JSP Tag Library 1.1//EN" "http://java.sun.com/j2ee/dtds/web-jsptaglibrary_1_1.dtd"> <!-- a tab library descriptor --> <taglib> <!-- after this the default space is "http://java.sun.com/j2ee/dtds/web-jsptaglibrary_1_1.dtd" --> <tlibversion>1.0</tlibversion> <jspversion>1.1</jspversion> <shortname>jml</shortname> <info> Oracle's jml tag library. Not all of the jml tag's available in the Oracle JSP environment are provided in this library. No jsp: tags are duplicated, some tags are unavailable, and some tags have stricter syntax. No bean expressions are supported. The differences are: *-jml:call - not available * jml:choose - works as documented * jml:flush - works as documented * jml:for - works as documented * jml:foreach - the type attribute is required, otherwise, as documented *!jml:forward - use jsp:forward *!jml:getProperty - use jsp:getProperty * jml:if - works as documented *!jml:include - use jsp:include *-jml:lock - not available *!jml:plugin - use jsp:plugin * jml:print - the expression to print must be supplied as an attribute. i.e. the tag cannot have a body * jml:remove - works as documented * jml:return - works as documented *-jml:set - not available *!jml:setProperty - use jsp:setProperty * jml:styleSheet - works as documented * jml:transform - works as documented *!jml:useBean - use jsp:useBean * jml:useCookie - works as documented * jml:useForm - works as documented * jml:useVariable - works as documented </info> <!-- The choose tag --> <tag> <name>choose</name> <tagclass>oracle.jsp.jml.tagext.JmlChoose</tagclass> <bodycontent>JSP</bodycontent> <info> The outer tag of a multiple choice logic block, choose when condition1 when condition2 otherwise end choose </info> </tag> <!-- The flush tag --> <tag> <name>flush</name> <tagclass>oracle.jsp.jml.tagext.JmlFlush</tagclass> <bodycontent>empty</bodycontent> <info> Flush the current JspWriter </info> </tag> <!-- The for tag --> <tag> <name>for</name> <tagclass>oracle.jsp.jml.tagext.JmlFor</tagclass> <teiclass>oracle.jsp.jml.tagext.JmlForTEI</teiclass> <bodycontent>JSP</bodycontent> <info> A simple for loop </info> <attribute> <name>id</name> <required>true</required> </attribute> <attribute> <name>from</name> <required>true</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>to</name> <required>true</required> <rtexprvalue>true</rtexprvalue> </attribute> </tag> <!-- The foreach tag --> <tag> <name>foreach</name> <tagclass>oracle.jsp.jml.tagext.JmlForeach</tagclass> <teiclass>oracle.jsp.jml.tagext.JmlForeachTEI</teiclass> <bodycontent>JSP</bodycontent> <info> A foreach loop for iterating arrays, enumerations, and vector's. </info> <attribute> <name>id</name> <required>true</required> </attribute> <attribute> <name>in</name> <required>true</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>type</name> <required>true</required> </attribute> <attribute> <name>limit</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> </tag> <!-- The if tag --> <tag> <name>if</name> <tagclass>oracle.jsp.jml.tagext.JmlIf</tagclass> <bodycontent>JSP</bodycontent> <info> A classic if </info> <attribute> <name>condition</name> <required>true</required> <rtexprvalue>true</rtexprvalue> </attribute> </tag> <!-- The otherwise tag --> <tag> <name>otherwise</name> <tagclass>oracle.jsp.jml.tagext.JmlOtherwise</tagclass> <bodycontent>JSP</bodycontent> <info> (optional) final part of a choose block </info> </tag> <!-- The print tag --> <tag> <name>print</name> <tagclass>oracle.jsp.jml.tagext.JmlPrint</tagclass> <bodycontent>empty</bodycontent> <info> print the expression specified in the eval attribute </info> <attribute> <name>eval</name> <required>true</required> <rtexprvalue>true</rtexprvalue> </attribute> </tag> <!-- The remove tag --> <tag> <name>remove</name> <tagclass>oracle.jsp.jml.tagext.JmlRemove</tagclass> <bodycontent>empty</bodycontent> <info> remove the specified object from the pageContext </info> <attribute> <name>id</name> <required>true</required> </attribute> <attribute> <name>scope</name> <required>false</required> </attribute> </tag> <!-- The return tag --> <tag> <name>return</name> <tagclass>oracle.jsp.jml.tagext.JmlReturn</tagclass> <bodycontent>empty</bodycontent> <info> Skip the rest of the page </info> </tag> <!-- The styleSheet tag --> <tag> <name>styleSheet</name> <tagclass>oracle.jsp.jml.tagext.JmlStyleSheet</tagclass> <bodycontent>JSP</bodycontent> <info> Transform the body of the tag using a stylesheet </info> <attribute> <name>href</name> <required>true</required> <rtexprvalue>true</rtexprvalue> </attribute> </tag> <!-- The transform tag --> <tag> <name>transform</name> <tagclass>oracle.jsp.jml.tagext.JmlStyleSheet</tagclass> <bodycontent>JSP</bodycontent> <info> Transform the body of the tag using a stylesheet </info> <attribute> <name>href</name> <required>true</required> <rtexprvalue>true</rtexprvalue> </attribute> </tag> <!-- The useCookie tag --> <tag> <name>useCookie</name> <tagclass>oracle.jsp.jml.tagext.JmlUseCookie</tagclass> <teiclass>oracle.jsp.jml.tagext.JmlUseTEI</teiclass> <bodycontent>empty</bodycontent> <info> create a jml variable and initialize it to a cookie value </info> <attribute> <name>id</name> <required>true</required> </attribute> <attribute> <name>scope</name> <required>false</required> </attribute> <attribute> <name>type</name> <required>true</required> </attribute> <attribute> <name>cookie</name> <required>true</required> </attribute> </tag> <!-- The useForm tag --> <tag> <name>useForm</name> <tagclass>oracle.jsp.jml.tagext.JmlUseForm</tagclass> <teiclass>oracle.jsp.jml.tagext.JmlUseTEI</teiclass> <bodycontent>empty</bodycontent> <info> create a jml variable and initialize it to a parameter value </info> <attribute> <name>id</name> <required>true</required> </attribute> <attribute> <name>scope</name> <required>false</required> </attribute> <attribute> <name>type</name> <required>true</required> </attribute> <attribute> <name>param</name> <required>true</required> </attribute> </tag> <!-- The useVariable tag --> <tag> <name>useVariable</name> <tagclass>oracle.jsp.jml.tagext.JmlUseVariable</tagclass> <teiclass>oracle.jsp.jml.tagext.JmlUseTEI</teiclass> <bodycontent>empty</bodycontent> <info> create a jml variable and initialize it to a parameter value </info> <attribute> <name>id</name> <required>true</required> </attribute> <attribute> <name>scope</name> <required>false</required> </attribute> <attribute> <name>type</name> <required>true</required> </attribute> <attribute> <name>value</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> </tag> <!-- The when tag --> <tag> <name>when</name> <tagclass>oracle.jsp.jml.tagext.JmlWhen</tagclass> <bodycontent>JSP</bodycontent> <info> one part of a choose block, see choose </info> <attribute> <name>condition</name> <required>true</required> <rtexprvalue>true</rtexprvalue> </attribute> </tag> </taglib>
This section documents the JML tags that are supported in the OracleJSP 1.1.2.x runtime implementation, following the JSP 1.1 specification. They are categorized as follows:
For an elementary sample using some of the tags described here, see "JML Tag Sample--hellouser_jml.jsp".
Tags for XML transformations are documented separately, in "JML Tags for XSL Stylesheets".
For the syntax documentation in the tag descriptions, note the following:
[...]
taglib directive.
This section documents the following JML tags, which are used for bean-binding operations:
This tag offers a convenient alternative to the jsp:useBean tag for declaring simple variables.
<jml:useVariable id = "beanInstanceName" [scope = "page | request | session | application"] type = "string | boolean | number | fpnumber" [value = "stringLiteral | <%= jspExpression %>"] />
id--Names the variable being declared. This attribute is required.
scope--Defines the duration or scope of the variable (as with a jsp:useBean tag). This attribute is optional; the default scope is page.
type--Specifies the type of the variable. The type specifications refer to JmlString, JmlBoolean, JmlNumber, or JmlFPNumber. This attribute is required.
value--Allows the variable to be set directly in the declaration, as either a string literal or a JSP expression enclosed in <%=... %> syntax. This attribute is optional. If it is not specified, the value remains the same as when it was last set (if it already exists) or is initialized with a default value. If it is specified, then the value is always set, regardless of whether this declaration instantiates the object or merely acquires it from the named scope.
Consider the following example:
<jml:useVariable id = "isValidUser" type = "boolean" value = "<%= dbConn.isValid() %>" scope = "session" />
This is equivalent to the following:
<jsp:useBean id = "isValidUser" class = "oracle.jsp.jml.JmlBoolean" scope = "session" /> <jsp:setProperty name="isValidUser" property="value" value = "<%= dbConn.isValid() %>" />
This tag provides a convenient syntax for declaring variables and setting them to values passed in from the request.
<jml:useForm id = "beanInstanceName" [scope = "page | request | session | application"] [type = "string | boolean | number | fpnumber"] param = "requestParameterName" />
id--Names the variable being declared or referenced. This attribute is required.
scope--Defines the duration or scope of the variable (as with a jsp:useBean tag). This attribute is optional; the default scope is page.
type--Specifies the type of the variable. The type specifications refer to JmlString, JmlBoolean, JmlNumber, or JmlFPNumber. This attribute is required.
param--Specifies the name of the request parameter whose value is used in setting the variable. This attribute is required. If the request parameter exists, then the variable value is always updated, regardless of whether this declaration brings the variable into existence. If the request parameter does not exist, then the variable value remains unchanged.
The following example sets a session variable named user of the type string to the value of the request parameter named user.
<jml:useForm id = "user" type = "string" param = "user" scope = "session" />
This is equivalent to the following:
<jsp:useBean id = "user" class = "oracle.jsp.jml.JmlString" scope = "session" /> <jsp:setProperty name="user" property="value" param = "user" />
This tag offers a convenient syntax for declaring variables and setting them to values contained in cookies.
<jml:useCookie id = "beanInstanceName" [scope = "page | request | session | application"] [type = "string | boolean | number | fpnumber"] cookie = "cookieName" />
id--Names the variable being declared or referenced. This attribute is required.
scope--Defines the duration or scope of the variable. This attribute is optional; the default scope is page.
type--Identifies the type of the variable (the type specifications refer to JmlString, JmlBoolean, JmlNumber, or JmlFPNumber). This attribute is optional; the default setting is string.
cookie--Specifies the name of the cookie whose value is used in setting this variable. This attribute is required. If the cookie exists, then the variable value is always updated, regardless of whether this declaration brings the variable into existence. If the cookie does not exist, then the variable value remains unchanged.
The following example sets a request variable named user of the type string to the value of the cookie named user.
<jml:useCookie id = "user" type = "string" cookie = "user" scope = "request" />
This is equivalent to the following:
<jsp:useBean id = "user" class = "oracle.jsp.jml.JmlString" scope = "request" /> <% Cookies [] cookies = request.getCookies(); for (int i = 0; i < cookies.length; i++) { if (cookies[i].getName().equals("user")) { user.setValue(cookies[i].getValue()); break; } } %>
This tag removes an object from its scope.
<jml:remove id = "beanInstanceName" [scope = "page | request | session | application" ] />
id--Specifies the name of the bean being removed. This attribute is required.
scope--This attribute is optional. If not specified, then scopes are searched in the following order: 1) page, 2) request, 3) session, 4) application. The first object whose name matches id is removed.
The following example removes the session user object:
<jml:remove id = "user" scope = "session" />
This is equivalent to the following:
<% session.removeValue("user"); %>
This section documents the following JML tags, which are used for logic and flow control:
These tags, which are intended for developers without extensive Java experience, can be used in place of Java logic and flow control syntax, such as iterative loops and conditional branches.
This tag evaluates a single conditional statement. If the condition is true, then the body of the if tag is executed.
<jml:if condition = "<%= jspExpression %>" > ...body of if tag (executed if the condition is true)... </jml:if>
The following e-commerce example displays information from a user's shopping cart. The code checks to see if the variable holding the current T-shirt order is empty. If not, then the size that the user has ordered is displayed. Assume currTS is of type JmlString.
<jml:if condition = "<%= !currTS.isEmpty() %>" > <S>(size: <%= currTS.getValue().toUpperCase() %>)</S>  </jml:if>
The choose tag, with associated when and otherwise tags, provides a multiple conditional statement.
The body of the choose tag contains one or more when tags, where each when tag represents a condition. For the first when condition that is true, the body of that when tag is executed. (A maximum of one when body is executed.)
If none of the when conditions are true, and if the optional otherwise tag is specified, then the body of the otherwise tag is executed.
<jml:choose> <jml:when condition = "<%= jspExpression %>" > ...body of 1st when tag (executed if the condition is true)... </jml:when> ... [...optional additional when tags...] [ <jml:otherwise> ...body of otherwise tag (executed if all when conditions false)... </jml:otherwise> ] </jml:choose>
The when tag uses the following attribute (the choose and otherwise tags have no attributes):
The following e-commerce example displays information from a user's shopping cart. This code checks to see if anything has been ordered. If so, the current order is displayed; otherwise, the user is asked to shop again. (This example omits the code to display the current order.) Presume orderedItem is of the type JmlBoolean.
<jml:choose> <jml:when condition = "<%= orderedItem.getValue() %>" > You have changed your order: -- output the current order -- </jml:when> <jml:otherwise> Are you sure we can't interest you in something, cheapskate? </jml:otherwise> </jml:choose>
This tag provides the ability to iterate through a loop, as with a Java for loop.
The id attribute is a local loop variable of the type java.lang.Integer that contains the value of the current range element. The range starts at the value expressed in the from attributed and is incremented by one after each execution of the body of the loop, until it exceeds the value expressed in the to attribute.
Once the range has been traversed, control goes to the first statement following the for end tag.
<jml:for id = "loopVariable" from = "<%= jspExpression %>" to = "<%= jspExpression %>" > ...body of for tag (executed once at each value of range, inclusive)... </jml:for>
id--Names the loop variable, which holds the current value in the range. This is a java.lang.Integer value and can be used only within the body of the tag. This attribute is required.
from--Specifies the start of the range. This is an expression that must evaluate to a Java int value. This is a required attribute.
to--Specifies the end of the range. This is an expression that must evaluate to a Java int value. This is a required attribute.
The following example repeatedly prints "Hello World" in progressively smaller headings (H1, H2, H3, H4, H5).
<jml:for id="i" from="<%= 1 %>" to="<%= 5 %>" > <H<%=i%>> Hello World! </H<<%=i%>> </jml:for>
This tag provides the ability to iterate over a homogeneous set of values.
The body of the tag is executed once per element in the set. (If the set is empty, then the body is not executed.)
The id attribute is a local loop variable containing the value of the current set element. Its type is specified in the type attribute. (The specified type should match the type of the set elements, as applicable.)
This tag currently supports iterations over the following types of data structures:
<jml:foreach id = "loopVariable" in = "<%= jspExpression %>" limit = "<%= jspExpression %>" type = "package.class" > ...body of foreach tag (executes once for each element in data structure)... </jml:foreach>
id--Names the loop variable, which holds the value of the current element at each step of the iteration. It can be used only within the body of the tag. Its type is the same as specified in the type attribute. The id attribute is required.
in--Specifies a JSP expression that evaluates to a Java array, Enumeration object, or Vector object. This is a required attribute.
limit--Specifies a JSP expression that evaluates to a Java int value defining the maximum number of iterations, regardless of the number of elements in the set. This is a required attribute.
type--Specifies the type of the loop variable. This should match the type of the set elements, as applicable. This is a required attribute.
The following example iterates over the request parameters.
<jml:foreach id="name" in="<%= request.getParameterNames() %>" type="java.lang.String" > Parameter: <%= name %> Value: <%= request.getParameter(name) %> <br> </jml:foreach>
Or, if you want to handle parameters with multiple values:
<jml:foreach id="name" in="<%= request.getParameterNames() %>" type="java.lang.String" > Parameter: <%= name %> Value: <jml:foreach id="val" in="<%=request.getParameterValues(name)%>" type="java.lang.String" > <%= val %> : </jml:foreach> <br> </jml:foreach>
When this tag is reached, execution returns from the page without further processing.
<jml:return />
None.
The following example returns without processing the page if the timer has expired.
<jml:if condition="<%= timer.isExpired() %>" > You did not complete in time! <jml:return /> </jml:if>
This tag writes the current contents of the page buffer back to the client. This applies only if the page is buffered; otherwise, there is no effect.
<jml:flush />
None.
The following example flushes the current page contents before performing an expensive operation.
<jml:flush /> <% myBean.expensiveOperation(out); %>
|
 Copyright © 1996-2001, Oracle Corporation. All Rights Reserved. |
|