Developing Web Applications, Servlets, and JSPs for Oracle WebLogic Server

Using Custom WebLogic JSP Tags (cache, process, repeat)

The following sections describe the use of three custom JSP tags—cache, repeat, and process—provided with the WebLogic Server distribution:

• Overview of WebLogic Custom JSP Tags

• Using the WebLogic Custom Tags in a Web Application

• Cache Tag

• Process Tag

• Repeat Tag

 

---

Overview of WebLogic Custom JSP Tags

Oracle provides three specialized JSP tags that you can use in your JSP pages: cache, repeat, and process. These tags are packaged in a tag library jar file called weblogic-tags.jar. This jar file contains classes for the tags and a tag library descriptor (TLD). To use these tags, you copy this jar file to the Web application that contains your JSPs and reference the tag library in your JSP.

 

---

Using the WebLogic Custom Tags in a Web Application

Using the WebLogic custom tags requires that you include them within a Web application.

To use these tags in your JSP:

1. Copy the weblogic-tags.jar file from the ext directory of your WebLogic Server installation to the WEB-INF/lib directory of the Web application containing the JSPs that will use the WebLogic Custom Tags.

2. Reference this tag library descriptor in the <taglib> element of the J2EE standard Web application deployment descriptor, web.xml. For example:

   <taglib>
   
     <taglib-uri>weblogic-tags.tld</taglib-uri>
   
     <taglib-location>
   
        /WEB-INF/lib/weblogic-tags.jar
   
     </taglib-location>
   
   </taglib>
   

3. Reference the tag library in your JSP with the taglib directive. For example:

   <%@ taglib uri="weblogic-tags.tld" prefix="wl" %>
   

 

---

Cache Tag

The cache tag enables caching the work that is done within the body of the tag. It supports both output (transform) data and input (calculated) data. Output caching refers to the content generated by the code within the tag. Input caching refers to the values to which variables are set by the code within the tag. Output caching is useful when the final form of the content is the important thing to cache. Input caching is important when the view of the data can vary independently of the data calculated within the tag.

If one client is already recalculating the contents of a cache and another client requests the same content it does not wait for the completion of the recalculation, instead it shows whatever information is already in the cache. This is to make sure that the web site does not come to a halt for all your users because a cache is being recalculated. Additionally, the async attribute means that no one, not even the user that initiates the cache recalculation waits.

Two versions of the cache tag are available. Version 2 has additional scopes available.

Caches are stored using soft references to prevent the caching system from using too much system memory. Unfortunately, due to incompatibilities with the HotSpot VM and the Classic VM, soft references are not used when WebLogic Server is running within the HotSpot VM.

 

Refreshing a Cache

You can force the refresh of a cache by setting the _cache_refresh object to true in the scope that you want affected. For example, to refresh a cache at session scope, specify the following:

<% request.setAttribute("_cache_refresh", "true"); %>

If you want all caches to be refreshed, set the cache to the application scope. If you want all the caches for a user to be refreshed, set it in the session scope. If you want all the caches in the current request to be refreshed, set the _cache_refresh object either as a parameter or in the request.

The <wl:cache> tag specifies content that must be updated each time it is displayed. The statements between the <wl:cache> and </wl:cache> tags are only executed if the cache has expired or if any of the values of the key attributes (see the Cache Tag Attributes table) have changed.

 

Flushing a Cache

Flushing a cache forces the cached values to be erased; the next time the cache is accessed, the values are recalculated. To flush a cache, set its flush attribute to true. The cache must be named using the name attribute. If the cache has the size attribute set, all values are flushed. If the cache sets the key attribute but not the size attribute, you can flush a specific cache by specifying its key along with any other attributes required to uniquely identify the cache (such as scope or vars).

For example:

1. Define the cache.

   <wl:cache name="dbtable" key="parameter.tablename"
   
   scope="application">
   
   // read the table and output it to the page
   
   </wl:cache>
   

2. Update the cached table data.

3. Flush the cache using the flush attribute in an empty tag (an empty tag ends with / and does not use a closing tag). For example

   <wl:cache name="dbtable" key="parameter.tablename" scope="application" flush="true"/>
   

   Table 16-1 Cache Tag Attributes

   Attribute	Required	Default Value	Description
   timeout	no	-1	Cache timeout property. The amount of time, in seconds, after which the statements within the cache tag are refreshed. This is not proactive; the value is refreshed only if it is requested. If you prefer to use a unit of time other than seconds, you can specify an alternate unit by postfixing the value with desired unit: ms = milliseconds s = seconds (default) m = minutes h = hours d = days
   scope	no	application	Specifies the scope in which the data is cached. Valid scopes include: parameter, (versions 1,2)requests the HTTP servlet request parameters page, (versions 1,2)requests the JSP page context attributes (This scope does not exist for the cache filter.) request, (versions 1,2)requests the servlet request attributes. Request attributes are valid for the entire request, including any forwarded or included pages. cookie, (version 2)requests the cookie values found in the request. If there are multiple cookies with the same name, this request returns only the first value. requestHeader, (version 2)requests the values from the request Headers. If there are multiple Headers with the same name, only the value of the first is returned.
   scope (cont.)			responseHeader, (version 2)requests the values from the response Headers. If there are multiple Headers with the same name, only the value of the first is returned. If you set a response header, all response headers are replaced with the value you have set. This scope should not be used for storing content. session, (versions 1,2)requests the values from the session attributes of the current user. If there is no session then one will not be created by accessing the scope. The caches can become very large if you are caching content. application, (versions 1,2)requests the values found in the servlet context attributes. cluster, (versions 1,2)requests the values from the application scope, and when written to replicates the information across the cluster. Most caches will be either session or application scope.
   key	no	--	Specifies additional values to be used when evaluating whether to cache the values contained within the tags. Typically a given cache is identified by the cache name that you configured in web.xml. If that is not specified the request uri is used as a cache name. Using keys you can specify additional values to identify a tag. For example, if you want to separate out the cache for a given end user, then in addition to the cache name you can specify the keys as the userid, values for which you want to pick it up from the request parameter scope (query param/post params) plus perhaps a client ip. So you will specify your keys as: "parameter.userid,parameter.clientip" Here "parameter" is the scope (request parameter scope) and "userid"/"clientip" are the parameters/attributes. This means the primary key for the cache becomes the cache name (request uri in this case) + value of userid request param + value of clientip request param. The list of keys is comma-separated. The value of this attribute is the name of the variable whose value you wish to use as a key into the cache. You can additionally specify a scope by prepending the name of the scope to the name. For example: parameter.key | page.key | request.key | application.key | session.key It defaults to searching through the scopes in the order shown in the preceding list. Each named key is available in the cache tag as a scripting variable. A list of keys is comma-separated.
   async	no	false	If the async parameter is set to true, the cache will be updated asynchronously, if possible. The user that initiates the cache hit sees the old data.
   name	no	--	A unique name for the cache that allows caches to be shared across multiple JSP pages. This same buffer is used to store the data for all pages using the named cache. This attribute is useful for textually included pages that need cache sharing. If this attribute is not set, a unique name is chosen for the cache. We recommended that you avoid manually calculating the name of the tag; the key functionality can be used equivalently in all cases. The name is calculated as weblogic.jsp.tags.CacheTag. plus the URI plus a generated number representing the tag in the page you are caching. If different URIs reach the same JSP page, the caches are not shared in the default case. Use named caches in this case. System named caches can not be flushed and refreshed automatically.
   size	no	-1 (unlimited)	For caches that use keys, the number of entries allowed. The default is an unlimited cache of keys. With a limited number of keys the tag uses a least-used system to order the cache. Changing the value of the size attribute of a cache that has already been used does not change the size of that cache.
   vars	no	--	In addition to caching the transformed output of the cache, you can also cache calculated values within the block. These variables are specified exactly the same way as the cache keys. This type of caching is called Input caching. Variables are used to do input caching. When the cache is retrieved the variables are restored to the scope you specified. For example, for retrieving results from a database you used var1 from request parameter and var2 from session. When the cache is created the value of these variables are stored with the cache. The next time the cache is accessed these values are restored so you will be able to access them from their respective scopes. For example, var1 will be available from request and var2 from session.
   flush	no	none	When set to true, the cache is flushed. This attribute must be set in an empty tag (ends with /).

Additional properties of the cache system for version 2

• Each cache also has additional arbitrary attributes associated with it that the end user can manipulate and expect to be populated when the cache is retrieved.

• Cache listeners can be registered by putting an object that implements weblogicx.cache.CacheListener in a java.util.List that is present in any scope in the cache system under the "weblogicx.cache.CacheListener" key. If there is a List present in the scope, add your listener to the end.

The following examples show how you can use the <wl:cache> tag. Listing 16-1 Examples of Using the cache Tag

<wl:cache>

<!--the content between these tags will only be

 refreshed on server restart-->

</wl:cache>



<wl:cache key="request.ticker" timeout="1m">

<!--get stock quote for whatever is in the request parameter ticker

 and display it, only update it every minute-->

</wl:cache>



<!--incoming parameter value isbn is the number used to lookup the

 book in the database-->

<wl:cache key="parameter.isbn" timeout="1d" size="100">

<!--retrieve the book from the database and display 

the information -- the tag will cache the top 100 

most accessed book descriptions-->

</wl:cache>



<wl:cache timeout="15m" async="true">

<!--get the new headlines from the database every 15 minutes and

 display them-->

<!--do not let anyone see the pause while they are retrieved-->

</wl:cache>

 

---

Process Tag

Use the <wl:process> tag for query parameter-based flow control. By using a combination of the tag's four attributes, you can selectively execute the statements between the <wl:process> and </wl:process> tags. The process tag may also be used to declaratively process the results of form submissions. By specifying conditions based on the values of request parameters you can include or not include JSP syntax on your page.

Table 16-2 Process Tag Attributes

Tag Attribute	Required	Description
name	no	Name of a query parameter.
notname	no	Name of a query parameter.
value	no	Value of a query parameter.
notvalue	no	Value of a query parameter.

The following examples show how you can use the <wl:process> tag: Listing 16-2 Examples of Using the process tag:

<wl:process notname="update">

<wl:process notname="delete">

<!--Only show this if there is no update or delete parameter-->

<form action="<%= request.getRequestURI() %>">

  <input type="text" name="name"/>

  <input type="submit" name="update" value="Update"/>

  <input type="submit" name="delete" value="Delete"/>

</form>

</wl:process>

</wl:process>

<wl:process name="update">

<!-- do the update -->

</wl:process>

<wl:process name="delete">

<!--do the delete-->

</wl:process>

<wl:process name="lastBookRead" value="A Man in Full">

<!--this section of code will be executed if lastBookRead exists

 and the value of lastBookRead is "A Man in Full"-->

</wl:process>

 

---

Repeat Tag

Use the <wl:repeat> tag to iterate over many different types of sets, including Enumerations, Iterators, Collections, Arrays of Objects, Vectors, ResultSets, ResultSetMetaData, and the keys of a Hashtable. You can also just loop a certain number of times by using the count attribute. Use the set attribute to specify the type of Java objects.

Table 16-3 Repeat Tag Attributes

Tag Attribute	Required	Type	Description
set	No	Object	The set of objects that includes: Enumerations Iterators Collections Arrays Vectors Result Sets Result Set MetaData Hashtable keys
count	No	Int	Iterate over first count entries in the set.
id	No	String	Variable used to store current object being iterated over.
type	No	String	Type of object that results from iterating over the set you passed in. Defaults to Object. This type must be fully qualified.

The following example shows how you can use the <wl:repeat> tag. Listing 16-3 Examples of Using the repeat Tag

<wl:repeat id="name" set="<%= new String[] { "sam", "fred", "ed" } %>">

  <%= name %> 

</wl:repeat>



<% Vector v = new Vector();%> 

<!--add to the vector-->



<wl:repeat id="item" set="<%= v.elements() %>">

<!--print each element-->

</wl:repeat>