(*) Tag File
Store the tag files in /WEB-INF/tags folder.
The name of the tag file will become the tag name. (Header.tag ==> Header will be the name of the tag in JSP)

JSP usage

<%@taglib prefix="mytags" tagdir="/WEB-INF/tags" %>

• note that the tagdir attribute used instead of uri attribute
• tagdir value is the folder where the tag files are located

<mytags:Header subtitle="Welcome" />

• Header was the name of the file. (Header.tag)

Header.tag

<em><strong>${subtitle}</strong></em>

* The difference from <jsp:include> or <c:import> is that they use parameter to pass down the variables and they will exist in the JSP after include is comleted. But with Tag file, the attribute variable will not be available after the call.

* Tag files do not require to be defined in TLD file. Instead we use new directive in the tag file to define various information

<%@ attribute  name="subtitle" required="true" rtexprvalue="true" %>

Since subtitle is required, if the attribute subtitle is not used within the tag used in the JSP, you will get exception.

*If you want to use body with the Tag File,
JSP page

<mytags:Header>This is a body</mytags/Header>

Header.tag

<em><strong><jsp:doBody/></strong></em>

Additional tag for TAG files

<%@tag body-content="scriptless" %>

By default, the body-content is “scriptless” if tag directive not defined. In TAG FILE, scriplets are not allowed within BODY , so JSP for body-content not allowed.

Searching for the tag files (order)

1. /WEB-INF/tags
2. /WEB-INF/tags’ subfolder
3. /META-INF/tags of Jar file in the /WEB-INF/lib
4. /META-INF/tags’ subfolder of Jar file in the /WEB-INF/lib

* If tag file is deployed in a Jar, there must be TLD file for the tag files. See below example for such case.

<taglib …>
	<tlib-version>1.0</tlib-version>
	<uri>myLib</uri>
	<tag-file>
		<name>Header</name>
		<path>/META-INF/tags/Header.tag</path>
	</tag-file>
</taglib>

* Scriptlet & EL implicit objects can be used in tag file except ServletContext. Instead JspContext is used.

(*) Tag Handlers

Simple (new) & Classic (old before 2.0)

Simple Tag Handler

1. Write Class extends SimpleTagSupport
2. override doTag() method
3. create TLD file

   <tag>
   	<description>Testing simple tag</description>
   	<name>SimpleTest</name>
   	<tag-class>com.example.tag.TestSimpleTag</tag-class>
   	<body-content>empty</body-content>
   </tag>

4. Deploy tag handlers TLD & class in /WEB-INF/file.tld
5. Write JSP using the tag

   <%@ taglib prefix="mytag" uri="…" %>
   <mytag:SimpleTest />

* Processing Body example

Public void doTag() throws JspException, IOException {
	getJspBody().invoke(null) ; 
	// This will evaluate the body & print output to the response output. (when arg is null)
}

* Simple Tag handler Processing steps

1. Load Class
2. Instantiate class (no-arg constructor runs)
3. Calls setJspContext(JspContext)
4. If tag is nested, call the setParent(JspTag)
5. If tag has attributes , call attributes bean setters.
6. If Body exists & is not empty, setJspBody(JspFragment) is called
7. Call the doTag()

Example
Jsp Tag invocation

<table>
	<myTags:simple movieList="${movieCollection}" >
		<tr><td>${movie.name}</td><td>${movie.genre}</td></tr>
	</myTags:simple>
</table>

The Tag handler class

Public class SimpleTagTest extends SimpleTagSupport {
	private List movieList;
	public void setMovieList(List movieList) {
		this.movieList = movieList;
	}
	Public void doTag() throws JspException, IOException {
		Iterator I = movieList.iterator();
		While(i.hasNext()){
			Movie movie = (Movie) i.next();
			getJspContext().setAttributes("movie", movie);
			getJspBody.invoke(null);
		}
	}
}

The TLD

<tag>
	<description>takes an attribute and iterates over body</description>
	<name>simple</name>
	<tag-class>com.example.tag.SimpleTagTest</tag-class>
	<body-content>scriptless</body-content>
	<attribute>
		<name>movieList</name>
		<required>true</required>
		<rtexprvalue>true</rtexprvalue>
	</attribute>
</tag>

JspFragment is an object represents JSP code (JspFragment jf = getJspBody(); )
Body of tag is encapsulated in JspFragment & then sent to the tag handler in the setJspBody(). No Scriptlets are allowed in body of tag for Simple Tag.

*JspFragment.invoid(java.io.writer) : use null as arg to send output to response otherwise create a write object & pass it. Work with write to access the body.

If doTag() throws SkipPageException, all the contents will be shown right before Exception. But the rest of the page will not be shown. (Stop processing) If JspException occurs , error page will be shown.

(*) Classic Handler

Create a classic handler by extending TagSupport or BodyTagSupport.

The order that BodyTag is extended / implemented parents classes.
JspTag interface <== Tag interface <== IterationTag interface (doAfterBody() belongs here ) <== BodyTag interface (doInitBody(), setBodyContent(BodyContent) belong this interface)

TagSupport implement IterationTag interface.
BodyTagSupport implement BodyTag interface.

public int doStartTag() throws JspException (Note that no IOException)

• Return SKIP_BODY ==> No Body Process
• Return EVAL_BODY_INCLUDE ==> Body process ==> call doAfterBody()

public int doEndTag() throws JspException

• Return EVAL_PAGE ==> cdontinue with the rest of page
• Return SKIP_PAGE ==> same as SkipPageException.

LifeCycle

1. Load class
2. Instantiate class (call no-arg constructor)
3. Call setPageContext(Pagecontext)
4. If tag nested, call setParent(Tag)
5. If tag has attributes, call attributes setters
6. Call doStartTag()
7. If doStartTag returns EVAL_BODY_INCLUDE , the body is evaluated.
8. doAfterBody() is called after body is evaluated
9. doEndTag()

public int doAfterBody() throws JspException

• Return SKIP_BODY ==> goto doEndTag()
• Return EVAL_BODY_AGAIN ==> eval body again ==> doAfterBody called again

Default Return Values of the methods if not overridden:

• doStartTag ==> SKIP_BODY
• doAfterBody ==> SKIP_BODY
• doEndTag ==> EVAL_PAGE

Classic handler object is reused unlike simple handler.

* Dynamic Attribute Interface
To pass down bunch of attributes to that are not actually used in the TAG class. Just like HTML default attributes.

Implement DynamicAttributes interface

public void setDynamicAttribute(String uri,String name, Object value) {
	hashmap.put_(name, value);
}

TLD for Dynamic Attribute

<tag>
	<name>…</name><tag-class>…</tag-class><body-content>empty</body-content>
	<attribute> 
<name> …</name><type>…</type>
<required></required><rtexprvalue></rtexprvalue>
</attribute>
	<dynamic-attributes>true</dynamic-attributes>
</tab>

In case of TAG FILES

<%@ tag body-content="empty" dynamic-attributes="tagAttrs" %>

BodyTagSupport Class : This is just to work with the actual body content.
There is one more return value for the doStartTag() : EVAL_BODY_BUFFERED (default return for the BodyTagSupport class).
When EVAL_BODY_BUFFERED is returned, setBodyContent() & doInitBody() called before evaluate the body.

Nesting Tags : How to access parent tag? ==> using getParent()

//Getting top most tag handler
Tag parent = getParent();
While (parent != null) {
	parent = parent.getParent();
	nestLevel++;
}

Using getParent(), a classic can access only classic tag parents, and a simple tag can access either a classic or simple parent.

If you want to access child from the parent: there is no predefined method. You will need to create custom method for the parent Tag class & call it from the child Tag class by getting getParent and call the method. Store child data to parent class using the method.

findAncestorWithClass(Tag,class of ancestor Tag you want to search)
This searches Tag parent until the class matches. This function does not belong to interface but to final classes (SimpleTagSupport, TagSupport, BodyTagSupport)

<%@ attribute name="extra" fragment="true" %>
<jsp:invoke fragment='extra'>

<jsp:invoke > ==> just like processing tag body but attribute fragment ?? Need to check further.

Also SimpleTagSupport & TAG FILE do not support 'JSP' type for <body-content>. But with classic handler TagSupport & BodyTagSupport, 'JSP' can be used for <body-content>

(*) Next: [SCWCD] Cram Sheet 8 - Web Deployment and Security

JSTL is not part of JSP 2.0 spec. (jstl.jar & standard.jar copy needed)

(*) <c:out>

<c:out value='${pageContent.currentTip}' escapeXml="true" default="No tip" />

• escapeXML: when true, escapes HTML special characters (<,>,&,’,”) and default value is true.
• default: attribute is to show default value when the value attribute data is null. Or default value can be defined in the body.

(*) <c:forEach>

<c:forEach var="movie" items="${movieList}" varStatus="info">
	<tr><td>${info.count}</td><td>${movie}</td></tr>
</c:forEach>

• Items: array, collection, map, comma delimited string
• varStatus: extra object that you can get count information.
• <c:forEach> can be nested.

(*) <c:if>

<c:if test="${userType eq 'member'}" >
	<jsp:include page="input.jsp" />
</c:if>

(*) <c:choose>, <c:when>, <c:otherwise>

<c:choose>
	<c:when test="${userPref == 'performance'}" >
		…
	</c:when>
	<c:when test="${userpref == 'safety'}" >
		…
	</c:when>
	<c:otherwise> … </c:otherwise>  
 
</c:choose>

<c:otherwise> is not a mandatory item within <c:choose>

(*) <c:set >

1. Setting attribute variable ‘var’

   <c:set var="userlevel" scope="session" value="admin" />

   When the attribute ‘userlevel’ does not exist, it will create one within the session scope only if value is not null.

   • Scope : it is optional. Default is page scope
   • Value : it may not be string. It can be object defined using EL ${object}

   <c:set var="userlevel" scope="session">admin</c:set>
   *Using data in the body as the value when body is used.

   *If value is null, the var is removed even if it was previously defined!

2. using ‘target’ Setting target for Map and Bean object. (Not for array and list)

   <c:set target="${PetMap}" property="dogName" value="Clover" />

   If the target expression is null, container throws exception.
   Target should be the actual object. So do no use ID names(string) but EL expression to reference real object.
   Even if target object exists, but propery name does not, Exception will be thrown.

(*) <c:remove>

<c:remove var="userStatus" scope="request" />

The var must be string , can’t be an expression.
If scope not defined, the named attribute is removed from all scopes.

(*) <c:import>

<c:import url=http://www.yahoo.com/index.html />

This tag can import outside url page. <c:import> support local and remote file.

It is similar to <jsp:import> & <jsp:param> . But <jsp:import> supports only local file.

<c:import url="include.jsp" >
	<c:param name="subtitle" value="This is subtitle" />
</c:import>

If the URL is local resource , the <c:param> will be available as local variable in the local resource.
If the URL is remote website, the <c:param> value will be passed as query string.

(*) <c:redirect>

<c:redirect url=http://www.yahoo.com" >
	<c:param name="query_name" value="query_value" />
</c:redirect>

Same as reponse.sendRedirect(”…”); Client Redirect.

(*) <c:url>

<c:url value="/output.jsp"  var="tempUrl" />

Just like encodeURL(), this element adds jsessionid to the URL if cookie is disabled.
The actual url is stored into Var name and it is used to refer to the actual URL at the bottom of jsp page.

<c:url value="/test.jsp" >
	<c:param name="firstname" value="${first}" />
	<c:param name="lastname" value="${last}" />
</c:url>

In order to encode the query string, you need to use <c:param> on each name and value pair. (not like encodeURL())

(*) Error page

<%@ page isErrorPage ="true" > says this page is only used to show when error occurs. This makes exception implicit object available (scriplet ==> exception object , EL ==> ${pageContext.exception} )
<%@ page errorPage =”errorPage.jsp”> If error occurs in this JSP page, forward to the error page.

DD

<error-page>
	<exception-type>java.lang.Throwable</exception-type> <!-- Throwable catch means to catch all exception-->
	<location>/errorPage.jsp</location>
</error-page>
<error-page>
	<error-code>404</error-code>
	<location>/404page.jsp</location>
</error-page>

You can make the exception an attribute with in the same JSP page

<c:catch var="myException">
	Inside the catch…
	<% int x= 10/0 ; %>
</c:catch>
<c:if test="${myException} != null" >
	There was an exception: ${myException.message} <br>
</c:if>

(*) Custom Tag Library

TLD FILE: /WEB-INF/anyname.tld (the file extension must be tld)

<?xml version="1.0" encoding="ISO-8859-1" ?>
<taglib xmlns="http://java.sun.com/xml/ns/j2ee" 
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
	xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee/web-jsptaglibrary_2_0.xsd" version="2.0">
	<tlib-version>1.2</tlib-version>  <!--mandatory-->
	<short-name>MyTagTests</short-name> <!--mandatory-->
<uri>MyTagTests</uri>  <!--mandatory-->
	<tag>
		<description>Simple Test</description> <!-- optional -->
		<name>SimpleTest</name> <!-- require -->
		<tag-class>com.example.web.tag.TestSimpleTag</tag-class> <!-- Required -->
		<body-content>scriptless</body-content> <!-- required! -->
		<attribute>  <!-- attribute tag is required for each attribute needed -->
			<name>arg1</name>			
			<required>true</required>
			<rtexprvalue>true</rtexprvalue>
		</attribute>		
</tag>	
</taglib>

JSP FILE: /tagusing.jsp

<%@ taglib prefix="mytag" uri="MyTagTests" %>

The uri should be the actual tld file path (/WEB-INF/anyname.tld) or the <uri> element name from the tld file.

<mytag:SimpleTest arg1="${value}" >
	Here is the body
</mytag:SimpleTest>

• using the prefix defined in the taglib.
• Attribute name is defined in the <attribute> . If <required> is true and you didn’t use the attribute , you get Exception.
• Body is used since <body-content> is not empty. If <body-content> is empty but body exists, you get Exception.

Actual tag class java source (simple tag): /WEB-INF/classes/com/example/web/tag/TestSimpleTag.class

package com.example.web.tag;
import javax.servlet.jsp.JspException;
import javax.servlet.jsp.tagext.SimpleTagSupport;
import java.io.IOException;
 
public class TestSimpleTag extends SimpleTagSupport {
    private String arg1;
 
    @override
    public void doTag() throws JspException, IOException { //must be overriden
        // Write something to output
        String result="Body is empty";
        JspFragment jf = getJspBody();
        if (jf != null ){
            jf.invoke(null); // evaluating the tag body
            result="Body is not empty!";
        }
        getJspContext().getOut().println("<br>ARG: "+this.arg1 + "<br>" + result);	
    }
 
    public void setArg1(String arg){  //Create a setter method for each Attribute
        this.arg1=arg;
    }
}

* Tag file <rtexprvalue> true ==> means OK to use both EL and scripting Expression.
The default value is false for <rtexprvalue>. When you use EL when <rtexprvalue>=false, you get exception.

Below three tags are all the same.

<mytag:SimpleTest arg1="${name}" />
<mytag:SimpleTest arg1="<%=request.getAttribute("name")%>" />
<mytag:SimpleTest >
	<jsp:attribute name="arg1">${name}</jsp:attribute>
</mytag:SimpleTest>

<jsp:attribute> can be used inside of tag body for tag’s each attribute.

*Values for <body-content>

• empty: tag must not have body
• scriptless: no scriptlets allowed, but EL, customs and standard tags are OK.
• tagdependent: body treated as plain text
• JSP : All is allowed

* <uri> is just a name , not a location!

* You had to define taglib in the OLD DD specification

<taglib>
	<taglib-uri>MyTagTests</taglib-uri>
	<taglib-location>/WEB-INF/anyname.tld</taglib-location>
</taglib>

* You can’t use below prefix in taglib directive : jsp, jspx, java, javax, servlet, sun, sunw

(*) Next: [SCWCD] Cram Sheet 7 – Custom Tag Development