Tag Libraries

Tag libraries extend the JSP language to encapsulate business rules and other functionality without embedding Java code. They encourage the division of presentation logic from business logic by allowing the tags to be used in any JSP. Hundreds of available tag libraries perform a wide variety of tasks , and you can easily create your own. Additionally, as of this writing, JSR52, the JavaServer Pages Standard Tag Library (JSTL), is nearing completion. This library will give the Java community a set of standardized tags that will eventually become part of the J2EE standard. JSTL encapsulates some core functionality that is commonly used by JSP applications. Additionally, WebLogic Server includes tag libraries to help validate HTML forms, manage data caches, and perform general-purpose flow control and looping operations. WebLogic Portal Server supplies additional tags to help JSP developers to manage portal content and behavior.

Parts of a Tag Library

A JSP custom tag library has two components . The first is the tag handler class, which defines what the application server does when it encounters the tag. This Java class extends either javax.servlet.jsp. tagext .TagSupport or javax.servlet.jsp.tagext.BodyTagSupport . A class that extends one of these two does the work of the custom tag library.

The other part of a custom tag library is the library descriptor file. This file associates an XML tag within the JSP with the Java class that does the work of the tag. The tag library descriptor (TLD) file is an XML file that contains this mapping and other information about the tag library.

Implementing a Custom Tag Library

Now it's time to create a simple custom tag that prints the current date and time with an optional message that you supply in the call from the JSP. Certainly, there are simpler ways to print this information, but this approach will work for this small example.

Start by implementing the Java class. You first must decide from which of the two classes you are going to extend. The TagSupport class is used for tags that do not process the body of the custom tag. In this context, the body is the HTML or other code that is between the opening and closing tags. In the JSP, the TagSupport -based tag takes this form:

 <om:SampleTag attribute1="hello" /> 

The BodyTagSuppport class is extended if your custom tag needs to process the information in the body of the tag. In the JSP, it takes this form:

 <om:SampleTag attribute1="hello"> body </om:SampleTag> 

The simple example shown in Listing 18.9 does not need to process the body of the tag and so will extend from TagSupport . This file, named DateTag.java , is in myFirstServlet/WEB-INF/src/jspexample .

Listing 18.9 DateTag.java

 package jspexample; import javax.servlet.jsp.*; import javax.servlet.jsp.tagext.*; import java.io.*; import java.util.*; // // Simple custom tag library to output the current date and time that the server // is running in. // public class DateTag extends TagSupport { private String outputMessage = null; public int doStartTag() { try { JspWriter out = pageContext.getOut(); Date now = new Date(); if( outputMessage == null ) out.print( "The current date and time is " ); else out.print( outputMessage + " " ) ; out.print( now.toString() ); } catch( IOException ioe ) { System.err.println( "caught exception in DateTag: " + ioe ); } return( SKIP_BODY ); } public void setMessage( String message ) { outputMessage = message; } } 

You need to define the tag library descriptor file for this tag so that it can be used in JSP pages. Listing 18.10, named dateTag.tld , lives in myFirstWebApp/WEB-INF .

Listing 18.10 datetag.tld

 <?xml version="1.0" encoding="ISO-8859-1" ?> <!DOCTYPE taglib PUBLIC "-//Sun Microsystems, Inc.//DTD JSP Tag Library 1.2//EN" "weblogic-jsptaglib_1_1.dtd"> <taglib> <tlib-version>1.0</tlib-version> <jsp-version>1.2</jsp-version> <short-name>om</short- name > <uri>http://www.objectmind.com/schema/jsp/dateTag/1.1/</uri> <displayname>Simple Date</ displayname > <description>A simple date tag library</description> <tag> <name>simpledate</name> <tag-class>jspexample.DateTag</tag-class> <body-content>EMPTY</body-content> <attribute> <name>message</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> </tag> </taglib> 

Using the Custom Tag in a JSP

To use the custom tag in a JSP, you simply need to include it and use it. Listing 18.11 shows a small JSP file that does just that.

Listing 18.11 DateTagSample.jsp

 <html> <head> <%@ taglib uri="/WEB-INF/dateTag.tld" prefix="om" %> <title>A simple custom JSP tag library example</title> </head> <body> <b><om:simpledate /></b><br> <b><om:simpledate message="Now the current date and time is" /></b> </body> </html> 

Running DateTagSample.jsp produces the output shown in Figure 18.6.

Figure 18.6. Output from the tag library example.

Putting It All Together: Using the Tag Library in WebLogic

Now you have the Java class that will be used to implement the custom tag and the tag library descriptor (TLD) that will be used to describe the tag library to WebLogic. Deployment of the tag library is fairly straightforward as we will use the examples domain that is shipped with WebLogic 7.0. There are two methods for deploying a custom tag library.

The first method is to create files needed for the tag library in a directory underneath the Web application that will be using it. Say you have a Web application named firstWebApp . In the default installation of WebLogic 7.0, you need to create the directories where your code and the Web application will live. For this example, create it in the sample directory that comes with WLS.

For Unix, do the following:

 cd $WL_HOME/samples/server/config/examples/applications mkdir -p firstWebApp/WEB-INF/src 

For Windows, do this:

 cd %WL_HOME%\sample\server\config\examples\applications mkdir firstWebApp\WEB-INF\src 

Now create the TLD file in the WEB-INF directory. Its contents will be Listing 18.10. Name it datetag.tld . Next, create the Java source file that will hold the tag library implementation. In the example, you created the class in the jspexample package. This directory structure must also exist for the source code.

For Unix, do this:

 cd $WL_HOME/samples/server/config/examples/applications/firstWebApp/WEB-INF mkdir -p src/jspexample 

In Windows, do the following:

 cd %WL_HOME%\sample\server\config\examples\applications\firstWebApp\WEB-INF mkdir src\jspexamples 

In the src/jspexample directory, create the DateTag.java file. This code is shown in Listing 18.9.

To compile the Java source file into a Java class, do the following for Unix:

 cd $WL_HOME/samples/server/config/examples/applications/firstWebApp/WEB-INF mkdir classes javac -d classes -classpath $WL_HOME/server/lib/weblogic.jar src/jspexample/DateTag.java 

Do this in Windows:

 cd %WL_HOME%\sample\server\config\examples\applications\firstWebApp\WEB-INF mkdir classes javac -d classes -classpath %WL_HOME%\server\lib\weblogic.jar src\jspexample\DateTag.java 

Tip

The javac command for each operating system should be on one line. It is wrapped for readability.

Now you need to create a web.xml file that will be used for the Web application. The web.xml file is the deployment descriptor for the Web application; it describes the Web application to WebLogic Server. It is the same file that you use when configuring a servlet in a Web application. For the sample JSP tag, it will look like Listing 18.12.

Listing 18.12 web.xml

 <!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN" "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd"> <web-app> <display-name>My First custom JSP tag</display-name> <description> This is a simple Web application to display some dynamic content via a custom JSP tag. </description> <taglib> <taglib-uri>datetag.tld</taglib-uri> <taglib-location>WEB-INF/datetag.tld</taglib-location> </taglib> </web-app> 

The other method for creating a tag library is to create a Java JAR file that contains the tag library class and TLD file. To do this, you need to create a temporary directory structure. Create a directory named example that contains the following:

 example/ jspexample/ DateTag.class META-INF/ datetag.tld 

Then, from within the sample directory, run

 jar cvf dateTagLibrary.jar jspexample 

In the web.xml file for the Web application, modify the lines that reference the taglib as follows :

 <taglib> <taglib-uri>datetag.tld</taglib-uri> <taglib-location> /WEB-INF/lib/dateTagLibrary.jar </taglib-location> </taglib> 

Tag libraries are commonly put into a JAR file to simplify delivery. You can easily deploy the JAR file into a different WebLogic Server by simply copying the JAR file into the appropriate directory.