Accessibility
Icon or Spacer
   

Getting Started with JRun Server Tags

By Randy Nielsen
JRun Documentation Group Leader
Macromedia, Inc.

JRun Server Tags (JST) is a technology introduced in Macromedia JRun Server version 3.1 that you can use to implement custom tag handlers in JSP. Custom tag handlers are called when a JSP page invokes the associated custom tag. JST technology uses JSP syntax to bring the power of custom tags to the JSP programmer. JSTs shorten the development cycle, allowing you to develop applications more quickly than with custom tags written in Java. Any JSP page can be used as a custom tag, although you typically use the .jst extension to indicate that a page is a JRun server tag.

Note 1: Custom tags written in JSP are a JRun extension to the custom tag support defined in the JSP specification. Originally defined in the JSP 1.1 specification, custom tag handlers are written in Java and require that you implement one or more supporting methods along with a TLD file, which is an XML-format text file that helps to define a tag's functionality and usage. For more information on custom tags written in Java, refer to Chapter 22 of the Developing Applications with JRun manual and to the following JRun DevCenter articles:

Note 2: Our goal is to establish JST as a portable technology so that all members of the J2EE community can leverage its benefits. Macromedia is currently investigating the steps required to use JST on other application servers. These results will be published as soon as they are available. In addition, members of the JRun team are working with other developers and application server vendors to craft a specification, which would ensure compatibility across J2EE deployment platforms.

The goal of this article is to teach basic JST concepts to JSP developers; sample code has been simplified whenever possible. You can, however, use the full suite of JSP capabilities in a JST, including scriptlets, JavaBeans, and calls to other custom tags. For more complex examples, refer to Chapter 11 of the Developing Applications with JRun manual.

This article presents three scenarios to help you get started with JST technology. Each scenario includes a JST file, a JSP page that calls it, and sample output. You will find the scenarios below, following an introduction to JST technology from two familiar perspectives.

JST from a Servlet Perspective

At first, server-side Java was limited to servlets. Eventually, however, leading-edge innovators, such as Live Software, developed JavaServer Pages as a way to hide servlet complexity and offer the power of server-side Java to a wider audience of developers. Behind the scenes, these products dynamically transformed JSP pages into Java servlets, compiled them, and executed them, returning HTML to the browser.

JST technology uses a similar level of abstraction. Behind the scenes, JRun transforms the JST into a custom tag handler class, compiles it, and creates a TLD file dynamically.

JST from a ColdFusion Perspective

Early versions of ColdFusion included a C++ API that advanced developers used to write custom tags, which CFML developers could then call from a .cfm page. Later versions of ColdFusion supported custom tags written in CFML, thus enabling less experienced developers to code custom tags.

In the JSP world, the JSP 1.1 specification defines a framework for Java programmers to write custom tag handlers, which JSP developers can call from a .jsp page. JSTs allow JSP developers to write custom tags; Java experience is not required.

Getting Started: A Simple Example

The first example helps you understand the following:

  • Where to store the JST file.
  • How to code the taglib directive in the JSP.

To test this example, the JRun default server must be running and the demo web application must be installed (when you install JRun, the demo web application is installed by default).

JST File

Code the following file and save it as verysimple.jst in the JRun_rootdir/servers/default/demo-app directory: 

<%-- verysimple.jst --%>
<p>This paragraph came from the JRun Server Tag!</p>

When this file is invoked (shown in the JSP file, below), JRun transforms the page into a custom tag handler class, compiles it, and creates an associated TLD file.

JSP File

Code the following file and save it as firstcaller.jsp in the JRun_rootdir/servers/default/demo-app directory: 

<%-- firstcaller.jsp --%>
<%-- The uri attribute points to the directory that contains
      the JST file. The / points to the web application root. --%>
<%@ taglib prefix="mytag" uri="/" %>
<html>
<head>
  <title>Using a Very Simple JST</title>
</head>

<body>
<h1>Using a Very Simple JST</h1>
<p> This text comes from the JSP page.
<mytag:verysimple/>

</body>
</html>

Result

When you display http://localhost:8100/demo/firstcaller.jsp in a browser, you should see something similar to the following:

After you view the page, take a look in the JRun_rootdir/servers/default/default-app/WEB-INF/jsp directory (assumes you're running the JRun default server) and review the .java file and .tld file that were generated for your JST file.

Passing Attributes: Another Simple Example

Clearly, the first example provides no value added over the include directive or the jsp:include action. However, another simple use of JST is to call a tag while passing it one or more attributes. Attribute passing is not supported by the include directive and is only supported in the jsp:include action through separately coded jsp:param elements, which are not as easy to use as tag attributes.

The second example helps you understand the following:

  • How to access attributes in the JST file.
  • How to pass attributes when coding the tag in a JSP page.

JST File

Code the following file and save it as attrtag.jst in the JRun_rootdir/servers/default/demo-app directory:

<%-- attrtag.jst --%>
<%-- First, code a tagattribute directive to define and validate
     the attribute.--%>

<%-- The tagAttribute directive includes the following attributes:
     * name - Serves two purposes. This is the value the caller must use
              when invoking the tag. Also, this is the name you use
              to access the attribute within the JST.
     * type - Data type of the passed attribute
     * required - Indicates whether the caller is required to
                  pass the attribute. Specify true or false.
     * rtexpr - Indicates whether the caller can pass a runtime expression.
                Specify true or false.
     * default - Specifies a default value. Used when required="false"
    --%>
<%@ tagAttribute name="productname" type="String" required="true"
rtexpr="true"%>

<%-- Use the attribute as a variable in the JST file. --%>
<h1>Welcome to <%= productname %></h1>
<p>We hope you enjoy your visit to <%= productname %>.</p>
<p>Please let us know if we can help in any way.</p>

JSP File

Code the following file and save it as attrcaller.jsp in the JRun_rootdir/servers/default/demo-app directory:

<%-- attrcaller.jsp --%>
<%-- The uri attribute points to the directory that contains
     the JST file. The / points to the web application root. --%>
<%@ taglib prefix="mytag" uri="/" %>
<html>
<head>
   <title>Passing Attributes to a JST</title>
</head>

<body>
<%-- Imagine that this is a reusable welcome screen. --%>
<mytag:attrtag productname="Nirvana"/>

</body>
</html>

Result

When you display http://localhost:8100/demo/attrcaller.jsp in a browser, you should see something similar to the following:

After you view the page, take a look in the JRun_rootdir/servers/default/default-app/WEB-INF/jsp directory (assumes you're running the JRun default server) and review the .java file and .tld file that were generated for your JST file.

Third Scenario

The previous scenario shows how to pass a simple value to the custom tag. However, you can pass any type of object to the custom tag. The third example shows you how to use scriptlets and expressions in a JST.

JST File

Code the following file and save it as paramtag.jst in the JRun_rootdir/servers/default/demo-app directory:

<%-- paramtag.jst --%>
<%-- First, code a tagattribute directive to define and validate
     the attribute. --%>
<%@ tagAttribute name="params" type="java.util.Enumeration" required="true"
rtexpr="true"%>

<%-- This tag displays a table of request parameters and values.
     Can be used for simple debugging. --%>
<h2>Parameters passed to this page</h2>
<table>
  <tr>
    <th>Parameter</th>
    <th>Value</th>
  </tr>
  <% // First see if it's empty
     if(!params.hasMoreElements()) { %>
       <tr>
         <td><b>No Parameters</b></td>
      </tr>
  <% } // end if statement
     // Loop through the Parameters
     while(params.hasMoreElements()) { %>
       <tr>
         <td>
           <% String thisParam = (String)params.nextElement(); %>
           <b><%= thisParam %></b>
         </td>
         <td>
           <%= request.getParameter(thisParam) %>
         </td>
       </tr> 
  <% } // end while loop %>
</table>

JSP File

Code the following file and save it as paramcaller.jsp in the JRun_rootdir/servers/default/demo-app directory:

<%-- paramcaller.jsp --%>
<%-- The uri attribute points to the directory that contains
the JST file. The / points to the Web application root. --%>
<%@ taglib prefix="mytag" uri="/" %>
<html>
<head>
<title>Display Parameters and Values</title>
</head>

<body>
<h1>Display Parameters and Values</h1>
<%-- You might use this tag for debugging. --%>
<mytag:paramtag params="<%= request.getParameterNames() %>"/>
	
</body>
</html>

Result

When you display http://localhost:8100/demo/paramcaller.jsp in a browser, you should see something similar to the following (note that this example passes parameters through the URL):


Moving On

The previous example is immediately useful to a JSP developer who needs to display a list of passed parameters. However, depending on your needs and experience level, this example can be enhanced in either of the following ways:

  • Ease of use - If you want to make the tag even easier to call, remove the attribute from the JSP page and add the request.getParameterNames() call to the JST file. That is, the JSP call now looks something like this:

    <mytag:paramtag />

    The JST file no longer requires a tagAttribute directive and contains added logic to access the request parameters:

    ...
<% // Get the request parameters
   java.util.Enumeration params = request.getParameterNames();
   // First see if it's empty
     if(!params.hasMoreElements()) { %>
...
    The result is a tag that is very easy to call but can only be used to display request parameters.
  • Flexibility - If you want to make the tag more flexible, modify the tag name, parameter names, and supporting text to make it clear that the tag accepts any type of Enumeration. For example, you might change the tag name to enumtag, the attribute name to enum, and replace the word parameter with the word element in the text displayed by the JST file.
  • Power - One final enhancement might be to determine the object type of each element retrieved from the Enumeration and perform more complex processing for certain object types.

    The result is a tag that is quite flexible but requires more Java experience to maintain.

As you can see, once you've learned the basics of JST, you can use these tags to enhance and simplify your JRun JSP applications. And what's really interesting is that this is just the beginning! JST includes support for a wide variety of powerful features, including the following:

  • Invoking the JST with the start tag or the end tag
  • Interacting with body content
  • Looping
  • Scripting variables
  • Custom accessor methods for tag attributes
  • Implementing multiple tag handler methods through scriptlets

These capabilities allow you to access the full range of custom tag functionality through JSP syntax. For more information, refer to Chapter 11 of the Developing Applications with JRun manual.