Time to read: 8 minutes.
A tool to test and document Java code rapidly
This article appeared in IBM developerWorks Magazine in April 2001.
By Alex Roetter
Software Engineer, Teton Data Systems
Introduction to JSP Explorer
Good documentation is probably one of the most critical parts of any new piece of software, but certainly one of the most neglected. Whether it's because individuals or companies want to get a new product to market as quickly as possible, or because (as conventional wisdom holds) developers rarely have the perspective to document their own creations, the end user trying to learn a new API, for example, is often left out in the cold. JSP Explorer is a Java-based tool designed to make both documenting and learning new software a great deal easier, by providing a simple means to create dynamic html documents which give end-users a new way to explore and play and experiment with code snippets.
JSP Explorer is a Web application developed by zamples.com that brings API documentation to life. JSP Explorer can generate HTML for inclusion into Javadocs (or any HTML document), that displays a code fragment and a ‘Try It!‘ button. This provides ‘live’ demos of the code being documented. When a person reading the document clicks on the ‘Try It!’ button, JSP Explorer is launched, pre-loaded with a JSP or Java code fragment (see the sample below in Listing 1). JSP Explorer also allows developers to test and prototype JSP, server-side Java applications and applets rapidly.
Listing 1. Sample JSP Application
This is static HTML<br>
HTML says hello world!
<%
//This is Java code embedded in a JSP page
out.println("Java says hello world!");
out.println("Your browser is of type: " + request.getHeader("user-agent"));
out.println("I can count from 1 to 10");
for(int i=1; i <=10; i++)
{
out.println("Number = " + i);
}
%>
|
When a client running Windows 2000 accesses this Web page, Internet Explorer 5.0 displays the following page:
This is static HTML HTML says hello world! Java says hello world! Your browser is of type: Mozilla/4.0 (compatible; MSIE 5.01; Windows NT 5.0) I can count from 1 to 10 Number = 1 Number = 2 Number = 3 Number = 4 Number = 5 Number = 6 Number = 7 Number = 8 Number = 9 Number = 10
Basic operation
The basic operation of the JSP Explorer is fairly straightforward and intuitive. The interface consists of two frames, a text input frame where a programmer can enter his or her code, and an output frame. The output frame displays the results of the program after it is executed on the server. A ‘Run it!’ button exists in the text input frame which causes JSP Explorer to take the entered code and, according to the options set in the UI, generate a complete JSP that is displayed in the output frame.
The text frame consists of a box to enter import commands, a box to enter JSP, and a box to enter applet code.
Text can be entered into the JSP box as pure Java or as JSP.
A pull-down menu provides a choice between JSP, Java, and applet code.
Choosing JSP causes the code snippet the user has entered to be pasted directly into the resulting JSP page.
Choosing Java causes the code to be pasted into the JSP surrounded by the <% and %> tags,
which in JSP signify a block of embedded Java code.
Choosing applet from the pull-down menu causes the code in the third text box to be compiled into a Java applet.
The assumption when choosing this option is that the JSP text box contains code to embed the applet into the resulting JSP page.
The user also has the option to have the JSP use a predefined style sheet that formats the output nicely,
and to wrap the JSP output in the HTML <pre> tag, which preserves new lines and the spacing of the output that Web browsers
ignore while rendering HTML.
In addition, the user can view the source of the generated JSP rather than execute that JSP.
This is quite helpful to the novice programmer who needs to see examples of valid JSP pages, especially examples of how to embed Java into a JSP page.
There is also a button labeled HTML that generates an HTML button which encapsulates the sample code. This feature allows JSP Explorer to be used for generating live code documentation. Hitting the HTML button sends the HTML code for the button to the results frame, so it can be copied and then pasted into another Web page. The generated HTML button launches JSP Explorer with your code inserted into the code frame. This allows a code documentation page to show some sample code and to display a button that can be clicked to launch JSP Explorer and instantly run the code. This idea of interactive documentation is appealing. For example, running the code sample shown above in HTML encode mode generates the Web page snippet included immediately below. Note the inclusion of the source as it is entered into JSP Explorer, and the button to launch JSP Explorer in a new browser window.
Potential JSP Explorer Uses
The primary target users of JSP Explorer is a developer who wants to generate interactive HTML documentation and the user that will learn new APIs, with that documentation. Here JSP Explorer excels. The developer simply pastes the code into the text entry frame and clicks the HTML button. The result is HTML source that can be pasted into javadocs or sample code pages. For users of IE 5.5, the labels in the output frame are clickable, so that the HTML is automatically copied into the system clipboard. This is a quick way to create pages. The ability to generate of Web pages that contain executable code is the most attractive and useful feature of JSP Explorer.
The simple interface is excellent for users who do not have a servlet-enabled Web server but who would like to experiment with JSP or test out the technology. The lack of debugging capability should not be too much of a problem if the user wants to test only simple programs. The difficulty for a novice Java programmer is the way in which compilation errors are reported back to the user, which will be discussed below.
JSP Explorer is ideal for quick software documentation and a great way to play with code snippets.
Software developers who are looking for a way to prototype or test some code rapidly may also find JSP Explorer useful.
The developer can type into the editing window and hit run to see the output of his/her code.
While this functionality is nice for simple programs, it can be cumbersome for more substantial code.
First of all, the text window is a simple HTML form element and lacks any of the helpful formatting that most modern code editors include.
I personally missed syntax highlighting, intelligent tabbing, and parenthesis and bracket matching.
Hitting tab, a common event while programming, causes the Web page to move to the next form element,
an annoying and unintended consequence.
The workaround is to write code in another editor and cut and paste it into the Web page when you want to test it.
This could be quite useful, especially if the developer does not have a Web server with a servlet container available to test the code.
Assuming the existence of a Web server set up to execute JSP pages (a resource available to most JSP developers)
it is faster to develop the program locally and run it within the development Web environment.
Because the servlet container is under the control of the developer, it allows the use of servlet debugging to diagnose code problems.
JSP Explorer provides a plug-in for Borland's JBuilder to assist with the HTML generation process.
The generated HTML can be pasted back into the .java files, to assist with the creation of live Javadoc.
Problems with JSP Explorer
JSP Explorer has a few minor problems preventing it from being a fully-fledged development tool.
For example, the error reporting process could be clearer.
I wrote a simple program that used an undeclared variable which produced the error message, “Undefined variable,”
was buried in the output window amongst a list of Can't compile class...,
as well as a full stack trace of the Java exception that was generated by the compilation process.
While this is fine for a seasoned developer who can dive through the code to find the meaningful part of the lengthy message,
it could be quite daunting for a novice Java programmer.
The tool would be much more useful if error messages were parsed on the server side and sent to the client as short,
meaningful error messages.
The error messages returned by javac, the Java compiler, are good models.
They are short and clearly label the error with a description of the problem and a location in the code where the problem occurred.
Debugging code fragments entered into JSP is impossible. Because the servlet container lives on a remote machine that is not under the control of the developer, it is impossible to attach a debugger to the container process. This limits the ability to develop and test nontrivial code. Being able to install JSP Explorer on a local Web server would alleviate this problem entirely. The author of JSP Explorer invites people interested in licensing JSP Explorer and installing it locally to contact him.
Finally, creating a new applet is too difficult to be done by scratch. The naming requirements for the applet class imposed by JSP Explorer are quite specific. As a result, to create a new applet, the user must click the New Applet link found in the applet section of the documentation page. This link loads a skeleton JSP into the JSP box and a skeleton applet into the applet box, complete with the code to correctly launch the applet from the JSP page.
This allows the JSP page to properly reference the applet that will be compiled on the server side. While the complicated naming scheme is necessary to support multiple users compiling multiple applets, it requires a bit of care by the user to not accidentally delete or change the skeleton code in a way that breaks the system. Another minor annoyance with the applet code is that the import statements entered into the topmost text entry field do not effect the applet code, but only the JSP code. This means that any Java classes that the applet code needs must also be imported in the applet code entry text box.
Conclusion
JSP Explorer helps programmers and developers to test simple ideas and develop documentation quickly for JSP or Java code. While the poor error reporting and editing environment make JSP unacceptable as a full time development tool, that is not its primary use. JSP Explorer is a quick and powerful way to show how an API works by using sample live code fragments. Its ability to integrate with databases, servlets, and other remote or local resources makes it a powerful tool. Indeed, it excels in a couple of areas. For the new developer who needs to test programs quickly without the overhead of their own Web server, JSP Explorer allows for a speedy write and test cycle, facilitating the learning process.
For the developer who has pre-tested and reasonably bug-free code, JSP Explorer allows the quick development of ‘live’ documentation. As long as the user stays away from extensive development inside the JSP Explorer environment, focusing instead on trivial or pre-tested applications, JSP Explorer is a helpful, easy to use tool for the Java developer and technical writer.
Resources
- JSP Explorer Home Page. The author invites inquiries from parties interested in integrating JSP Explorer into their documentation systems.
- Visit the Java Server Pages Home Page for all sorts of information related to Java, such as product information, industry news, case studies, etc.
- The Java Servlet Home Page gives readers a good description of Java Servlet technology and contains links to other pages of interest.
About the author
Alex Roetter has been writing software in Java since version 1.0 debuted several years ago. He is currently developing a Web based searchable database application predominantly in C++. He holds a BS in Computer Science from Stanford University.
