Release 1.0
| Oracle JSP - Developers Guide Release 1.0 |
JSPs have been designed to support two developer communities. The primary developer community is the script developer. JSPs core syntax defines tags for embedding server-side scripts in an HTML (or other text-based) page. The primary scripting language is Java. In this manner it is similar to Microsoft's Active Server Pages (ASPs). Unlike ASPs, JSPs also recognizes a developer community less skilled at scripting. These developers are application assemblers whose primary syntax is (HTML) tags; they are less familiar with scripting languages in particular a programming language like Java. For this community, JSPs encourages an alternative. JSPs defines an extensible tag mechanism. New tags can be introduced that replace the need for (complex) script.
JML or JSP Markup Language is a set of tags developed by Oracle designed to allow most web applications to be assembled within JSPs without writing script code (using the script syntax). In a sense it provides an alternative "templating" language for expressing the JSP. It targets those application assemblers unfamiliar with Java (statement) syntax. In this manner it is similar to Allaire's Cold Fusion CFML (Cold Fusion Markup Language) or XSLT. Though provided as an alternative, JML coexists with JSPs scripting language. JML and JSP script can exist on the same page. They operate on the same object set. And the JML expression language is derived directly from the underlying scripting language (and in its purest form identical to it).
The goal of JML is to allow most web applications to be assembled within JSPs without writing script code (using the script syntax). That is as long as business logic is encapsulated in objects/beans, a developer should be able to author most JSPs entirely using JML tags. The JML tags are grouped into 5 categories:
You are already familiar with a portion of JML. All the existing JSP (<jsp:xxx >) tags are provided in the jml tag namespace as these tags provide a good though incomplete foundation for a templating tag language. For example:
<jsp:useBean> is a Bean binding tag.
<jsp:setProperty> is a Bean manipulation tag.
<jsp:forward> is a control flow tag.
JML defines additional tags to round out this set making most JSP pages expressible entirely with JML. The rest of this chapter covers the details of these tags. For convenient reference, a syntax card is provided. The chapter 6 samples included in the download provide good illustrations of using JML. Each sample is a reprise of one introduced earlier in the Developer's Guide.
JML syntax is not automatically available in a JSP page. To use JML tags, you must direct the page to include the JML tag library. This is done using the JSP <%@ taglib> directive. The syntax for including JML is:
<%@ taglib uri="oracle.jsp.parse.OpenJspRegisterLib" prefix="jml" %>
It is recommended you include this directive in your globals.jsa. By doing so you will not have to include this directive in each of the application's pages.
JML tags follow the same syntax rules as the JSP tags. JML tags are either of the form:
<jml:tag attr="value">
Tag body
</jml:tag>
or
<jml:tag attr="value" />
if the tag has no body.
Four different forms of attribute values are supported.
attr = "String literal"
attr = "String literal | JML expressions"
attr = "JML Bean reference"
attr = "JML expression"
You should already be familiar with the first two forms as they are equivalent to what the standard JSP tags support. In the first case, an attribute can only have a literal value. An example would be the <jsp:useBean> tags id attribute. In the second case, an attribute can have either a literal or an expression. In this case the default is literal. Expressions are denoted using the "<%= expr %>" syntax. <jsp:setProperty> value attribute is an example of this.
JML's expression syntax is a superset of the JSP expression syntax. The JSP expression syntax is the expression syntax of the declared scripting language. I.e. Java. In Java, the syntax for accessing a bean's property is more cumbersome than typical scripting languages. Properties are accessed by calling their accessor methods rather then by direct reference. For example the customer's name property is accessed with either:
customer.getName();
customer.setName(newName);
rather than the more direct:
customer.name
This becomes more significant when properties are themselves objects whose properties or methods are being referenced. I.e. a.b.c.d.doIt() is expressed a.getB().getC().getD().doIt() in Java.
JML expression syntax extends JSP expression syntax by supporting a distinguished syntax for Bean references that allow for this direct reference style.
A Bean reference is any reference to a Bean/object that results in accessing either a Bean's property or method. This is transitive. A Bean reference includes references to properties and methods of objects that are a property of the bean (I.e. a.b.c.d.doIt()). A JML Bean reference is a Bean reference that is expressed using direct "." notation. As a Bean reference allows for calling methods the standard Bean property accessor syntax is also valid. The following Java Bean reference:
customer.getName()
can be expressed in a JML Bean reference as either:
customer.name
customer.getName()
Java Bean's can have an optionally defined default property. A default property is the property whose reference is assumed if none is explicitly stated. Default property names can be omitted in JML Bean references. In the example above, if name is the default property then a valid JML Bean reference is either:
customer
customer.name
customer.getName()
Currently, there aren't alot of Beans available to the JSP developer that define default properties. The most significant ones at the moment are the Oracle JSP data type beans described in Chapter 5. Each of these four data type beans' default property is value. Thus variable references in Oracle JSP are simplified.
<jml:if condition="orderedSweatshirt" > vs. <jml:if condition="orderedSweatshirt.getValue()" >
JML defines tags which contains attributes whose values can only be JML Bean references. In these cases no distinguishing syntax is needed to denote the use of the reference. The conditional example above provides one illustration. In another example, the <jml:set> tag, a complement for the <jml:setProperty> tag performs the identical operation in each of the following statements:
<jml:set name="salary.value" value="<%= salary.getValue() * 1.06 %>" />
<jml:set name="salary.value" value="<%= $[salary.value] * 1.06 %>" />
<jml:set name="salary" value="<%= $[salary] * 1.06 %>" />
A JML Expression is an expression that (optionally) includes JML Bean references. As these references are optional and the default is a regular Java reference, JML Bean references must be enclosed in $[] when used in a attributed value that supports a JML expression. For example the JML version of <jsp:setProperty> can be written as either:
<jml:setProperty name="salary" property="value" value="<%= $[salary.value] * 1.06 %>" />
or
<jml:setProperty name="salary" property="value" value="<%= $[salary] * 1.06 %>" />
assuming that value is the default property.
As already discussed above, JML expressions can be used in attributed values that expect either literals or expressions. In this situation the JML expression is enclosed in <%= %> syntax as depicted in the preceeding <jml:setProperty> example. JML also defines tags whose attributed values only contain expressions. In these cases, because JML doesn't have to distinguish between whether the value is a literal or not the <%= %> syntax is not used. The value is always interpreted as an expression. For example, the <jml:print> tag evaluates the enclosed expression and prints it into the response.
<jml:print eval="salary.getValue() * 1.06" />
<jml:print eval="$[salary] * 1.06" />Note: to make its use less prone for mistakes, JML does recognize the use of the <%= %> syntax to enclose these types of attributed values. It is however unnecessary.
JML defines various tags to declare JSP objects. It also provides a tag to undeclare an object.
<jml:useBean>
<jml:useVariable>
<jml:useForm>
<jml:useCookie>
<jml:remove>
The <jml:useBean> tag declares an object to be used in the page. The tag will locate the previously instantiated object at the specified scope by name if it exists. Otherwise, the tag will create a new instance of the object and attach it to the specified scope by name. The tag covers the <jsp:useBean> tag. Its syntax and semantics are identical except that where ever a JSP expression is valid in <jsp:useBean> a JML expression can be used. Refer to the <jsp:useBean> documentation for specifics.
Chapter 5 discusses the value of defining Beans to represent the basic Java data types. The <jml:useVariable> tag provides a straightforward way of declaring these Beans.
The <jml:useVariable> tag provides a convenient alternative to using the <jml:useBean> tag for declaring simple variables.
id: As with <jml:useBean> the id attribute names the variable being declared. It is required.
type: The type attribute identifies the type of the variable. Four types are currently supported: string, boolean, number, and fpnumber. Each covers the underlying Java type. number is a 32 bit number equivalent to a Java int. fpnumber is a 64 bit floating point number equivalent to a Java double. This attribute is required.
value: The value attribute allows the variable to be set directly in the declaration. I.e. without needing to use the <jml:set> tag. Value is a string literal or jml_expression (enclosed in <%= %>). This attribute is optional. If not specified the variables 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.
scope: As with <jml:useBean>, the scope attribute defines the duration or scope of the variable. This attribute is optional. If not specified the default scope of page is used.
<jml:useVariable id = "isValidUser" type = "boolean" value = "<%= $[dbConn.valid] %>" scope = "session" />is equivalent to:
The <jml:useForm> 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: As with <jml:useBean> the id attribute names the variable being declared/referenced. It is required.
type: The type attribute identifies the type of the variable. Four types are currently supported: string, boolean, number, and fpnumber. Each covers the underlying Java type. number is a 32 bit number equivalent to a Java int. fpnumber is a 64 bit floating point number equivalent to a Java double. This attribute is optional. If not specified the variable assumes the default type string.
param: The param attribute names the request parameter this variable should be set to. This attribute is required. If the request parameter exists the variables value is always updated regardless of whether this declaration brings the variable into extistence or not. If the request parameter doesn't exist the value of the variable remains unchanged.
scope: As with <jml:useBean>, the scope attribute defines the duration or scope of the variable. This attribute is optional. If not specified the default scope of page is used.
The following sets a session variable named "user" of type "string" to the value of the request parameter named "user".
It is equivalent to:
The <jml:useCookie> tag provides a convenient syntax for declaring variables and setting them to values contained in a cookie.
<jml:useCookie id = "beanInstanceName" scope = "page | request | session | application" type = "string | boolean | number | fpnumber" cookie = "cookieName" />
id: As with <jml:useBean> the id attribute names the variable being declared/referenced. It is required.
type: The type attribute identifies the type of the variable. Four types are currently supported: string, boolean, number, and fpnumber. Each covers the underlying Java type. number is a 32 bit number equivalent to a Java int. fpnumber is a 64 bit floating point number equivalent to a Java double. This attribute is optional. If not specified the variable assumes the default type string.
cookie: The name of the cookie this variable should be set to. This attribute is required. If the cookie exists the variable's value is always updated regardless of whether this declaration brings the variable into extistence or not. If the cookie doesn't exist the value of the variable remains unchanged.
scope: As with <jml:useBean>, the scope attribute defines the duration or scope of the variable. This attribute is optional. If not specified the default scope of page is used.
The following sets a request variable named "user" of type "string" to the value of the cookie named "user".
It is equivalent to:
<%
Cookies [] cookies = request.getCookies();
for (int i = 0; i < cookies.length; i++) {
if (cookies[i].getName().equals("user")) {
user.setValue(cookies[i].getValue());
break;
}
}
%>
The <jml:remove> tag removes an object from its scope.
id: The name of the bean being removed. It is required.
scope: This attribute is optional. If not specified the scopes are searched in the following order: page, request, session and application. The first attribute that matches the name in id is removed.
The following removes the session "user" variable:
This is equivalent to:
<%
session.removeValue("user");
%>
JML defines various tags to operate on the objects created using the tags from the previous sections. These tags include and extend from the standard JSP tags.
<jml:print>
<jml:getProperty>
<jml:setProperty>
<jml:set>
<jml:call>
<jml:lock>
The <jml:print> tag provides the same function as <%= expr %>. It evaluates the specified (JML) expression and outputs the result into the response.
<jml:print eval = "jmlExpression" />
eval: The expression to be evaluated and output. It is required.
The following code outputs the current value of salary. salary is a JmlNumber.
This is equivalent to:
<%= salary.getValue() %>
The eval attribute value can only be an expression. String literals must be written using expression notation.
<jml:print eval='"A string literal must be quoted"' />
The <jml:getProperty> tag is identical to the <jsp:getProperty>. It prints the value of the Bean's property into the response. Refer to the documentation on <jsp:getProperty> for details on its use.
<jml:getProperty name = "beanInstanceName" property = "propertyName" />
name: The name of the bean whose property is being set. It is required.
property: The property of the bean whose value is being retrieved.
The following code outputs the current value of salary. salary is a JmlNumber.
This is equivalent to:
<%= salary.getValue() %>
The <jml:setProperty> tag covers the function defined by <jsp:setProperty>. Refer to the document on <jsp:setProperty> for details on its use. <jml:setProperty> differs from <jsp:setProperty> in one key way. Whereas the form of <jsp:setProperty ....> supports a value that is a jsp expression (of the form <%= expression %>, <jml:setProperty> also supports the value being expressed via a jml expression. I.e. you can use jml bean references in <jml:setProperty> when setting the value of a property using an expression.
<jml:setProperty name = "beanInstanceName"
{ property = " * " | property = "propertyName" [ param = "parameterName" ] |
property = "propertyName value = " { stringLiteral | <%= jmlExpression %> | $ jmlExpression}"
} />
name: The name of the bean whose property is being set. It is required.
property: The property of the bean being set. Consult the JSP documentation for details on the various permutations.
value: One of the forms of <jml:setProperty> let's you set the value of the property directly. This differs from <jsp:setProperty> in that a jmlExpression is valid (one containing JML bean references).
The following code updates salary with a 6% raise. salary is a JmlNumber.
This is equivalent to:
<% salary.setValue(salary.getValue() * 1.06); %>
The <jml:set> tag provides an alternative, simpler syntax for setting a bean's property.
<jml:set name = "beanInstanceName.propertyName"
value = " { stringLiteral | <%= jmlExpression %> | $ jmlExpression}" } />
name: A direct reference (JML bean reference) to the bean's property that is to be set. It is required.
value: The new property value. It is expressed either as a stringLiteral or a JML expression. This is a required attribute.
Each of the following updates salary with a 6% raise. salary is a JmlNumber.
<jml:set name="salary.value" value="<%= salary.getValue() * 1.06 %>" />
<jml:set name="salary.value" value="<%= $[salary.value] * 1.06 %>" />
<jml:set name="salary" value="<%= $[salary] * 1.06 %>" />
This is equivalent to:
<% salary.setValue(salary.getValue() * 1.06); %>
The <jml:call> tag provides a mechanism for invoking Bean methods that don't return anything.
<jml:call method = "beanInstanceName.methodName(parameters)" />
method: The call statement as you would write it in the scripting language. Note: the beanInstancename.methodName portion of the statement can be written as a JML Bean reference. I.e. property references can be made usign the direct "." notation if the reference is enclosed in $[ ]. This is a required attribute..
The following redirects the client to a different page.
<jml:call name='response.sendRedirect("http://www.oracle.com/")' />
This is equivalent to:
<%
response.sendRedirect("http://www.oracle.com/");
%>
The <jml:lock> tag provides you controlled, synchronous access to the named object within the tag's body. Generally, JSP developers don't have to be concerned with concurrency issues. However, as application scoped objects are shared across all users running the application their access must be controlled in critical sections.
<jml:lock name = "beanInstanceName" />
name: The name of the object that should be locked during the execution of the code in this tags body. A lock prevents concurrent access (update) from occuring elsewhere. This is a required attribute..
In the following pageCount is an application scoped JML number. The variable is locked to prevent the value from being updated by another user after this code gets the current value but before it sets the new value.
<jml:lock name="pageCount" >
<jml:set name="pageCount.value" value="<%= pageCount.getValue() + 1 %>" />
</jml:lock>
This is equivalent to:
<%
synchronized(pageCount) {
pageCount.setValue(pageCount.getValue() + 1);
}
%>
JML defines tags to control the flow of page evaluation.
<jml:if>
<jml:choose>
<jml:for>
<jml:foreach>
<jml:return>
<jml:flush>
<jml:include>
<jml:forward>
The <jml:if> tag provides a single conditional statement. The body of the <jsp:if> tag is executed if and only if the condition evaluates to true.
<jml:if condition = "{ jmlExpression | <%= jmlExpression %> | $ jmlExpression }" >
Body of <jml:if>. This is executed if the condition is true.
</jml:if>
condition: The conditional expression. It is required. Because only an expression is valid the expression is not enclosed using <%= %>
The following code example comes from cart.jsp in the JspStore sample. cart.jsp displays what's in the user's shopping cart. This code checks to see if the variable holding the current tShirt order is empty of not. If its not empty the size the user has ordered is displayed. currTS is a JmlString.
<jml:if condition = "!currTS.isEmpty()" > <S>(size: <jml:print eval="currTS.getValue().toUpperCase()" />)</S>  </jml:if>
The <jml:choose> tag provides a multiple conditional statement. The body of the <jsp:choose> tag contains 1 or more <jml:when> tags. Each <jml:when> tag represents a condition. <jml:choose> executes the body of the first <jml:when> condition that evaluates to true. At most only one <jml:when> body will be executed. For the situation where none of the <jml:when> conditions evaluate to true an optional <jml:otherwise> tag can be used. The body of a <jml:otherwise> tag is executed if and only if no <jml:when> condition evaluates to true.
<jml:choose>
<jml:when condition = "{ jmlExpression | <%= jmlExpression %> | $ jmlExpression }" >
Body of <jml:when>. This is executed if the condition is true.
</jml:when> +
[ <jml:otherwise>
Body of <jml:otherwise>. This is executed if all the succeeding <jml:when> are false.
</jml:otherwise> ]
</jml:choose>
condition: The conditional expression. It is required. Because only an expression is valid the expression is not enclosed using <%= %>
The following code example is excerpted from cart.jsp in the JspStore sample. cart.jsp displays what's in the user's shopping cart. This code checks to see if anything has been ordered. If it has it displays the current order, otherwise it asks the user to shop again.
<jml:choose>
<jml:when condition = "$[orderedSweatshirt] || $[orderedTShirt]" >
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>
The <jml:for> tag provides the ability to iterate over a range. The body of the <jsp:for> tag is executed once per element in the range, inclusive. id is a local loop variable containing the value of the current range element. It is an int. The value starts at the value expressed in the from attributed and is incremented by 1 after executing the body of the loop until it equals the value expressed in the to attribute. At this point the body of the loop is executed one last time (to is inclusive) before transfering to the first statement following the <jml:for> tag. Note: this tag only supports ascending iterations. I.e. from should be less than or equal to to.
<jml:for id = "loopVariable"
from = "{ jmlExpression | <%= jmlExpression %> | $ jmlExpression }"
to = "{ jmlExpression | <%= jmlExpression %> | $ jmlExpression }" >
Body of <jml:for>. Executes once per iteration over the range (inclusive).
</jml:for>
id: Identifier name for the loop variable. It is valid only in the body of the <jml:for> tag. It holds the current iteration value. it is a Java int. It is required.
from: A JML expression that evaluates to an Java int. It defines id's initial value. This is a required attribute.
to: A JML expression that evaluates to an Java int. It defines id's last value. This is a required attribute.
The following code prints "Hello World" progressively smaller by enclosing the string in an HTML heading tag.
<jml:for id="i" from="1" to="5" >
<H<jml:print eval="i" />
Hello World!
</H<jml:print eval="i" />
</jml:for>
The <jml:foreach> tag provides the ability to iterate over a homogeneous set. The body of the <jsp:foreach> tag is executed once per element in the set. If the set is empty the body is not executed. id is a local loop variable containing the value of the current set element. Its type by default is the type of value contained in the set. Some of the sets supported by <jsp:foreach> contain indeterminant types (java.lang.Object). In these situations the optional type attribute can be used to specify id's type.
<jsp:foreach> currently supports iterating over the following sets of data (data structures):
For large sets, an iteration can be limited by specifying an (optional) maximum number of iterations. The limit attribute constrains the loop to the lesser of the number of elements in the set or the number of iterations specified by this attribute.
<jml:foreach id = "loopVariable"
in = "{bean.property | bean.method }"
limit = "{ jmlExpression | <%= jmlExpression %> | $ jmlExpression }"
type = "package.class | java primitive type" >
Body of <jml:foreach>. Iterates once for each element in the data structure
specified by "in". Within the body "in" contains the current element in the set.
</jml:foreach>
id: Identifier name for the loop variable. It is valid only in the body of the <jml:foreach> tag. It holds the current iteration element. Its type is that which is returned by the data structure unless the type attribute is specified. It is required.
in: A JML expression that evaluates to a Java array, Enumeration or Vector. This is a required attribute.
limit: A JML expression that evaluates to an Java int. It defines maximum number of iterations regardless of the number of elements in the set. This is a required optional.
type: Defines the type if the loop variable. Most commonly used to specify a type when the set returns a java.lang.Object.
The following code iterates over the request parameters.
<jml:foreach id="name" in="request.getParameterNames()" type="java.lang.String" >
Parameter: <jml:print eval="name" />
Value: <jml:print eval="request.getParameter(name)" /> <br>
</jml:foreach>
Or more correctly, if you want to handle parameters with multiple values:
<jml:foreach id="name" in="request.getParameterNames()" type="java.lang.String" >
Parameter: <jml:print eval="name" />
Value:
<jml:foreach id="val" in="request.getParameterValues(name)" type="java.lang.String" >
<jml:print eval="val" /> :
</jml:foreach>
<br>
</jml:foreach>
The <jml:return> tag causes the page processing to return from this point without further processing.
<jml:return />
The following code 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>
The <jml:flush> tag writes the current contents of the page buffer back to the client. This tag only applies if the page is buffered. Otherwise this tag has not effect.
<jml:flush />
The following code flushes the current page contents before doing an expensive operation.
<jml:flush />
<jml:call method="myBean.expensiveOperation(out)" />
The <jml:include> tag includes the output of another servlet, JSP, or HTML page in this page's response. It provides equivalent function as <jsp:include> except the page attribute can take a JML expression. See the JSP specification for further details concerning this tag.
<jml:include page = "{ relativeURL | <%= jmlExpression %> | $ jmlExpression }" flush = "true" />
The following code includes the output of table.jsp. table.jsp is a page designed only to be included in other pages. It is a presentation component that renders an HTML table based on data based in the query string and request attributes.
<jml:include page="table.jsp?maxRows=10" flush="true" />
The <jml:forward> tag forwards the request to another servlet, JSP, or HTML page. It provides equivalent function as <jsp:forward> except the page attribute can take a JML expression. See the JSP specification for further details concerning this tag.
<jml:forward page = "{ relativeURL | <%= jmlExpression %> | $ jmlExpression }" />
The following code forwards to a different page depending on the sex of the user.
<jml:choose >
<jml:when condition='request.getParameter("sex").toUpperCase().equals("M")' >
<jml:forward page="male.jsp" />
</jml:when>
<jml:otherwise>
<jml:forward page="female.jsp" />
</jml:otherwise>
</jml:choose>
JML provides a tag to simplify applying XSL transformations to the result of a JSP page. The details of this are covered in the next chapter: "XML/XSL and JSPs".
The <jml:transform> tag applies the named stylesheet to the result generated when the body if the tag is executed. See the next chapter for more details.
<jml:transform href = " {URL | relativeURL | <%= jmlExpression %> | $ jmlExpression}" >
Body of transform tag. After this body is evaluated it is tranformed using the
XSL stylesheet named by the href attribute.
</jml:transform>
See the next chapter for details and examples.
The <jml:stylsheet> tag applies the named stylesheet to the result generated when the body if the tag is executed. It is a synonym for the <jml:transform> tag. See the next chapter for more details.
<jml:stylesheet href = " {URL | relativeURL | <%= jmlExpression %> | $ jmlExpression}" >
Body of transform tag. After this body is evaluated it is tranformed using the
XSL stylesheet named by the href attribute.
</jml:stylesheet>
See the next chapter for details and examples.
The following tags don't fit any particular category.
The <jml:plugin> tag covers the <jsp:plugin> tag. It is provided for completeness, so a developer can develop using JML exclusively. See the JSP specification for complete details on using this tag.
|
|
