A JML Compile-Time Syntax and Tags

Important:

The JML tag library is deprecated in the OC4J 10.1.2 implementation, and will be desupported in later implementations. Use the standard JSTL tag library instead.

The JSP tag library framework was introduced in the JSP 1.1 specification. Oracle JSP releases prior to the implementation of the JSP 1.1 specification could support JML tags only as Oracle-specific translator extensions. This is referred to as compile-time tag support in this manual.

JSP releases with OC4J continue to support the compile-time JML implementation; however, it is generally advisable to use the standards-compliant runtime implementation whenever possible. The runtime implementation is documented in Chapter 3, "JSP Markup Language Tags".

This appendix discusses features of the compile-time implementation that are not in common with the runtime implementation, and consists of the following sections:

JML Compile-Time Syntax Support
JML Compile-Time Tag Support

For a general discussion of when it might be advantageous to use a compile-time implementation, refer to the Oracle Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide.

JML Compile-Time Syntax Support

The following sections describe Oracle-specific bean reference syntax and expression syntax supported by the compile-time JML implementation for specifying tag attribute values:

JML Bean References and Expressions, Compile-Time Implementation
Attribute Settings with JML Expressions

This functionality requires the OC4J JSP translator; it is not portable to other JSP environments.

JML Bean References and Expressions, Compile-Time Implementation

A bean reference is any reference to a JavaBean instance that results in accessing either a property or a method of the bean. This includes a reference to a property or method of a bean where the bean itself is a property of another bean.

This becomes cumbersome, because standard JavaBeans syntax requires that properties be accessed by calling their accessor methods rather than by direct reference. For example, consider the following direct reference:

a.b.c.d.doIt()

This must be expressed as follows in standard JavaBeans syntax:

a.getB().getC().getD().doIt()

The Oracle compile-time JML implementation, however, offers abbreviated syntax, as described in the following subsections.

JML Be an References

Oracle-specific syntax supported by the compile-time JML implementation allows bean references to be expressed using direct dot (".") notation. Note that standard bean property accessor method syntax is also still valid.

Consider the following standard JavaBean reference:

customer.getName()

In JML bean reference syntax, you can express this in either of the following ways:

customer.getName()

or:

customer.name

JavaBeans can optionally have a default property whose reference is assumed if no reference is explicitly stated. You can omit default property names in JML bean references. In the example above, if name is the default property, then the following are all valid JML bean references:

customer.getName()

or:

customer.name

or:

customer

Most JavaBeans do not define a default property. Of those that do, the most significant are the JML datatype JavaBeans described in Chapter 2, "JavaBeans for Extended Types".

JML E xpressions

JML expression syntax supported by the compile-time JML implementation is a superset of standard JSP expression syntax, adding support for the JML bean reference syntax documented in the preceding section.

A JML bean reference appearing in a JML expression must be enclosed in the following syntax:

$[JML_bean_reference]

Attrib ute Settings with JML Expressions

Tag attribute documentation under "JSP Markup Language (JML) Tag Descriptions" notes standards-compliant syntax. You can set attributes, as documented there, for either the runtime or the compile-time JML implementation and even for non-Oracle JSP environments.

If you intend to use only the Oracle-specific compile-time implementation, however, you can set attributes using JML bean references and JML expression syntax, as documented in the preceding section, "JML Bean References and Expressions, Compile-Time Implementation". Note the requirements that follow.

Wherever Chapter 3 documents an attribute that accepts either a string literal or an expression, you can use a JML expression in its $[...] syntax inside standard JSP <%=...%> syntax.

Consider an example using the JML useVariable tag. You would use syntax such as the following for the runtime implementation:
```
<jml:useVariable id = "isValidUser" type = "boolean" 
                 value = "<%= dbConn.isValid() %>" scope = "session" />
```
You can alternatively use syntax such as the following for the compile-time implementation (the value attribute can be either a string literal or an expression):
```
<jml:useVariable id = "isValidUser" type = "boolean" 
                 value = "<%= $[dbConn.valid] %>" scope = "session" />
```

Wherever Chapter 3 documents an attribute that accepts an expression only, you can use a JML expression in its $[...] syntax without being nested in <%=...%> syntax.

Consider an example using JML choose...when tags. You would use something such as the following syntax for the runtime implementation (presuming orderedItem is a JmlBoolean instance):

<jml:choose>
     <jml:when condition = "<%= orderedItem.getValue() %>"  >
               You have changed your order:
             -- outputs the current order --
     </jml:when>
     <jml:otherwise>
               Are you sure we can't interest you in something?
     </jml:otherwise>
</jml:choose>

You can alternatively use syntax such as the following for the compile-time implementation, where the condition attribute can be an expression only:

<jml:choose>
     <jml:when condition = "$[orderedItem]"  >
               You have changed your order:
             -- outputs the current order --
     </jml:when>
     <jml:otherwise>
               Are you sure we can't interest you in something?
     </jml:otherwise>
</jml:choose>

JML Compile-Time Tag Support

This section presents the following:

Documentation of the taglib directive that you must use for compile-time JML support
Summary of all compile-time tags, noting which are desupported in the runtime implementation
Description of tags supported by the compile-time implementation that are desupported in the runtime implementation

Tags still supported in the runtime implementation are documented in "JSP Markup Language (JML) Tag Descriptions".

Note:

In most cases, JML tags that are desupported in the runtime implementation have standard JSP equivalents. Some of the compile-time tags, however, were desupported because they have functionality that is difficult to implement when adhering to the current JSP specification.

The taglib Di rective for Compile-Time JML Support

The Oracle compile-time JML support implementation uses a custom class, OpenJspRegisterLib, to implement JML tag support.

In a JSP page using JML tags with the compile-time implementation, the taglib directive must specify the fully qualified name of this class, instead of specifying a TLD file as in standard JSP tag library usage:

<%@ taglib uri="oracle.jsp.parse.OpenJspRegisterLib" prefix="jml" %>

For information about usage of the taglib directive for the JML runtime implementation, see "Overview of the JSP Markup Language (JML) Tag Library".

JML Tag Summary, Compile-Time Versus Runtime

Most JML tags are available in both the runtime model and the compile-time model; however, there are exceptions, as summarized in the following tables.

Table A-1 Bean-Binding Tags: Compile-Time Model Versus Runtime Model

Tag	Supported in Oracle Compile-Time Implementation?	Supported in Oracle Runtime Implementation?
useBean	Yes	No; use `jsp:useBean`.
useVariable	Yes	Yes
useForm	Yes	Yes
useCookie	Yes	Yes
remove	Yes	Yes

Table A-2 Bean Manipulation Tags: Compile-Time Model Versus Runtime Model

Tag	Supported in Oracle Compile-Time Implementation?	Supported in Oracle Runtime Implementation?
getProperty	Yes	No; use `jsp:getProperty`.
setProperty	Yes	No; use `jsp:setProperty`.
set	Yes	No
call	Yes	No
lock	Yes	No

Table A-3 Control Flow Tags: Compile-Time Model Versus Runtime Model

Tag	Supported in Oracle Compile-Time Implementation?	Supported in Oracle Runtime Implementation?
if	Yes	Yes
choose	Yes	Yes
for	Yes	Yes
foreach	Yes; `type` attribute is optional.	Yes; `type` attribute is required.
return	Yes	Yes
flush	Yes	Yes
include	Yes	No; use `jsp:include`.
forward	Yes	No; use `jsp:forward`.

Table A-4 XML Tags: Compile-Time Model Versus Runtime Model

Tag	Supported in Oracle Compile-Time Implementation?	Supported in Oracle Runtime Implementation?
transform	Deprecated	Yes
styleSheet	Deprecated	Yes

Table A-5 Utility Tags: Compile-Time Model Versus Runtime Model

Tag	Supported in Oracle Compile-Time Implementation?	Supported in Oracle Runtime Implementation?
print	Yes; use double-quotes to specify a string literal.	No; use JSP expressions.
plugin	Yes	No; use `jsp:plugin`.

Note:

Since Oracle9iAS Release 2 (9.0.3), the transform and styleSheet tags are deprecated in the compile-time implementation.

Descriptions of Additional JML Tags, Compile-Time Implementation

The following sections provide detailed descriptions of JML tags that are still supported by the JML compile-time implementation but are not supported by the JML runtime implementation. The tags supported in the runtime implementation are documented under "JSP Markup Language (JML) Tag Descriptions".

JML useBean Tag
JML getProperty Tag
JML setProperty Tag
JML set Tag
JML call Tag
JML lock Tag
JML include Tag
JML forward Tag
JML print Tag
JML plugin Tag

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.

JML us eBean Tag

This tag declares an object to be used in the page, locating the previously instantiated object at the specified scope by name if it exists. If it does not exist, the tag creates a new instance of the appropriate class and attaches it to the specified scope by name.

The syntax and semantics are the same as for the standard jsp:useBean tag, except that wherever a JSP expression is valid in jsp:useBean usage, either a JML expression or a JSP expression is valid in JML useBean usage.

You can refer to the Oracle Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide for an overview of the jsp:useBean tag.

Syntax

<jml:useBean id = "beanInstanceName" 
[ scope ="page" | "request" | "session" | "application" ]
  class ="package.class" | 
  type = "package.class" | 
  class ="package.class" type = "package.class" |
  beanName = "package.class" | "<%= jmlExpression %>" type = "package.class"  />

Alternatively, you can have additional nested tags, such as setProperty tags, and use a </jml:useBean> end-tag.

Attributes

In addition to specifying id, you must specify class, type (or class and type), or beanName.

Refer to the Sun Microsystems JavaServer Pages Specification for detailed information about jsp:useBean attributes and their syntax.

Example

<jml:useBean id = "isValidUser" class = "oracle.jsp.jml.JmlBoolean" scope = "session" />

JML getP roperty Tag

This tag is functionally identical to the standard jsp:getProperty tag. It prints the value of the bean property into the response.

For general information about getProperty usage, refer to the Oracle Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide or the Sun Microsystems JavaServer Pages Specification.

Syntax

<jml:getProperty name = "beanInstanceName" 
                 property = "propertyName" />

Attributes

name (required): This is the name of the bean whose property is being retrieved.
property (required): This is the name of the property being retrieved.

Example

The following example outputs the current value of the salary property. Assume salary is of type JmlNumber.

<jml:getProperty name="salary" property="value" />

This is equivalent to the following:

<%= salary.getValue() %>

JML set Property Tag

This tag covers the functionality supported by the standard jsp:setProperty tag and adds functionality to support JML expressions. In particular, you can use JML bean references.

For general information about setProperty usage, refer to the Oracle Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide or the Sun Microsystems JavaServer Pages Specification.

Syntax

<jml:setProperty name = "beanInstanceName" 
                 property = " * " | 
                 property = "propertyName" [ param = "parameterName" ] | 
                 property = "propertyName"
               [ value = "stringLiteral" | "<%= jmlExpression %>" ] />

Attributes

name (required): This is the name of the bean whose property is being set.
property (required): This is the name of the property being set.
value: This is an optional parameter that lets you set the value directly instead of from a request parameter. The JML setProperty tag supports JML expressions in addition to standard JSP expressions to specify the value.

Example

The following example updates salary with a six percent raise. Assume salary is of type JmlNumber.

<jml:setProperty name="salary" property="value" value="<%= $[salary] * 1.06 %>" />

This is equivalent to the following:

<% salary.setValue(salary.getValue() * 1.06); %>

JML s et Tag

This tag provides an alternative for setting a bean property, using syntax that is more convenient than that of the setProperty tag.

Syntax

<jml:set name = "beanInstanceName.propertyName"
         value = "stringLiteral" | "<%= jmlExpression %>" />

Attributes

name (required): This is a direct reference (JML bean reference) to the bean property to be set.
value (required): This is the new property value. It is expressed either as a string literal, a JML expression, or a standard JSP expression.

Example

Each of the following examples updates salary with a six percent raise. Assume salary is of type JmlNumber.

<jml:set name="salary.value" value="<%= salary.getValue() * 1.06 %>" />

or:

<jml:set name="salary.value" value="<%= $[salary.value] * 1.06 %>" />

or:

<jml:set name="salary" value="<%= $[salary] * 1.06 %>" />

These are equivalent to the following:

<% salary.setValue(salary.getValue() * 1.06); %>

JML c all Tag

This tag provides a mechanism to invoke bean methods that return nothing.

Syntax

<jml:call method = "beanInstanceName.methodName(parameters)" />

Attributes

method (required): This is the method call as you would write it in a scriptlet, except that the beanInstancename.methodName portion of the statement can be written as a JML bean reference if enclosed in JML expression $[... ] syntax.

Example

The following example redirects the client to a different page:

<jml:call name='response.sendRedirect("http://www.oracle.com/")' />

This is equivalent to the following:

<% response.sendRedirect("http://www.oracle.com/"); %>

JML lo ck Tag

This tag allows controlled, synchronous access to the named object for any code that uses it within the tag body.

Generally, JSP developers need not be concerned with concurrency issues. However, because application-scope objects are shared across all users running the application, access to critical data must be controlled and coordinated.

You can use the JML lock tag to prevent concurrent updates by different users.

Syntax

<jml:lock name = "beanInstanceName" >
   ...body...
</jml:lock>

Attributes

name (required): This is the name of the object that should be locked during execution of code in the lock tag body.

Example

In the following example, pageCount is an application-scope JmlNumber value. The variable is locked to prevent the value from being updated by another user between the time this code gets the current value and the time it sets the new value.

<jml:lock name="pageCount" >
    <jml:set name="pageCount.value" value="<%= pageCount.getValue() + 1 %>" />
</jml:lock>

This is equivalent to the following:

<% synchronized(pageCount) 
   {
      pageCount.setValue(pageCount.getValue() + 1);
   } 
%>

JML inc lude Tag

This tag includes the output of another JSP page, a servlet, or an HTML page in the response of the including page (the page invoking include). It provides the same functionality as the standard jsp:include tag except that the page attribute can also be expressed as a JML expression.

For general information about include usage, refer to the Oracle Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide or the Sun Microsystems JavaServer Pages Specification.

Syntax

<jml:include page = "relativeURL" | "<%= jmlExpression %>" 
             flush = "true" | "false" />

Attributes

For general information about include attributes and usage, refer to the Sun Microsystems JavaServer Pages Specification.

Example

The following example includes the output of table.jsp, a presentation component that renders an HTML table based on data in the query string and request attributes.

<jml:include page="table.jsp?maxRows=10" flush="true" />

JML for ward Tag

This tag forwards the request to another JSP page, a servlet, or an HTML page. It provides the same functionality as the standard jsp:forward tag except that the page attribute can also be expressed as a JML expression.

For general information about forward usage, refer to the Oracle Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide.

Syntax

<jml:forward page = "relativeURL" | "<%= jmlExpression %>" />

Attributes

For general information about forward attributes, refer to the Sun Microsystems JavaServer Pages Specification.

Example

<jml:forward page="altpage.jsp" />

JML pri nt Tag

This tag provides essentially the same functionality as a standard JSP expression of the form: <%= expr %>. A specified JML expression or string literal is evaluated and the result is output into the response. With this tag, the JML expression does not have to be enclosed in <%= ... %> syntax; however, a string literal must be enclosed in double-quotes.

Syntax

<jml:print eval = '"stringLiteral"' | "jmlExpression" />

Attributes

eval (required): Specifies the string or expression to be evaluated and output.

Examples

Either of the following examples outputs the current value of salary, which is of type JmlNumber:

<jml:print eval="$[salary]" />

or:

<jml:print eval="salary.getValue()" />

The following example prints a string literal:

<jml:print eval='"Your string here"' />

JML plu gin Tag

This tag has functionality identical to that of the standard jsp:plugin tag.

For general information about plugin usage, refer to the Oracle Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide or the Sun Microsystems JavaServer Pages Specification.

A JML Compile-Time Syntax and Tags

JML Compile-Time Syntax Support

JML Bean References and Expressions, Compile-Time Implementation

JML Bean References

JML Expressions

Attribute Settings with JML Expressions

JML Compile-Time Tag Support

The taglib Directive for Compile-Time JML Support

JML Tag Summary, Compile-Time Versus Runtime

Descriptions of Additional JML Tags, Compile-Time Implementation

JML useBean Tag

Syntax

Attributes

Example

JML getProperty Tag

Syntax

Attributes

Example

JML setProperty Tag

Syntax

Attributes

Example

JML set Tag

Syntax

Attributes

Example

JML call Tag

Syntax

Attributes

Example

JML lock Tag

Syntax

Attributes

Example

JML include Tag

Syntax

Attributes

Example

JML forward Tag

Syntax

Attributes

Example

JML print Tag

Syntax

Attributes

Examples

JML plugin Tag

JML Be an References

JML E xpressions

Attrib ute Settings with JML Expressions

The taglib Di rective for Compile-Time JML Support

JML us eBean Tag

JML getP roperty Tag

JML set Property Tag

JML s et Tag

JML c all Tag

JML lo ck Tag

JML inc lude Tag

JML for ward Tag

JML pri nt Tag

JML plu gin Tag