Oracle9iAS Containers for J2EE JSP Tag Libraries and Utilities Reference Release 2 (9.0.2) Part Number A95883-01 |
|
This chapter documents the Oracle JSP Markup Language (JML) tag library, which provides a set of JSP tags to allow developers to script JSP pages without using Java statements. The JML library provides tags for variable declarations, control flow, conditional branches, iterative loops, parameter settings, and calls to objects.
The chapter is organized as follows:
The library described here, which uses a standard runtime implementation, is also supported through an Oracle-specific compile-time implementation. The compile-time syntax and tags are documented in Appendix A, "JML Compile-Time Syntax and Tags". General considerations in using compile-time tags instead of runtime tags are discussed in the Oracle9iAS Containers for J2EE Support for JavaServer Pages Reference.
Note:
OC4J supplies the JSP Markup Language (JML) 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.
JML tags are intended to simplify coding syntax for JSP developers who are not proficient with Java. There are two main categories of JML tags: 1) logic/flow control; 2) bean binding.
This section covers the following topics:
Note the following requirements for using JML tags:
ojsputil.jar
is installed and in your classpath. This file is provided with the OC4J installation.
jml.tld
. In an Oracle9iAS installation, this file is located in the [Oracle_Home]/j2ee/tlds
directory. The TLD file must be deployed with any JSP application that uses JML tags, and specified in a taglib
directive for any page using JML tags. The taglib
directive 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" %>
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 feature set split into two functional categories, as summarized in Table 3-1.
Tag Categories | Tags | Functionality |
---|---|---|
bean binding tags |
useVariable |
The purpose of these tags is 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". |
This section documents the JML tags that are supported in the current JSP runtime implementation, following the JSP 1.1 specification. They are categorized as follows:
For an elementary sample using some of the tags described here, refer to the OC4J demos.
Notes:
|
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" ] />
id
(required)--Names the variable being declared.
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
(required)--Specifies the type of the variable. Type specifications refer to JmlString
, JmlBoolean
, JmlNumber
, or JmlFPNumber
.
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, then 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
(required)--Names the variable being declared or referenced.
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. Type specifications refer to JmlString
, JmlBoolean
, JmlNumber
, or JmlFPNumber
. This attribute is optional; its default value is "string".
param
(required)--Specifies the name of the request parameter whose value is used in setting the variable. 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
(required)--Names the variable being declared or referenced.
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. Type specifications refer to JmlString
, JmlBoolean
, JmlNumber
, or JmlFPNumber
. This attribute is optional; the default setting is "string".
cookie
(required)--Specifies the name of the cookie whose value is used in setting this variable. 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
(required)--Specifies the name of the bean being removed.
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
(required)--This is the name of 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.
from
(required)--Specifies the start of the range. This is an expression that must evaluate to a Java int
value.
to
(required)--Specifies the end of the range. This is an expression that must evaluate to a Java int
value.
The following example repeatedly prints "Hello World" as 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
(required)--This is the name of 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.
in
(required)--Specifies a JSP expression that evaluates to a Java array, Enumeration
object, or Vector
object.
limit
(required)--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.
type
(required)--Specifies the type of the loop variable. This should match the type of the set elements, as applicable.
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 © 2002 Oracle Corporation. All Rights Reserved. |
|