|
Oracle® Containers for J2EE JSP Tag Libraries and Utilities Reference
10g Release 3 (10.1.3) Part No. B14425-01 |
|
 Previous |
 Next |
|
Oracle® Containers for J2EE JSP Tag Libraries and Utilities Reference
10g Release 3 (10.1.3) Part No. B14425-01 |
|
|
Previous |
Next |
This manual documents tag libraries, JavaBeans, and other utilities supplied with Oracle Containers for J2EE (OC4J) that are implemented according to JSP standards. There is also a discussion of support for the JavaServer Pages Standard Tag Library (JSTL), and a section summarizing tag libraries provided with Oracle components outside of OC4J.
Oracle-specific features, as well as an introduction to the OC4J JSP container, standard JSP technology, and standard JSP 1.2 tag library features, are covered in the Oracle Containers for J2EE Support for JavaServer Pages Developer's Guide.
This chapter consists of the following sections:
Tags and JavaBeans introduced in the first section provide functionality in several different areas, including type extensions, integration with XML/XSL, database access, and programming convenience.
The Oracle extensions that are introduced in the following sections are implemented through tag libraries or custom JavaBeans that comply with JSP and JavaBeans standards.
|
Note: The Oracle JSP Markup Language (JML) tag library is officially removed from Oracle Application Server Release.Developers should use tags provided with the JavaServer Pages Standard Tag Library (JSTL), which encapsulate similar functionality in a standardized implementation. See "Support for the JavaServer Pages Standard Tag Library" for details on the JSTL. |
With the exception of JML, Oracle is not desupporting the existing libraries. 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.
|
Note:
|
For the syntax documentation in tag descriptions throughout this manual, note the following:
Italic indicates 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 attribute values are separated by vertical bars: |
Except where noted, you can use JSP runtime expressions to set tag attribute values: "<%= jspExpression %>"
Tag descriptions in this manual use certain tag prefixes by convention; however, you can designate any desired prefix in your taglib directives.
JSP pages generally rely on core Java types in representing scalar values. However, neither of the following standard type categories is fully suitable for use in JSP pages:
Primitive types such as int, float, and double
Values of these types cannot have a specified scope. They cannot be stored in a JSP scope object (for page, request, session, or application scope), because only objects can be stored in a scope object.
Wrapper classes in the standard java.lang package, such as Integer, Float, and Double
Values of these types are objects, so they can theoretically be stored in a JSP scope object. However, they cannot be declared in a jsp:useBean action, because the wrapper classes do not follow the JavaBean model and do not provide zero-argument constructors.
Additionally, instances of the wrapper classes are immutable. To change a value, you must create a new instance and assign it appropriately.
To work around these limitations, OC4J provides the JmlBoolean, JmlNumber, JmlFPNumber, and JmlString JavaBean classes in package oracle.jsp.jml to wrap the most common Java types.
For information, see "Overview of JML Extended Types".
|
Note: The JML extended types provide a convenient option if you are running OC4J on JDK 1.4 or earlier.If you are using JDK 5.0, you may want to take advantage of the autoboxing mechanism supported with the new JDK release, which provides automatic conversion between primitive types and wrapper types. See the following site for more information on autoboxing: http://java.sun.com/j2se/1.5.0/docs/guide/language/autoboxing.html |
OC4J provides the JspScopeListener interface for lifecycle management of Java objects of various scopes within a JSP application.
Standard servlet and JSP event-handling is provided through the javax.servlet.http.HttpSessionBindingListener interface, but this is for session-based events only. The Oracle JspScopeListener can be integrated with HttpSessionBindingListener to manage session-based events, and can handle page-based, request-based, and application-based events as well.
For information, see "JSP Event-Handling with JspScopeListener".
You can use JSP syntax to generate any text-based MIME type, not just HTML code. In particular, you can dynamically create XML output. When you use JSP pages to generate an XML document, however, you often want a stylesheet applied to the XML data before it is sent to the client. This is difficult in JavaServer Pages technology, because the standard output stream used for a JSP page is written directly back through the server.
OC4J provides special tags to specify that all or part of a JSP page should be transformed through an XSL stylesheet before it is output. Input can be from the tag body or from an XML DOM object, and output can be to an XML DOM object to the browser.
You can use these tags multiple times in a single JSP page if you want to specify different style sheets for different portions of the page.
There is additional XML support as well:
A utility tag converts data from an input stream to an XML DOM object.
Several tags, for such features as caching and SQL operations, now can take XML objects as input or send them as output.
XML utility tags are summarized in Table 1-1. Note that there is also XML functionality in the dbOpen SQL tag and the cacheXMLObj Web Object Cache tag. For more information, see Chapter 5, "XML and XSL Tag Support".
You can find information about standard JSP 1.2 XML support in the Oracle Containers for J2EE Support for JavaServer Pages Developer's Guide.
Table 1-1 Summary of XML Utility Tags
| Tag | Description | Attributes |
|---|---|---|
|
transform |
Output XML data with an XSL transformation, either to an HTTP client or a specified XML DOM object. |
href fromXMLObjName toXMLObjName toWriter |
|
styleSheet |
Same as |
href fromXMLObjName toXMLObjName toWriter |
|
parsexml |
Convert from an input stream to an XML DOM object. |
resource toXMLObjName validateResource root |
OC4J supplies a set of custom JavaBeans for use in accessing Oracle Database. The following beans are provided in the oracle.jsp.dbutil package:
ConnBean opens a database connection. This bean also supports data sources and connection pooling.
CursorBean provides general DML support for queries; UPDATE, INSERT, and DELETE statements; and stored procedure calls.
For information, see "JavaBeans for Data Access".
For JSP programmers, OC4J also provides a custom tag library for SQL functionality, wrapping the functionality of the JavaBeans. These tags are summarized in Table 1-2. For further information, see "SQL Tags for Data Access".
Table 1-2 Summary of Data-Access Tag Library
| Tag | Description | Attributes |
|---|---|---|
|
dbOpen |
Open a database connection. This tag also supports data sources and connection pooling. |
connId scope dataSource user password URL commitOnClose |
|
dbClose |
Close a database connection. |
connId scope |
|
dbQuery |
Execute a query. |
queryId connId scope output maxRows skipRows bindParams toXMLObjName |
|
dbCloseQuery |
Close the cursor for a query. |
queryId |
|
dbNextRow |
Process the rows of a result set. |
queryId |
|
dbExecute |
Execute any SQL statement (DML or DDL). |
connId scope output bindParams |
|
dbSetParam |
Set a parameter to bind into a |
name value scope |
|
deSetCookie |
Set a cookie. |
name value domain comment maxAge version secure path |
Web site personalization is a mechanism to tailor recommendations to users of a site, based on behavioral and demographic data. Recommendations are made in real-time, during a user's Web session. User behavior is saved to a database repository for use in building models for predictions of future user behavior.
OracleAS Personalization uses data mining algorithms in Oracle Database to choose the most relevant content available for a user. Recommendations are calculated by an OracleAS Personalization recommendation engine, using typically large amounts of data regarding past and current user behavior. This is superior to other approaches that rely on common-sense heuristics and require manual definition of rules in the system.
The OracleAS Personalization tag library brings this functionality to a wide audience of JSP developers for use in HTML, XML, or JavaScript pages. The tag interface is layered on top of the Java API of the recommendation engine.
Table 1-3 summarizes the OracleAS Personalization tag library. See Chapter 10, "Personalization Tags" for information.
Table 1-3 Summary of OracleAS Personalization Tag Library
| Tag | Description | Attributes |
|---|---|---|
|
startRESession |
Start an OracleAS Personalization recommendation engine session. |
REName REURL RESchema REPassword RECacheSize REFlushInterval applicationSession createSession userType userID storeUserIDIn disableRecording |
|
endRESession |
Explicitly end a recommendation engine session. |
(None) |
|
setVisitorToCustomer |
Use this tag for situations where an anonymous visitor creates a registered customer account. |
customerID |
|
getRecommendations |
Request a set of recommendations for purchasing, navigation, or ratings. |
from fromHotPicksGroups storeResultsIn storeInterestDimensionIn maxQuantity tuningName tuningDataSource tuningInterestDimension tuningPersonalizationIndex tuningProfileDataBalance tuningProfileUsage filteringName filteringTaxonomyID filteringMethod filteringCategories sortOrder |
|
getCrossSellRecommendations |
Request a set of recommendations for purchasing, navigation, or ratings, based on input of a set of past items (such as past purchases) that are used as a basis for the recommendations. |
storeResultsIn storeInterestDimensionIn fromHotPicksGroups inputItemList maxQuantity tuningName tuningDataSource tuningInterestDimension tuningPersonalizationIndex tuningProfileDataBalance tuningProfileUsage filteringName filteringTaxonomyID filteringMethod filteringCategories sortOrder |
|
selectFromHotPicks |
Request recommendations from a set of "hot picks" groups only. |
hotPicksGroups storeResultsIn storeInterestDimensionIn maxQuantity tuningName tuningDataSource tuningInterestDimension tuningPersonalizationIndex tuningProfileDataBalance tuningProfileUsage filteringName filteringTaxonomyID filteringMethod filteringCategories sortOrder |
|
evaluateItems |
Evaluate only the set of items that are input to the tag. |
storeResultsIn taxonomyID inputItemList tuningName tuningDataSource tuningInterestDimension tuningPersonalizationIndex tuningProfileDataBalance tuningProfileUsage sortOrder |
|
forItem |
Select individual items input to a tag that requires an input list. |
index itemList type ID |
|
getNextItem |
Optionally use this tag within some recommendation tags to access and process returned items. |
storeTypeIn storeIDIn storeItemIn |
|
recordNavigation |
Record a navigation item into the recommendation engine session cache. |
type ID index itemList |
|
recordPurchase |
Record a purchasing item into the recommendation engine session cache. |
type ID index itemList |
|
recordRating |
Record a rating item into the recommendation engine session cache. |
value type ID index itemList |
|
recordDemographic |
Record a demographic item into the recommendation engine session cache. |
type value |
|
removeNavigationRecord |
Remove a navigation item that had been recorded into the recommendation engine session cache earlier in the session. |
type ID index itemList |
|
removePurchaseRecord |
Remove a purchasing item that had been recorded into the recommendation engine session cache earlier in the session. |
type ID index itemList |
|
removeRatingRecord |
Remove a rating item that had been recorded into the recommendation engine session cache earlier in the session. |
value type ID index itemList |
|
removeDemographicRecord |
Remove a demographic item that had been recorded into the recommendation engine session cache earlier in the session. |
type value |
The Web services tag library provided with OC4J enables developers to conveniently create JSP pages for Web service client applications. The implementation uses a SOAP-based mechanism, supporting RPC-style or document-style services. A client application would access a Web Services Description Language (WSDL) document, then use the WSDL information to access the operations of a Web service.
The tag library also uses the Oracle implementation of the dynamic invocation API, described in the Oracle Application Server Web Services Developer's Guide . When a client application acquires a WSDL document at runtime, the dynamic invocation API is the vehicle for invoking any SOAP operation described in the WSDL document.
The Web services tag library is summarized in Table 1-4. For more information, see Chapter 11, "Web Services Tags".
Table 1-4 Summary of Web Services Tag Library
| Tag | Description | Attributes |
|---|---|---|
|
webservice |
Create a Web service proxy. The tag requires the URL of a WSDL document and uses either a binding and SOAP location or a service name and port in creating the proxy. |
wsdlUrl id scope binding soapLocation service port |
|
map |
Use |
localName namespaceUri javaType encodingStyle java2xmlClassName xml2javaClassName |
|
property |
Optionally use this tag to specify a name/value pair that defines any of several supported custom properties for use by the Web service client application. |
name value |
|
invoke |
Invoke an operation of a Web service. The |
id operation webservice inputMsgName outputMsgName xmlToWriter toXMLObjName |
|
part |
Use this tag if the operation being performed requires input message part values, using one part tag for each input part. |
name value |
OC4J provides tag libraries for file access (uploading and downloading) and for sending e-mail messages from an application.
For uploading files, you can use the httpUpload tag or the oracle.jsp.webutil.fileaccess.HttpUploadBean JavaBean. For downloading, there is the httpDownload tag or the HttpDownloadBean JavaBean. Table 1-5 summarizes the file access tags. For more information, see "File-Access JavaBeans and Tags".
Table 1-5 Summary of File Access Tag Library
| Tag | Description | Attributes |
|---|---|---|
|
httpUploadForm |
For convenience, you can use this tag to create a form in your application, using multipart encoded form data, that allows users to specify the files to upload. |
formsAction maxFiles fileNameSize maxFileNameSize includeNumbers submitButtonText |
|
httpUpload |
Upload files from the client to a server. You can upload into either a file system or a database. |
destination destinationType connId scope overwrite fileType table prefixColumn fileNameColumn dataColumn |
|
httpDownload |
Download files from a server to the client. You can download from either a file system or a database. |
servletPath source sourceType connId scope recurse fileType table prefixColumn fileNameColumn dataColumn |
For sending e-mail messages, optionally with server-side or client-side attachments, you can use the oracle.jsp.webutil.email.SendMailBean JavaBean or the sendMail tag. Table 1-6 summarizes the sendMail tag. See "Mail JavaBean and Tag" for more information.
OC4J provides a custom tag library to simplify the use of Enterprise JavaBeans in JSP pages. The functionality of the OC4J EJB tags follows the J2EE specification. The tags allow you to instantiate EJBs by name, using configuration information in the web.xml file.
There are tags to create a home instance, create an EJB instance, and iterate through a collection of EJBs. Table 1-7 summarizes the EJB tag library. See "EJB Tags" for more information.
Table 1-7 Summary of EJB Tag Library
| Tag | Description | Attributes |
|---|---|---|
|
useHome |
Look up the home interface for the EJB and create an instance of it. |
id type location local |
|
useBean |
Instantiate and use the EJB. The functionality is similar to that of the standard |
id type value scope local |
|
createBean |
For first instantiating an EJB, if you do not use the |
instance |
|
iterate |
Iterate through a collection of EJB instances (more typical for entity beans). |
id type collection max |
OC4J has utility tags for displaying a date, displaying an amount of money in the appropriate currency, displaying a number, iterating through a collection, evaluating and including the tag body (depending on whether the user belongs to a specified role), and displaying the last modification date of the current file. Table 1-8 summarizes these tags. See "General Utility Tags" for more information.
Table 1-8 Summary of General Utility Tag Library
| Tag | Description | Attributes |
|---|---|---|
|
displayCurrency |
Display a specified amount of money, formatted as currency for the locale. |
amount locale |
|
displayDate |
Display a specified date, formatted appropriately for the locale. |
date locale |
|
displayNumber |
Display the specified number, for the locale and optionally in the specified format. |
number locale format |
|
iterate |
Iterate through a collection. |
id type collection max |
|
ifInRole |
Evaluate the tag body and include it in the body of the JSP page, depending on whether the user is in the specified application role. |
role include |
|
lastModified |
Display the date of the last modification of the current file, in appropriate format for the locale. |
locale |
This section provides the following information:
An introduction to caching features supported by the Oracle Application Server in general and the OC4J JSP container in particular
A discussion of the role of the OC4J Web Object Cache in relation to other Oracle Application Server caching components
A summary of tag libraries relating to caching features
The Oracle tag libraries introduced in this section comply with JSP standards.
The Oracle Application Server and OC4J provide the following caching features:
Oracle Application Server Web Cache
This is an HTTP-level cache, maintained outside the application, providing very fast cache operations. It is a content-based cache, capable of caching static data (such as HTML, GIF, or JPEG files) or dynamic data (such as servlet or JSP results). Given that it exists as a content-based cache outside the application, it cannot cache objects (such as Java objects or XML DOM objects) in a Java object format. In addition, post-processing operations applicable to cached data cannot be coded in Java and are predefined by the cache itself.
The OracleAS Web Cache provides an ESI processor to support Edge Side Includes, an XML-style markup language that allows dynamic content assembly away from the Web server. This technology enables you to separate cacheable pages into distinct cached objects, as desired. OC4J supports this technology through its JESI tag library.
For an overview of Edge Side Includes and the OracleAS Web Cache, as well as detailed documentation of the JESI tag library, see Chapter 6, "JESI Tags for Edge Side Includes".
For additional information about the OracleAS Web Cache, see the Oracle Application Server Web Cache Administrator's Guide.
OC4J Web Object Cache
This is an application-level cache that is embedded and maintained within a Java Web application. It is a hybrid cache, both Web-based and object-based. A custom tag library or API enables you to define page fragment boundaries and to capture, store, reuse, process, and manage the intermediate and partial execution results of JSP pages and servlets as cached objects. Each page fragment can produce a separate cache object. The produced objects can be HTML or XML text fragments, XML DOM objects, or Java serializable objects. These objects can be cached conveniently in association with HTTP request and session semantics. Alternatively, they can be reused outside HTTP, such as when an application outputs cached XML objects through Simple Mail Transfer Protocol (SMTP), Java Messaging Service (JMS), Advanced Queueing (AQ), or Simple Object Access Protocol (SOAP).
For more information, see Chapter 7, "Web Object Cache Tags and API".
Oracle Application Server Java Object Cache
The Oracle Application Server Java Object Cache is a general-use Java cache to manage Java objects within a process, across processes, and on local disk. By managing local copies of objects that are difficult or expensive to retrieve or create, the Java Object Cache can significantly improve application performance. By default, the OC4J Web Object Cache uses the Oracle Application Server Java Object Cache as its underlying cache repository.
For details about the Java Object Cache, see the Oracle Containers for J2EE Services Guide.
It is important to understand the role of the OC4J Web Object Cache in the overall setup of a Web application. It works at the Java level and is closely integrated with the HTTP environment of servlet and JSP applications. By contrast, the Oracle Application Server Java Object Cache works at the Java object level, but is not integrated with HTTP. As for the OracleAS Web Cache, it is well integrated with HTTP and is orders of magnitude faster than the Web Object Cache, but it does not operate at the Java level and cannot be directly invoked by Web application code. For example, it cannot apply a style sheet to a cached DOM object within the J2EE container, reuse the cached result in other protocols, or allow direct DOM operations. OracleAS Web Cache can, however, apply a style sheet to text-based XML documents, as opposed to DOM objects, that were cached from the original Web server through HTTP.
The Web Object Cache is not intended for use as the main Web cache for an application. It is an auxiliary cache embedded within the same Java virtual machine that is running your servlets and JSP pages. Because the retrieval path for cached results in the Web Object Cache includes the JVM and the JSP and servlet engines, it generally takes much longer to serve a page from the Web Object Cache compared to the OracleAS Web Cache.
The Web Object Cache does not replace or eliminate the need for either the OracleAS Web Cache or the Oracle Application Server Java Object Cache. It is a complementary caching component in the overall framework of a Web application and should be used together with the other caching products, as appropriate. In fact, the Web Object Cache uses the Java Object Cache as its default repository. And through combined use of the OC4J JESI tags and Web Object Cache tags, you can use the Web Object Cache and OracleAS Web Cache together in the same page.
Think of the OracleAS Web Cache as the primary caching component. It serves cached pages directly to HTTP clients and handles large volumes of HTTP traffic quickly, fitting the requirements of most Web sites. You can use the OracleAS Web Cache to store complete Web pages or partial pages (through use of the JESI tags). Cached pages can be customized, to a certain extent, before being sent to a client, including cookie-replacement and page-fragment concatenation, for example.
It is advisable to use the OracleAS Web Cache as much as possible to speed up response and reduce the load on the Web application server and back-end database. The caching needs of a large percentage of Web pages can be addressed by the OracleAS Web Cache alone.
As a complement to the OracleAS Web Cache, you can use the Web Object Cache to capture intermediate results of JSP and servlet execution and subsequently reuse these cached results in other parts of the Java application logic. It is not beneficial to use the Web Object Cache in your Web application unless you can repeatedly reuse objects after they are cached and you require post-processing on cached objects before they are served to a client.
In comparison to the Oracle Application Server Java Object Cache, the Web Object Cache makes it much easier to store and maintain partial execution results in dynamic Web pages. The Java Object Cache, being a pure object-based framework for any general Java application, is not aware of any HTTP environment in which it might be embedded. For example, its cache keys do not automatically depend on HTTP cookies or sessions. When you directly use the Java Object Cache within a Web application, you are responsible for creating any necessary interfacing with resulting Web pages. The Java Object Cache provides only a programmatic way to specify cache maintenance policies, whereas the Web Object Cache allows the alternative of specifying policies through configuration files.
OC4J supplies two tag libraries for use with Oracle Application Server caching features:
JESI tag library
Web Object Cache tag library
This section summarizes those libraries.
OC4J provides the JESI tag library as a convenient interface to ESI tags and Edge Side Includes functionality for Web caching. Developers have the option of using ESI tags directly in any Web application, but JESI tags provide additional convenience in a JSP environment.
Table 1-9 summarizes the JESI tag library. See "Oracle JESI Tag Descriptions" for more information.
Table 1-9 Summary of JESI Tag LIbrary
| Tag | Description | Attributes |
|---|---|---|
|
control |
Control caching characteristics for JSP pages in the control/include usage model. You can use a JESI |
expiration maxRemovalDelay cache control |
|
include |
This tag, like a standard |
page alt ignoreError copyParam flush |
|
param |
This is a subtag of the JESI |
name value |
|
template |
Use this tag (together with JESI |
expiration maxRemovalDelay cache control |
|
fragment |
Use one or more JESI |
expiration maxRemovalDelay cache control |
|
codeblock |
This is a subtag of the JESI |
execute |
|
invalidate |
Use this tag, with its JESI |
url username password config output |
|
object |
Use this required subtag of the JESI |
uri prefix maxRemovalDelay |
|
cookie |
Optionally use this subtag of the JESI |
name value |
|
header |
Optionally use this subtag of the JESI |
name value |
|
personalize |
Use this tag to allow page customization, by directing the ESI processor to perform cookie value substitution for every request for an object. |
name default |
The OC4J Web Object Cache is a mechanism that allows Web applications written in Java to capture, store, reuse, post-process, and maintain the partial and intermediate results generated by a dynamic Web page, such as a JSP page or servlet. The programming interfaces it provides are a tag library (for use in JSP pages) and a Java API (for use in servlets).
Table 1-10 summarizes the Web Object Cache tag library. See "Web Object Cache Tag Descriptions" for more information.
Table 1-10 Summary of Web Object Cache Tag LIbrary
| Tag | Description | Attributes |
|---|---|---|
|
cache |
Use this tag to cache an object, for example a text fragment, in a JSP application. (Note, however, that there are separate tags for caching XML DOM objects or Java serializable objects.) |
policy ignoreCache invalidateCache scope autoType selectedParam selectedCookies reusableTimeStamp reusableDeltaTime name expirationType TTL timeInaDay dayInaWeek dayInaMonth writeThrough printCacheBlockInfo printCachePolicy cacheRepositoryName reportException |
|
cacheXMLObj |
Generally speaking, use this tag instead of the |
All attributes of the |
|
useCacheObj |
Use this tag to cache any Java serializable object. The |
All attributes of the |
|
cacheInclude |
This tag combines functionality of the |
policy page printCacheBlockInfo reportException |
|
invalidateCache |
Use this tag to programmatically invalidate a cache object. Most attributes of the |
policy ignoreCache scope autoType selectedParam selectedCookies name invalidateNameLike page autoInvalidateLevel cacheRepositoryName reportException |
