Skip Headers

Oracle Application Server Containers for J2EE JSP Tag Libraries and Utilities Reference 10g (9.0.4) Part Number B10319-01 |
Home | Contents | Index

# 3
JSP Markup Language Tags

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 consists of the following sections:

- Overview of the JSP Markup Language (JML) Tag Library

- JSP Markup Language (JML) Tag Descriptions

Note: 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 Oracle Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide.

## Overview of the JSP Markup Language (JML) Tag Library

OC4J supplies the JSP Markup Language (JML) tag library, developed according to JSP standards. 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: logic/flow control and bean binding.

These topics are covered in the following sections:

- JML Tag Library Philosophy

- JML Tag Categories

Note the following requirements for using JML tags:

- Verify that the file `ojsputil.jar` is installed and in your classpath. This file is provided with the OC4J installation, in the "well-known" tag library directory.

- The tag library descriptor, `jml.tld`, must be available to the application, and any JSP page using the library must have an appropriate `taglib` directive. In an Oracle Application Server installation, the TLD is in `ojsputil.jar`. The `uri` value for `jml.tld` is the following:

      http://xmlns.oracle.com/j2ee/jsp/tld/ojsp/jml.tld

You can refer to the Oracle Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide for information about `taglib` directives, the well-known tag library directory, TLD files, and the meaning of `uri` values.

Note: The custom JML tag library provided with OC4J pre-dates the JavaServer Pages Standard Tag Library (JSTL) and has areas of duplicate functionality. For standards compliance, it is now generally advisable to use JSTL instead. See "Support for the JavaServer Pages Standard Tag Library". Oracle is not desupporting the existing library, however. For features in the custom library that are not yet available in JSTL, where there seems to be general usefulness, Oracle will try to have the features adopted into the JSTL standard as appropriate.

### JML Tag Library Philosophy

JavaServer Pages technology is intended for two separate developer communities:

- Those whose primary skill is Java programming

- Those whose primary skill is in designing static content, particularly in HTML, and who may have limited scripting experience

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.

### JML Tag Categories

The JML tag library covers a feature set split into two functional categories, as summarized in Table 3-1.

##### Table 3-1 JML Tag Functional Categories

Tag Categories | Functionality | Tags
--- | --- | ---
Bean binding tags | The purpose of these tags is to declare or undeclare a JavaBean at a specified JSP scope. See "Bean Binding Tag Descriptions". | useVariable useForm useCookie remove
Logic/flow control tags | These tags offer simplified syntax to define code flow, such as for iterative loops or conditional branches. See "Logic and Flow Control Tag Descriptions". | if choose..when..[otherwise] foreach return flush

## JSP Markup Language (JML) Tag Descriptions

The following sections document the JML tags that are supported in the current JSP runtime implementation:

- Bean Binding Tag Descriptions

- Logic and Flow Control Tag Descriptions

  Notes: The prefix "jml:" is used in the tag syntax here. This is by convention but is not required. You can specify any desired prefix in your `taglib` directive. See "Tag Syntax Symbology and Notes" for general information about tag syntax conventions in this manual.

### Bean Binding Tag Descriptions

The following sections document JML tags used for bean-binding operations:

- JML useVariable Tag

- JML useForm Tag

- JML useCookie Tag

- JML remove Tag

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

##### Attributes

- `id` (required): Specifies the variable being declared.

- `scope`: Defines the duration or scope of the variable (as with a `jsp:useBean` tag). The default scope is `page`.

- `type` (required): Specifies the type of the variable. Type specifications refer to `JmlString`, `JmlBoolean`, `JmlNumber`, or `JmlFPNumber`.

- `value`: Use this to set the variable directly in the declaration, as either a string literal or a JSP expression enclosed in `<%=... %>` syntax. If this attribute 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.

##### 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` (required): Specifies the variable being declared or referenced.

- `scope`: Defines the duration or scope of the variable (as with a `jsp:useBean` tag). The default is "`page`".

- `type`: Specifies the type of the variable. Type specifications refer to `JmlString`, `JmlBoolean`, `JmlNumber`, or `JmlFPNumber`. The default 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.

##### Example

The following example sets a session variable named `user` of the type `JmlString` 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` (required): Specifies the variable being declared or referenced.

- `scope`: Defines the duration or scope of the variable. This attribute is optional; the default is "`page`".

- `type`: Identifies the type of the variable. Type specifications refer to `JmlString`, `JmlBoolean`, `JmlNumber`, or `JmlFPNumber`. The default 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.

##### Example

The following example sets a request variable named `user` of the type `JmlString` 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, typically a bean, from its scope.

##### Syntax

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

##### Attributes

- `id` (required): Specifies the name of the bean being removed.

- `scope`: Specifies the scope of the bean being removed. 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

The following sections document JML tags that are used for logic and flow control:

- JML if Tag

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

- JML for Tag

- JML foreach Tag

- JML return Tag

- JML flush Tag

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 jml:if tag (executed if the condition is true)...
    </jml:if>

##### Attributes

- `condition` (required): Specifies the conditional expression to be evaluated.

##### 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 the `when` conditions are all false, 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 jml:when tag (executed if the condition is true)...
        </jml:when>
        ...
        [...optional additional when tags...]
        [ <jml:otherwise>
            ...body of jml:otherwise tag (executed if all when conditions false)...
        </jml:otherwise> ]
    </jml:choose>

##### Attributes

The `when` tag uses the following attribute:

- `condition` (required): Specifies the conditional expression to be evaluated.

The `choose` and `otherwise` tags have no attributes.

##### 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` attribute 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 jml:for tag (executed once at each value of range, inclusive)...
    </jml:for>

##### Attributes

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

##### Example

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>

#### JML foreach Tag

This tag provides the ability to iterate over a homogeneous set of values. The body of the tag is executed once for each 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 jml:foreach tag (executes once for each element in data structure)...
    </jml:foreach>

##### Attributes

- `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 containing the set of values over which to iterate.

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

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

Alternatively, 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); %>

| Copyright © 2002, 2003 Oracle Corporation. All Rights Reserved. |
Home | Contents | Index