J2EE^TM Developer's Guide
Advanced Topics

Accessing Enterprise Beans Through JSP Tag Libraries

A tag library enables you to define new actions for a JSP page. For example, you can define an action that locates the home interface of an enterprise bean. The sections that follow show how to create such a tag library in a J2EE application named ConverterJSPApp. This application contains the following elements:

JSP File: Converter.jsp
Tag Library Descriptor File: taglib.tld
Tag Handler Class: EjbTag
TagExtraInfo Class: EjbExtraInfo
Session Bean: ConverterEJB

The ConverterEJB.java file is in the doc/guides/ejb/examples/converter directory. The other files are in the doc/guides/ejb/examples/jsptag directory.

Setting Up the ConverterJSPApp Application

Before creating the web component for the JSP page, you should perform these tasks:

Open the ConverterApp you created in the Getting Started chapter.
In the ConverterApp, save the ConverterBean component in a file named ConverterEJB.jar.
Create a J2EE application named ConverterJSPApp.
Add the ConverterEJB.jar file to the ConverterJSPApp application.

Writing the JSP File

This section briefly describes the JSP tags in the Converter.jsp file. These tags are marked by bold font in the full listing of Converter.jsp included at the end of this section. (For more information on writing JSP files, see the JavaServer Pages web site .)

The taglib directive is the first JSP tag in the Converter.jsp file. This directive identifies the tag library descriptor (taglib.tld) and defines the tag prefix (j2ee) that associates subsequent tags with the tag library:

<%@ taglib uri="taglib.tld" prefix="j2ee" %>

The tag library described in the taglib.tld file has just one tag, which is named ejb. The ejb tag has three attributes: jndiName, homeInterface, and homeVar. The ejb tag file assigns values to each attribute:

<j2ee:ejb
   jndiName="java:comp/env/ejb/MyConverter"
   homeInterface="ConverterHome"
   homeVar="converterHome">
   <% converter = converterHome.create(); %>
</j2ee:ejb>

The Converter.jsp file uses script elements in conjunction with the tag library. The first of these elements declares the Converter session bean:

<% Converter converter = null; %>

The next script element creates a new session bean:

<% converter = converterHome.create(); %>

The last two script elements invoke methods on the session bean, returning values which are displayed:

<%= converter.dollarToYen(100.00) %> 
<%= converter.yenToEuro(100.00) %>

The full listing for the Converter.jsp file follows:

<html>
<%@ taglib uri="taglib.tld" prefix="j2ee" %>

<head>
    <title>Converter JSP</title>
</head>

<h1><b><center>Converter JSP Example</center></b></h1>
<hr>


<% Converter converter = null; %>

<j2ee:ejb
   jndiName="java:comp/env/ejb/MyConverter" 
   homeInterface="ConverterHome"
   homeVar="converterHome">
   <% converter = converterHome.create(); %>
</j2ee:ejb>


<p>
dollarToYen:  <%= converter.dollarToYen(100.00) %> 
<p>
yenToEuro: <%= converter.yenToEuro(100.00) %> 

</html>

Writing the Tag Library Descriptor

A tag library descriptor is an XML file whose elements describe a particular tag library. A JSP container uses the tag library descriptor to interpret pages that include taglib directives. The taglib directive in the Converter.jsp page refers to the taglib.tld tag library descriptor:

<%@ taglib uri="taglib.tld" prefix="j2ee" %>

A listing of the taglib.tld file follows. The tag element defines the ejb action, including its three attributes (jndiName, homeInterface, and homeVar). The tagclass element defines the tag handler class (EjbTag). The teiclass element specifies the TagExtraInfo class (EjbExtraInfo).

<?xml version="1.0" encoding="ISO-8859-1" ?>
<!DOCTYPE taglib
        PUBLIC "-//Sun Microsystems, Inc.//DTD JSP Tag Library 1.1//EN"
      "http://java.sun.com/j2ee/dtds/web-jsptaglibrary_1_1.dtd">

<!-- a tab library descriptor -->

<taglib>
  <tlibversion>1.0</tlibversion>
  <jspversion>1.1</jspversion>
  <urn></urn>
  <info>
    Tag library for EJB support
  </info>

  <!-- ejb tag -->

  <tag>
    <name>ejb</name>
    <tagclass>EjbTag</tagclass>
    <teiclass>EjbExtraInfo</teiclass>
    <bodycontent>JSP</bodycontent>
    <info>
       Look up home interface and declare enterprise bean.
    </info>

    <attribute>
      <name>jndiName</name>
      <required>true</required>
      <rtexprvalue>true</rtexprvalue>
      <type>String</type>
    </attribute>
    <attribute>
      <name>homeInterface</name>
      <required>true</required>
    </attribute>
    <attribute>
      <name>homeVar</name>
      <required>true</required>
    </attribute>
  </tag>
</taglib>

Coding the Tag Handler Class

A tag handler is an object in the web container that helps evaluate actions when a JSP page executes. The EjbTag class, for example, is the tag handler for the ejb action. The doInitBody method of the EjbTag class sets the homeVar attribute to the reference returned by a JNDI lookup method:

public void doInitBody() throws JspException {
    try {
        System.out.println("doInitBody()");
        InitialContext ic = new InitialContext();
        Object homeRef = ic.lookup(jndiName);
        homeRef = PortableRemoteObject.narrow(homeRef, 
           Class.forName(homeInterface));
        pageContext.setAttribute(homeVar, homeRef);
    } catch (NamingException ex) {
        throw new JspTagException("Unable to lookup home: "+jndiName);
    } catch (ClassNotFoundException ex) {
        throw new JspTagException("Class "+homeInterface+" not found");
    }
}

Coding the TagExtraInfo Class

If a tag defines scripting variables or if it validates attributes during translation, then you must provide a TagExtraInfo class. A subclass of TagExtraInfo, the EjbExtraInfo class implements the getVariableInfo method. This method provides information about the homeVar and homeInterface attributes. The EjbExtraInfo class follows:

import javax.servlet.jsp.*;
import javax.servlet.jsp.tagext.*;

public class EjbExtraInfo extends TagExtraInfo {
   public VariableInfo[] getVariableInfo(TagData data) {
      return new VariableInfo[] 
             {
                 new VariableInfo(
                    (String)data.getAttribute("homeVar"),
                    (String)data.getAttribute("homeInterface"),
                    true,
                    VariableInfo.NESTED),
             };
   }

To compile the EjbTag and TagExtraInfo classes, change to the examples/jsptag directory and execute these commands:

UNIX:

CPATH=.:$J2EE_HOME/lib/j2ee.jar:ejb.jar
javac -classpath "$CPATH" *.java

Windows:

set CPATH=.;%J2EE_HOME%\lib\j2ee.jar;ejb.jar
javac -classpath %CPATH% *.java

Creating the Tag Library's .war File

To create a .war file, you run the New Web Component Wizard of the Application Deployment Tool. To start the wizard, from the File menu choose New Web Component. The wizard displays the following dialog boxes. (You may skip any dialog boxes not listed here.)

WAR File General Properties Dialog Box:

a. In the combo box labelled "Web Component Will Go In," select ConverterJSPApp.

b. In the WAR Display Name field, enter ConverterWAR.

c. Click Add.

d. In the Add Content Files dialog box, choose the examples/jsptag directory. You may either type the directory name in the Root Directory field or locate it by clicking Browse.

c. Select the Converter.jsp and taglib.tld files from the text area and click Add.

d. Click Next.

e. Choose the examples/jsptag directory again.

f. Select the EjbExtraInfo.class and EjbTag.class files from the text area and click Add.

g. Click Finish.

h. Click Next.

Choose Component Type Dialog Box:

a. Select JSP.

b. Click Next.

Component General Properties Dialog Box:

a. In the JSP Filename combo box, select Converter.jsp.

b. In the Web Component Display Name field, enter TheConverter.

c. Click Next.

Enterprise Bean References Dialog Box:

a. Click Add.

b. In the Coded Name column enter ejb/MyConverter.

c. In the Type column select Session.

d. In the Home column enter ConverterHome.

e. In the Remote column enter Converter.

f. Click Finish.

Specifying the Web Context Root

1. In the tree view select ConverterJSPApp.

2. In the Web Context tabbed pane, enter ConverterContextRoot in the ContextRoot column.

Specifying the JNDI Names

In the JNDI Names tabbed pane for the ConverterJSPApp, specify MyConverter as the JNDI name for both the ejb/Converter reference and the ConverterBean component.

Deploying the ConverterJSPApp Application

1. From the Tools menu, choose Deploy Application.

2. In the first dialog box, do not select the checkbox labelled "Return Client Jar."

3. In the second dialog box, verify the JNDI names.

4. In the third dialog box, verify the context root.

Running the ConverterJSPApp Application

To run Converter.jsp from your browser, specify the URL as follows, but replace <host> with the name of the machine that is running the J2EE server:

http://<host>:8000/ConverterContextRoot/Converter.jsp

Comparing the ConverterJSPApp and AccountJSPApp Applications

In the Clients chapter, the JavaServer Pages^TM Components section describes a J2EE application named AccountJSPApp. Unlike the ConverterJSPApp, the AccountJSPApp accesses an enterprise bean through a JavaBeans^TM component. This component mirrors the enterprise bean-- its state matches the enterprise bean's state. The ConverterJSPApp does not have to synchronize the state of an intermediary object with that of the enterprise bean. However, the JSP page of the ConverterJSPApp cannot maintain a state throughout a session. Every time a web client invokes the Converter.jsp file, all of the page's tags are executed. Because of this stateless nature, the approach taken by the ConverterJSPApp is not appropriate for an application that carries on a "conversation" with the end-user.

Prev | Next

TOC | Index