JSP Tag Libraries and the Oracle JML Tags

JSP Markup Language (JML) Tag Descriptions

This section documents the JML tags that are supported in the OracleJSP 1.1.0.0.0 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".

Syntax Symbology and Notes

For the syntax documentation in the tag descriptions, note the following:

Italics indicate that you must specify a value or string.
Optional attributes are enclosed in square brackets: [...]
Default values of optional attributes are indicated in bold.
Choices in how to specify an attribute are separated by vertical bars: |
The prefix "jml:" is used. This is by convention but is not required. You can specify any desired prefix in your taglib directive.

Bean Binding Tag Descriptions

This section documents the following JML tags, which are used for bean-binding operations:

JML useVariable Tag

This tag offers a convenient alternative to the jsp:useBean tag for declaring simple variables.

Syntax

<jml:useVariable id = "beanInstanceName" 
                [scope = "page | request | session | application"]
                 type = "string | boolean | number | fpnumber" 
                [value = "stringLiteral | <%= jspExpression %>"] />

Attributes

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.

Example

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() %>" />

JML useForm Tag

This tag provides a convenient syntax for declaring variables and setting them to values passed in from the request.

Syntax

<jml:useForm id = "beanInstanceName" 
            [scope = "page | request | session | application"]
            [type = "string | boolean | number | fpnumber"]
             param = "requestParameterName" />

Attributes

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 optional; the default setting is string.
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.

Example

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" />

JML useCookie Tag

This tag offers a convenient syntax for declaring variables and setting them to values contained in cookies.

Syntax

<jml:useCookie id = "beanInstanceName" 
              [scope = "page | request | session | application"]
              [type = "string | boolean | number | fpnumber"]
               cookie = "cookieName" />

Attributes

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.

Example

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;
             }
     }
%>

JML remove Tag

This tag removes an object from its scope.

Syntax

<jml:remove id = "beanInstanceName" 
           [scope = "page | request | session | application" ] />

Attributes

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.

Example

The following example removes the session user object:

<jml:remove id = "user" scope = "session" />

This is equivalent to the following:

<% session.removeValue("user"); %>

Logic and Flow Control Tag Descriptions

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.

JML if Tag

This tag evaluates a single conditional statement. If the condition is true, then the body of the if tag is executed.

Syntax

<jml:if condition = "<%= jspExpression %>" >
     ...body of if tag (executed if the condition is true)...
</jml:if>

Attributes

condition--Specifies the conditional expression to be evaluated. This attribute is required.

Example

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>&nbsp
</jml:if>

JML choose...when...[otherwise] Tags

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.

Syntax

<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>

Attributes

The when tag uses the following attribute (the choose and otherwise tags have no attributes):

condition--Specifies the conditional expression to be evaluated. This attribute is required.

Example

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>

JML for Tag

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.

Note:
Descending ranges are not supported; the from value must be less than or equal to the to value.

Syntax

<jml:for id = "loopVariable"
         from = "<%= jspExpression %>" 
         to = "<%= jspExpression %>" >
      ...body of for tag (executed once at each value of range, inclusive)...
</jml:for>

Attributes

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.

Example

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>

JML foreach Tag

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:

Java array
java.util.Enumeration
java.util.Vector

Syntax

<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>

Attributes

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.

Example

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>

JML return Tag

When this tag is reached, execution returns from the page without further processing.

Syntax

<jml:return />

Attributes

None.

Example

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>

JML flush Tag

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.

Syntax

<jml:flush />

Attributes

None.

Example

The following example flushes the current page contents before performing an expensive operation.

<jml:flush />
<% myBean.expensiveOperation(out); %>