OracleJSP Support for JavaServer Pages Developer's Guide and Reference Release 1.1.2.3 Part Number A90208-01 |
|
OracleJSP 1.0.0.6.x releases, because they were JSP 1.0 implementations, could support JML tags only as Oracle-specific extensions. (The tag library framework was not added to the JavaServer Pages specification until JSP 1.1.) For those releases, JML tag processing was built into the OracleJSP translator. This is referred to as "compile-time JML support".
OracleJSP 1.1.x releases continue to support the compile-time JML implementation; however, it is generally advisable to use the runtime implementation whenever possible. The runtime implementation is documented in Chapter 7, "JSP Tag Libraries and the Oracle JML Tags".
This appendix discusses features of the compile-time implementation that are not in common with the runtime implementation. This includes the following topics:
This section discusses two aspects of compile-time tag libraries compared to runtime tag libraries:
taglib
directive required for the compile-time JML implementation in particular
The Sun Microsystems JavaServer Pages Specification, Version 1.1, describes a runtime support mechanism for custom tag libraries. This mechanism, using an XML-style tag library description file to specify the tags, is covered in "Standard Tag Library Framework".
Creating and using a tag library that adheres to this model assures that the library will be portable to any standard JSP environment.
There are, however, reasons to consider compile-time implementations:
In the future, Oracle may offer a general framework for creating custom tag libraries with compile-time tag implementations. Such implementations would depend on the OracleJSP translator, so would not be portable to other JSP environments.
The general advantages and disadvantages of compile-time implementations apply to the Oracle JML tag library as well. There may be situations where it is advantageous to use the compile-time JML implementation as first introduced in older versions of OracleJSP. There are also a few additional tags in that implementation, and some additional expression syntax that is supported. (See "JML Compile-Time/1.0.0.6.x Syntax Support" and "JML Compile-Time/1.0.0.6.x Tag Support".)
It is generally advisable, however, to use the JML runtime implementation that adheres to the JSP 1.1 specification.
The OracleJSP 1.0.0.6.x/compile-time JML support implementation uses a custom class supplied by Oracle, 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 (as opposed to specifying a TLD file as in standard JSP 1.1 tag library usage).
Following is an example:
<%@ taglib uri="oracle.jsp.parse.OpenJspRegisterLib" prefix="jml" %>
For information about usage of the taglib directive for the JML runtime implementation, see "The taglib Directive".
This section describes Oracle-specific bean reference syntax and expression syntax supported by the compile-time JML implementation, for specifying tag attribute values. The following topics are covered:
This functionality is not portable to other JSP environments.
Generally speaking, a bean reference is any reference to a JavaBean instance (bean) 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()
Oracle's compile-time JML implementation, however, offers abbreviated syntax.
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. Default property names can be omitted 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 simply:
customer
Most JavaBeans do not define a default property. Of those that do, the most significant are the JML datatype JavaBeans described in "JML Extended Datatypes".
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]
Tag attribute documentation under "JSP Markup Language (JML) Tag Descriptions" notes standard syntax that is portable. 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 "JML Bean References and Expressions, Compile-Time Implementation" above.
Note the following requirements:
$[...]
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" />
$[...]
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 (presume 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 (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>
This section presents the following:
These tags are not documented in "JSP Markup Language (JML) Tag Descriptions".
Most JML tags are available in both the runtime model and the compile-time model; however, there are exceptions, as summarized in Table C-1.
This section provides detailed descriptions of JML tags that are still supported by the JML compile-time implementation, but are not supported by the JML runtime implementation. These tags are not documented under "JSP Markup Language (JML) Tag Descriptions".
In summary, this consists of the following JML tags.
For the syntax documentation in the tag descriptions, note the following:
[...]
taglib
directive.
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 will create a new instance of the appropriate class and attach 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.
<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.
Refer to the Sun Microsystems JavaServer Pages Specification, Version 1.1 for information about attributes and their syntax.
<jml:useBean id = "isValidUser" class = "oracle.jsp.jml.JmlBoolean" scope = "session" />
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 "JSP Actions and the <jsp: > Tag Set" or to the Sun Microsystems JavaServer Pages Specification, Version 1.1.
<jml:getProperty name = "beanInstanceName" property = "propertyName" />
name
--This is the name of the bean whose property is being retrieved. This attribute is required.
property
--This is the name of the property being retrieved. This attribute is required.
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() %>
This tag covers the functionality supported by the standard jsp:setProperty
tag, but also adds functionality to support JML expressions. In particular, you can use JML bean references.
For general information about setProperty
usage, refer to "JSP Actions and the <jsp: > Tag Set" or to the Sun Microsystems JavaServer Pages Specification, Version 1.1.
<jml:setProperty name = "beanInstanceName" property = " * " | property = "propertyName" [ param = "parameterName" ] | property = "propertyName" value = "stringLiteral | <%= jmlExpression %>" />
name
--This is the name of the bean whose property is being set. This attribute is required.
property
--This is the name of the property being set. This attribute is required.
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.
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); %>
This tag provides an alternative for setting a bean property, using syntax that is more convenient than that of the setProperty
tag.
<jml:set name = "beanInstanceName.propertyName" value = "stringLiteral | <%= jmlExpression %>" />
name
--This is a direct reference (JML bean reference) to the bean property to be set. This attribute is required.
value
--This is the new property value. It is expressed either as a string literal, a JML expression, or a standard JSP expression. This attribute is required.
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); %>
This tag provides a mechanism to invoke bean methods that return nothing.
<jml:call method = "beanInstanceName.methodName(parameters)" />
method
--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. This attribute is required.
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/"); %>
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-scoped 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.
<jml:lock name = "beanInstanceName" > ...body... </jml:lock>
name
--This is the name of the object that should be locked during execution of code in the lock
tag body. This is a required attribute.
In the following example, pageCount
is an application-scoped 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); } %>
This tag includes the output of another JSP page, a servlet, or an HTML page in the response of this page (the page invoking the 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 "JSP Actions and the <jsp: > Tag Set" or to the Sun Microsystems JavaServer Pages Specification, Version 1.1.
<jml:include page = "relativeURL | <%= jmlExpression %>" flush = "true" />
For general information about include
attributes and usage, refer to the Sun Microsystems JavaServer Pages Specification, Version 1.1.
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" />
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 "JSP Actions and the <jsp: > Tag Set" or to the Sun Microsystems JavaServer Pages Specification, Version 1.1.
<jml:forward page = "relativeURL | <%= jmlExpression %>" />
For general information about forward
attributes and usage, refer to the Sun Microsystems JavaServer Pages Specification, Version 1.1.
<jml:forward page="altpage.jsp" />
This tag provides essentially the same functionality as a standard JSP expression: <%=
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.
<jml:print eval = '"stringLiteral"' | "jmlExpression" />
eval
--Specifies the string or expression to be evaluated and output. This attribute is required.
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"' />
This tag has functionality identical to that of the standard jsp:plugin
tag.
For general information about plugin
usage, refer to "JSP Actions and the <jsp: > Tag Set" or to the Sun Microsystems JavaServer Pages Specification, Version 1.1.
|
Copyright © 1996-2001, Oracle Corporation. All Rights Reserved. |
|