<taglib:tutorial lesson="6"/>

In this lesson, we will look at how we can use a custom Tag to access environment entries set for our web-application.

Lesson 6, Accessing environment entries
Creating the Tag
Creating the TEI class
Update the Tag Library Descriptor
Adding a environment entry to your Web-module
Presenting your Tag
Using your new Tag

1 Lesson 6, Accessing environment entries

In this lesson, we will look at how we can use a custom Tag to access environment entries set for our web-application. We will do this by using the InitialContext to lookup an entry specified in a parameter to the Tag.

Figure 1: The InitialContext class

Explaining the InitialContext or the Context class is outside the scope of this tutorial. It might be added in the future, but for now you should consult the JNDI 1.1 specification for more details. For now, lets just say that we will use the InitialContext's lookup() method to retrieve environment entries specified in our web-application descriptor (web.xml). These entries can be of the type Boolean, Byte, Double, Float, Integer, Long, Short or String.

Our Tag will extend the TagSupport class in order to take advantage of the methods defined in that class. We will also add a TEI class so that our Tag adds a scripting variable to the Page scope. As the TEI we wrote for the Iterate Tag was NESTED (that is, the scripting variable was only available in the body of the Tag), we have to write a new one.

Throughout this lesson, We will continue to use the setup previously defined for this tutorial. You should feel comfortable about the Tag interface and the TagSupport class before starting on this lesson.

2 Creating the Tag

We will now create the Tag that will give us the lookup functionality that we want. The EnvEntry Tag will extend the TagSupport class like shown in the image below.

Figure 2: The GetEnvEntryTag class extends the TagSupport class

As you can see, we only have to add two new methods and then override the doEndTag() method of the TagSupport class in order to get the functionality we want.

In the '/WEB-INF/classes/com/acme/tag/' directory, create a new class called 'GetEnvEntryTag.java' with the following content:
package com.acme.tag;

import javax.servlet.jsp.*;
import javax.servlet.jsp.tagext.*;
import javax.naming.*;
Listing 1: Adding include directives
In the code above, we import javax.naming.* to get the naming and directory functionality (JNDI) needed

Continue with the following:

public class GetEnvEntryTag extends TagSupport
{
private String name;
private String type;

Listing 2: Adding a class declaration

Add a constructor:

public GetEnvEntryTag()
{
super();
}

Listing 3: Adding a constructor

Continue with the following method:
public void setName(String name)
{
this.name=name;
}
Listing 4: Implementing the setName() method
The setName(String name) method above will be used by the Container to set the parameter name which we will use to lookup the environment entry.
Continue with the following:
public void setType(String type)
{
this.type=type;
}
Listing 5: Implementing the setType() method
The Container will use the method above to set the parameter type, which we will use to later in our TEI to specify the object type of the environment entry.

End this class with the following:

public int doEndTag() throws javax.servlet.jsp.JspException
{
try
{
InitialContext context=new InitialContext();
Object obj=(Object)context.lookup("java:comp/env/"+name);
pageContext.setAttribute(name,obj,PageContext.PAGE_SCOPE);
}
catch(javax.naming.NamingException ne)
{
throw new JspException(ne.getMessage());
}
return EVAL_PAGE;
}
}

Listing 6: Overriding the doEndTag() method

The method above will be called at the end of our Tag. It will use the InitialContext to lookup the specified environment entry and add it to the Page scope. If the environment entry specified can not be found a javax.naming.NamingException is thrown. We catch this exception and throw it on as a JspTagException.

By now, your GetEnvEntryTag.java should look like this. Store the sourcecode in the /WEB-INF/classes/com/acme/tag/ directory as GetEnvEntryTag.java

Compile the Tag.

3 Creating the TEI class

Now lets create the TEI class that we will couple our new Tag with.

Figure 3: The GetEnvEntryTEI class.

As with the TEI of the previous lesson, we don't need to do any special validation of the Tag data, so we will just override the getVariableInfo() method of the TagExtraInfo class and add a constructor.

In the '/WEB-INF/classes/com/acme/tag/' directory, create a new class called 'GetEnvEntryTEI.java' with the following content:

package com.acme.tag;

import javax.servlet.jsp.tagext.*;

public class GetEnvEntryTEI extends TagExtraInfo
{
public GetEnvEntryTEI()
{
super();
}

public VariableInfo[] getVariableInfo(TagData data)
{
return new VariableInfo[]
{
new VariableInfo
(
data.getAttributeString("name"),
data.getAttributeString("type"),
true,
VariableInfo.AT_END
),
};
}
}

Listing 7: The GetEnvEntryTEI source.

Above, we use the TagData object to retrieve the value of the name and type parameters that was passed into the GetEnvEntryTag. We also tell the Container to treat the added variable as if it was a new variable, and that the variable should be available from the end of the Tag to the end of the page.

By now, your GetEnvEntryTEI.java should look like this. Store the sourcecode in the /WEB-INF/classes/com/acme/tag/ directory as GetEnvEntryTEI.java .

Compile the TEI class.

4 Update the Tag Library Descriptor

We should now describe our new Tag together with its TEI in the previously created Tag library descriptor.

Open your 'taglib.tld' from your '/WEB-INF/' directory with your favourite editor.

Add the following description for your new Tag and its TEI:

<tag>
<name>envEntry</name>
<tagclass>com.acme.tag.GetEnvEntryTag</tagclass>
<teiclass>com.acme.tag.GetEnvEntryTEI</teiclass>
<bodycontent>empty</bodycontent>
<info>Reads a environment entry</info>
<attribute>
<name>name</name>
<required>true</required>
</attribute>
<attribute>
<name>type</name>
<required>true</required>
</attribute>
</tag>

Listing 8: The descriptor entries for the Tag and the TEI.

Your taglib.tld should now look like this. Store the descriptor in the /WEB-INF/ directory as taglib.tld.

5 Adding a environment entry to your Web-module

In order to use your new Tag, you will need to add a environment entry to your Web-module.

Open the 'web.xml' file found in the '/WEB-INF/' directory of your web-application.

Add the following lines right before the last line of the file:

<env-entry>
<description>A test value</description>
<env-entry-name>test</env-entry-name>
<env-entry-value>HelloWorld</env-entry-value>
<env-entry-type>java.lang.String</env-entry-type>
</env-entry>

Listing 9: The environment entry descriptor entry.

This will add a String with the name of test to the java:comp/env/ context.

Save your web.xml.

By now, your web.xml should look something like this.

6 Presenting your Tag

In order to test your Tag, you will need a JSP page that uses it.

Create a file called envEntry.jsp and add the following lines:

<%@ taglib uri="mytags" prefix="mt" %>
<HTML>
<HEAD>
<TITLE>Env-Entry reader</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<mt:envEntry name="test" type="java.lang.String"/>
<P>The value of the environment entry 'test' is <%=test%>.</P>
</BODY>
</HTML>

Listing 10: A sample JSP page

The code above will print out the value of the environment entry named test.

As you can see, the Tag (with the help of our TEI class) adds the environment entry class to the page scope so that it's accessible from the end of our Tag.

If you've typed in this correctly, your envEntry.jsp should look like this.

7 Using your new Tag

We are now ready to use our Tag.

Open the URL http://localhost/taglib/envEntry.jsp in a normal web browser. Hopefully the result looks like this.

Continue with lesson 7, "Accessing resource references".