Disclaimer: This is old information. But I still often talk to Java or JSP developers who were not aware of this feature, even though it was introduced in JSP 2.x, many years ago.

Another disclaimer: When I say “typesafe” I mean that tag files support the declaration of parameter types and some advanced IDEs like Intellij will actually use that information at source edit time to help the developer avoid runtime errors. If you want to get more reliable type safety independent of the IDE, you might want to consider a JSP pre-compilation approach like this one.

Ok, so now to the actual thing I wanted to write about:

If you have repetitive markup in your JSP pages you have several options for reuse, including:

1. The <% @include %> directive for static file inclusion
2. <jsp:include> or <c:import> tags for runtime inclusion
3. Complicated “classic” JSP custom tags with tag handler Java code

All of these have limitations or problems: Static includes do not support any parametrization, jsp:include and c:import tags only support String parameters (via nested jsp:param tags) and custom tags with tag handlers and tab library descriptors require writing and compiling Java code that generates markup which is a bad practice and complicated.

JSP tag files, introduced in JSP 2.0 (JEE 1.4) solve all these problems and allow simple, straightforward and compact markup reuse that supports parameters of any Java type. The reference documentation is in the JEE 1.4 tutorial.

For example, put these lines into WEB-INF/tags/email.tag:

<%@ attribute name="p" required="true" type="net.doepner.Person" %>

<span title="Send email to ${p.name} &lt;${p.email}&gt;">
    <a href="mailto:${p.email}">${p.name}</a>
</span>

Then you can use it in any of your JSP pages as a tag like this, assuming the page has access to a “company” bean that has a getBoss() method:

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

<x:email p="${company.boss}" />

The good part about declaring the attribute type in your tag file is that IDEs like IntelliJ can provide all the nice things like code completion, refactoring support, javadoc display, etc for the EL expressions, like p.email or p.name in the example.

If the Java type of the “company” bean is known to the IDE, then it will even show an error in case the return type of getBoss() was not a subtype of Person.

Other nice things about the tag file approach:

• No tag library descriptor (tld) file required
• Tag attributes have local scope (not polluting the session, request or page scope)

Packaged tag files

A very cool thing about tag files is that they can be packaged in jars and reused in other web applications. This page in the J2EE 1.4 tutorial explains the details.

Sometimes people ask me how to learn Java, or aspects of Java. As a quick and free option, I usually recommend the Official Java tutorials.

Of course, you should do this hands-on, after installing a recent JDK and a decent text editor or IDE.

My favorite sources for Java coding conventions and guidelines:

• Code Conventions for the Java Programming Language (Sun, now Oracle)
• Java Coding Standard (NASA / Jet Propulsion Laboratory, Caltech)
• Secure Coding Standard for Java (CERT / Oracle)
• Book: Effective Java, 2nd ed. (Josh Bloch, Sun / now Google)
• Book: Clean Code (Robert C. Martin aka “Uncle Bob”)

To generate CSV from Java consider this simple interface:

package net.doepner;

import java.io.IOException;

/**
 * Generates CSV (comma separated values) for rows of Java objects
 */
public interface ICsvWriter {

    /**
     * Adds a row of objects to the CSV document
     *
     * @param values The objects in the row (count must match the number of the
     *               headers)
     */
    void row(Object... values);

    /**
     * Writes CSV based on the the String representations of the objects
     *
     * @param appendable The writer to append to
     * @throws IOException If underlying IO fails
     */
    void appendTo(Appendable appendable) throws IOException;
}

I implemented the interface with this CsvWriter class:

package net.doepner;

import java.io.IOException;
import java.util.Arrays;
import java.util.Collection;
import java.util.LinkedList;
import java.util.regex.Pattern;

/**
 * Convenient generation of CSV
 */
public class CsvWriter implements ICsvWriter {

    private static final CharSequence CSV_ROW_END = "\r\n";
    private static final char LINE_BREAK_WITHIN_CELL = '\n';

    private static final Pattern QUOTES = Pattern.compile("\"");
    private static final String ESCAPED_QUOTE = "\"\"";

    private final Object[] headers;
    private final Collection<Object[]> rows = new LinkedList<Object[]>();

    /**
     * @param headers The objects representing the column headers
     */
    public CsvWriter(Object... headers) {
        this.headers = Arrays.copyOf(headers, headers.length);
        if (cols() == 0) {
            throw new IllegalArgumentException("No columns");
        }
    }

    @Override
    public final void row(Object... values) {
        if (values.length != cols()) {
            throw new IllegalArgumentException("Specify " + cols() + "values ");
        }
        rows.add(Arrays.copyOf(values, values.length));
    }

    @Override
    public final void appendTo(Appendable appendable) throws IOException {
        appendRow(appendable, headers);

        for (Object[] row : rows) {
            appendRow(appendable, row);
        }
    }

    private static void appendRow(Appendable appendable, Object[] row)
            throws IOException {
        boolean first = true;
        for (Object value : row) {
            if (first) {
                first = false;
            } else {
                appendable.append(",");
            }
            appendable.append('"');
            appendable.append(toCsvString(value));
            appendable.append('"');
        }
        appendable.append(CSV_ROW_END);
    }

    private static CharSequence toCsvString(Object object) {
        if (object instanceof Iterable) {
            final StringBuilder sb = new StringBuilder();
            boolean first = true;
            for (Object o : (Iterable<?>) object) {
                if (first) {
                    first = false;
                } else {
                    sb.append(LINE_BREAK_WITHIN_CELL);
                }
                sb.append(toCsvString(o));
            }
            return sb.toString();
        } else {
            if (object == null) {
                return "";
            } else {
                final String s = object.toString();
                return QUOTES.matcher(s).replaceAll(ESCAPED_QUOTE);
            }
        }
    }

    private int cols() {
        return headers.length;
    }
}

Example for how it can be used in a Servlet, here with full support for Unicode characters using UTF-8, in a way that even Excel understands:

    private static final char BYTE_ORDER_MARK = (char) 0xfeff;
 
    private static void generateCsv(ServletResponse resp, 
                                    Iterable<IMessage> messages)
            throws ServletException {

        resp.setContentType("text/csv");
        resp.setCharacterEncoding("UTF-8");

        final ICsvWriter csv = new CsvWriter(
                "Date", "Sender", "Recipients", "Subject");

        for (IMessage msg : messages) {
            csv.row(msg.getDateTime(), msg.getSender(), 
                    msg.getRecipients, msg.getSubject());
        }

        final PrintWriter writer = getResponseWriter(resp);
        try {
            // The BOM is required so that Excel will recognize UTF-8
            // characters properly, i.e. all non-ASCII letters, etc.
            writer.print(BYTE_ORDER_MARK);
            writer.flush();

            csv.appendTo(writer);
            writer.flush();

        } catch (IOException e) {
            throw new ServletException(e);
        }
    }

    private static PrintWriter getResponseWriter(ServletResponse resp)
            throws ServletException {
        try {
            return resp.getWriter();
        } catch (IOException e) {
            throw new ServletException(e);
        }
    }