Oracle9iAS Containers for J2EE - Release 2

Date: Feb-27- 2003

How-To:  Tag Library Validation in OC4J (JSP 1.2 feature)

After completing this how-to you should be able to:

• Understand Tag Library Validation feature that is part of JSP 1.2 specification
• How to create and use a custom tag validator
• Code a simple custom tag validator class
• How to package and deploy the tag validator classes
  

A significant addition to JSP 1.2 specification is support for Tag Library Validation mechanism. The JSP Tag Library Validation mechanism provides a translation time or request time approach for enforcing constraints on usage of JSP tags. OC4J too supports this feature.

Some times the tag library implementor feels the need to constrain the way developer uses the provided tag library. Many times incorrect use of tag library may result in run time errors, though the JSP page has been compiled successfully. There are many reasons why such constraints are needed. Some of the reasons are given below:

• Attribute and value checking - In some cases a JSP tag must be used with certain attributes and with valid values.
• Ordering - In certain cases tags must be nested in a predefined order so that the inner tags have access to objects defined by the parent tags.
• Authoring-tool support - The tool may require an ordering in the usage of JSP tags.
• Methodological constraints - The tag library development group may want to constrain the way some features are used.

There are three components any developer must be aware of when he/she wants to write a Tag Library Validator. Tag Classes and Tag Library Validator classes are java classes that implement designated interfaces. These interfaces guarantee that these classes provide method implementation that can be used by the JSP container. Tag Library Descriptor, an XML file links the Tag classes and the Validator classes together.

Tag Library Descriptor: The Tag Library Descriptor contains the basic syntactic information. In particular, the attributes are described including their name, whether they are optional or mandatory, and whether they accept request-time expressions. Additionally the body-content element can be used to indicate that an action must be empty. All constraints described in the TLD must be enforced. A tag library author can assume that the tag handler instance corresponds to an action that satisfies all constraints indicated in the TLD.

Tag Classes : Tag classes are Java classes that are used to carry out actions defined by the tag library. Every tag defined in the tag library has a corresponding Tag class that is associated with the help of Tag Library Descriptor file. These classes define the actions that are executed when response is generated from a JSP page.

Tag Library Validator class: A Tag Library Validator class may be listed in the TLD for a tag library to request that a JSP page be validated. The XML view of a JSP page is exposed through a PageData class, and the validator class can do any checks the tag library author may have found appropriate. This way the library author has complete control over the way page is validated.

The illustration given below explains how one can use Tag Library Validation framework with OC4J. For this illustration let us take a simple scenario. In this scenario we have defined two tags "parent" and "child". Given below is the list of constraints that will be enforced by using a Tag Library Validator class:

1. "child" tag must be enclosed in parent tag
2. "parent" tag must have an attribute "age" with value between 1 to 100
3. Text contained in "child" node must not have a string "EXPERIMENT"
   

In order to implement this, we need to go through following steps:

Step 1: Create the tag handlers
Step 2: Create the Tag Library Validator class
Step 3: Define the Tag Library Descriptor file
Step 4: Write JSP's that use the tags
Step 5: Setting up and running the example

Create the tag handlers

In this how-to we will create 2 tags "parent" and "child". Given below is the definition of these classes.

Parent tag handler : TagParent.java
This tag handler defines the "parent" tag. This tag has two properties name and age. These properties are set by the container when the tag element and attributes are encountered in the JSP page.

Child tag : TagChild.java
This tag handler defines the "child" tag. This tag has one property name . This property is set by the container when tag element and attribute is encountered.

Create the Tag Library Validator Class

Tag Validator Class : Validator.java
The tag validator class has one important method validate. This method is called by the container when it encounters a tag that has an associated validator class definition in the Tag Library Descriptor file. PageData class is passed by the container as an argument to this method. PageData instance can be used to recreate the entire JSP XML view ( The XML representation of the translated JSP document). Once the XML document object is created normal DOM API's can be used to process and validate the XML document. Thus the Tag Library author has complete control over the way the JSP page is validated.

Define the Tag Library Descriptor

Tag Library Descriptor : howtotlv.tld

<?xml version = '1.0' encoding = 'windows-1252'?>
<!DOCTYPE taglib PUBLIC "-//Sun Microsystems, Inc.//DTD JSP Tag Library 1.2//EN"
 "http://java.sun.com/dtd/web-jsptaglibrary_1_2.dtd">

<taglib>
  <tlib-version>1.0</tlib-version>
  <jsp-version>1.2</jsp-version>
  <short-name>howtotlv</short-name>
  <uri>http://xmlns.oracle.com/j2ee/jsp/tld/demos/howtotlv.tld</uri>
  <description>
    This tag library descriptor uses a Validator class to enforce following rules
      1. "child" tag must be enclosed in parent tag
      2. "parent" tag must have an attribute "age" with value between 1 to 100 
      3. Text contained in "child" node must not have a string "EXPERIMENT"
  </description>
  <validator>
     <validator-class>howtotlv.Validator</validator-class>
  </validator>
  <tag>
    <name>parent</name>
	<tag-class>howtotlv.TagParent</tag-class>
    <body-content>JSP</body-content>
    <attribute>
      <name>name</name>
      <required>required</required>
      <rtexprvalue>false</rtexprvalue>
    </attribute>
    <attribute>
      <name>age</name>
 
     <required>false</required>
      <rtexprvalue>true</rtexprvalue>
    </attribute>
  </tag>
  <tag>
    <name>child</name>
    <tag-class>howtotlv.TagChild</tag-class>
    <body-content>JSP</body-content>
    <attribute>
      <name>name</name>
      <required>true</required>
      <rtexprvalue>true</rtexprvalue>
    </attribute>
  </tag>
</taglib>

Write JSP's that use the tags

Valid JSP page [Does not produce error ]: howtotlv.jsp

<%@ page language="java" %>
<%@ taglib prefix="demo" uri="howtotlv.tld" %>
<html>
  <body>
    <demo:parent name="Stella" age="32" >
      <demo:child name="Michael">
        Hello from the child tag!
      </demo:child>
    </demo:parent>
    Done!
  </body>
</html>

Invalid JSP page [Produces error ]: error2.jsp

<%@ page language="java" %>
<%@ taglib prefix="demo" uri="howtotlv.tld" %>
<html>
  <body>
    <demo:parent name="Stella" age="102" >
      <demo:child name="Michael">
        Hello from the EXPERIMENT child tag!
      </demo:child>
    </demo:parent>
    <br/>Done!
  </body>
</html>

Setting up and running the example on your OC4J installation

Prerequisites
Make sure that you have installed OC4J v9.0.3 or higher. Downloadable from OTN.

Notation: < OC4J_HOME> - The directory where OC4J is installed. If you installed OC4J under c:\ then <OC4J_HOME> would be c:\j2ee\home .

Un-packing this example:

Download the howtotlv.ear file into a convenient directory. You can deploy the sample application using instructions given below.

Deploying this example on OC4J

1. Make sure that you've installed OC4J v9.0.3 and it is running.
2. Download or copy howtotlv.ear to a convenient directory.
3. Open a command prompt window. ( On Unix or Linux open a shell )
4. Change the current directory in this command window to the directory where howtotlv.ear is placed.
5. On command prompt execute following command :
   java -jar <OC4J_HOME>\j2ee\home\admin.jar ormi://localhost:23791 admin welcome -deploy -file howtotlv.ear -deploymentName howtotlv
   For example,
   java -jar C:\OC4J\j2ee\home\admin.jar ormi://localhost:23791 admin welcome -deploy -file howtotlv.ear -deploymentName howtotlv
6. On command prompt execute following command :
   java -jar <OC4J_HOME>\j2ee\home\admin.jar ormi://localhost:23791 admin welcome -bindWebApp howtotlv howtotlv-web http-web-site /howtotlv
   For example,
   java -jar C:\OC4J\j2ee\home\admin.jar ormi://localhost:23791 admin welcome -bindWebApp howtotlv howtotlv-web http-web-site /howtotlv
   
7. To run the examples visit the url http://<hostname>:<port>/howtotlv/
where,

• hostname is the name of the host where this application is deployed.
• portno is the port number where OC4J is listening.

Deploying this example on Oracle9i Application Server

To deploy this application on Oracle9i Aplication Server use instructions given in Oracle9iASinstall.html

Note: If you are using Microsoft Internet Explorer to view the pages then make sure that the browser is set to display full error message text. To do this,
1. Click on tools menu
2. Select Internet Options
3. In the dialog box that pops up select Advanced Tab
4. Go to the Browsing Category shown in the scrollable window
5. Make sure that "Show friendly HTTP error messages" is deselected 

Summary

By reading and following the steps given this document, you should have learnt:

• The tag validation support feature provided by JSP 1.2 specification
• How to implement a custom tag validator
• Packaging and deployment of custom tag validator in OC4J

References

• How-to: Implementing Custom Tag Libraries in Oracle9iAS Containers for J2EE 

Please enter your comments about this How-To in the OTN Sample Code Discussion Forum.