Featured White Papers

• Measuring Risk to Improve Java Software Quality
• Do You Really Get Classloaders?
• Pragmatic Continuous Delivery with Jenkins, Nexus, and LiveRebel
• Your Next Java Web App: Less XML, No Long Restarts, Fewer Hassles
• Coding with JRebel, Java Forever Changed
• 2012 Developer Productivity Report: Java Tools, Tech, Devs, and Data

Sponsored Links

• Graph databases are 1000x faster than relational.

  Learn More!

• Career opportunities at Harman- Careers That'll Rock Your Socks Off.

  Learn More!

• Developer-friendly Java PDF libraries by Qoppa Software

  Live Demos

• Stop blaming your app! Diagnose Java performance issues.

  Free tool >

• UrbanCode: Go From Continuous Integration to
  Continuous Delivery

  Learn More!

Sponsored Links

Optimize with a SATA RAID Storage Solution
Range of capacities as low as $1250 per TB. Ideal if you currently rely on servers/disks/JBODs

More JSP best practices

JSP advancements ease development of standardized, highly maintainable JSP-based applications

By Dustin Marx, JavaWorld.com, 07/25/03

Page 5 of 6

The servlet specification itself lists numerous potential servlet filter uses.

Document the APIs for your JSPs

One of Java's many desirable features is its Javadoc support. Javadoc lets you quickly and easily provide Web-based documentation of your Java code. Unfortunately, the Javadoc tool does not support JSP, and the JSP specification does not call out a similar method of providing "JSP APIs."

What is the JSP API?

It would be extremely useful to quickly identify some JSP aspects without scouring the JSP code itself. For example, you need to know which variables are bound to session, request, or application scope, and which of these scopes they are bound to. Another example of useful JSP API information is denoting in JSP segments which variables they require the calling JSP to have declared and defined when including them.

The JSP specifications do not address the issue of documenting JSP APIs. The JSP 1.x Code Convention document from Sun (see Resources) discusses putting comments at the top of JSPs with information such as author, copyright, and description, but I like to document my JSPs' expected inputs more thoroughly.

Because the specification does not address this, there is no standard for commenting this type of JSP API information. One approach might be to use scriptlets and enclose Javadoc-style comments (/** javadoc comment */) in them. Although I typically do not place scriptlets in my JSPs, this is the easiest way to keep these comments on the server side only when using JSP documents. It is not a good idea to expose your JSP APIs to clients by using XML/HTML-style comments for this information.

I am aware of two freely available products for documenting your JSPs. JspDoc is available through SourceForge.net. Another tool with a similar name is JSPDoc, available at Open Source Development Network (OSDN)'s Freshmeat.net. (See Resources for more detailed information about these two products.) I present a brief summary of each product here.

JspDoc (SourceForge)

Available through SourceForge, the JspDoc tool generates Javadoc-like documentation pages for JSPs. This documentation generation is enabled by placing XML-compliant tags within Javadoc-style comments (/** */) that are in turn placed within JSP page scriptlet tags (<% %>). A drawback is that this tool only supports JSP pages, though support for JSP documents is on the planned extensions list.

This tool also provides a utility for converting JSP pages ("classic") to JSP documents ("new"). Because I write JSP documents to begin with, I have not used this extra utility, but it might benefit those wishing to migrate JSP pages to JSP documents. Another utility converts JSP documents to JSP pages.

JSPDoc (Freshmeat.net)

Listed as JSP Documentation Generator on the Freshmeat.net site, this tool extracts information directly from your JSPs to build Javadoc-like Web-based documentation pages. One of this tool's strengths is its ability to integrate the generated JSP documentation with Javadoc-generated documentation for Java classes. One drawback is that the expected comment structure for generating documentation pages is fairly rigid. This special syntax uses Javadoc delimiters (/** */), but does not recognize the special significance of the @ symbol, which is meaningful in standard Javadoc. This is an issue for the product's to-do list. Another drawback for me is that this tool does not support XML-compliant JSP documents, but instead requires <% %> syntax use. This product is available under the Mozilla public license.