JSP Explorer Proof of Concept

Time to read: 8 minutes.

Sample O'Reilly Articles Converted to use JSP Explorer

Four articles were converted to use JSP Explorer by Mike Slinn as a proof of concept for online articles with interactive code examples. JSP Explorer is the first of a family of products for interacting with live code. IBM devloperWorks released this review of JSP Explorer on August 21, 2001. The second member of the family, ActiveReader, is available for previewing.

General comments

This section contains comments that are applicable to all of the revised articles.

One benefit to having code online and executable via a browser is that editors and authors can be sure at all times that the code is correct, as well as correctly configured. Most of the articles that I worked on had errors – errors which would have been noticed by the author had he/she been publishing ‘live’ code. The examples in some of the articles were time-consuming to set up, and for a novice, virtually impossible to get working. Again, had the articles been executable on-line, the reader's experience would have been greatly enhanced ... see for yourself by reading the revised versions of the articles, available at the end of this document.

I added a link at the top of each article to a JAR file containing all the sample code used in the article, including java source and class files.

General guidelines

In order for the reader to have a rewarding experience interacting with a server-side document through a browser, and so that the reader will be able to run the sample code with a single click, here are some general guidelines for interactive Java code:

Discrete Files: Each class must be contained in a separate file - with the exception of inner classes. Very often authors make up a single file containing all of the source files. Instead, authors should place the java and class files in a JAR.
Use a package: Place each class in package so that class names will not collide with similarly named classes in other packages on the server.
Use consistent package names: Some O'Reilly authors use com.oreilly.whatever, others use com.ora.book.chapter. So that the code base remains managable, a naming convention should be established, and all code examples should be altered to conform.

Directory structure: Source files must be in the appropriate subdirectory, according to the package that they reside in.

Declare all exceptions: This is an important practice to follow, but because the command-line javac compiler isn't strict about enforcing this rule, classes can get compiled by javac that will cause errors when compiled by a stricter compiler, such as Jasper.

JSP Explorer Guidelines

The following guidelines are implementation specific - that is, these guidelines pertain to code examples prepared for JSP Explorer:

Public classes: Since the Java classes will be accessed from a JSP, they must be declared public.
Don't use System.out or System.err: Use out.println() instead of System.out.println(), similarly use err.println() instead of System.err.println(). This is so that output will appear on the browser, not the remote system console which is not visible to the reader.

No output from static methods: Because out is an instance of JspWriter, and you can't reference an instance variable from a static method, any methods writing to out cannot be declared static.

Organize code for exhibition: In order for the reader to have a good experience playing with the code, the sections of the program that they would be most likely to play with should be combined into a code fragment or a single (short) class. This exposition class should be as short as possible.

Because the current version of JSP Explorer only allows the reader to interact with a single class at a time, support classes must be supplied in a JAR.
Edit displayed code: JSP Explorer separates the displayed code from the code that is executed. What this means is that you can edit the displayed code next to the HTML button without affecting the stored code that is transmitted from the form to JSP Explorer when the Try It! button is pressed. Because JSP Explorer's displayed code is HTML encoded, it is difficult to edit without an HTML editor such as DreamWeaver. We show two examples of this: an applet and a JSP. The examples illustrate removing import statements, edit base class references, folding lines so that they fit in a narrower page and renaming an applet so that it has a more 'normal' name.
Include action limitation: Under Tomcat 3.2.1, JSP Explorer cannot process nested include actions, that is, JSP statements of the form: <jsp:include page="pagename.jsp" />. JSP Explorer already uses such a construct in order to operate, hence your JSPs cannot use include actions. Should JSP Explorer run under a different servlet container, this restriction may not apply. There is no such limitation for <%@ include %> statements (known as include directives).

This also means that one can't set headers or use <jsp:forward> in a sample JSP created by JSP Explorer. Since response.sendRedirect() works by setting a meta header, this method cannot be used in JSP Explorer JSP.
Use a Stylesheet: JSP Explorer uses a stylesheet to format the 'Try It!' buttons and the generated code. The formInput class controls the rendering of the buttons. I have augmented O'Reilly's style2.css to display code more clearly. Should you wish to display JSP Explorer's HTML differently, merely edit the style sheet.

Revised articles

Click on the following articles to interact with revised versions of the articles. Note that two images have been added below the table of contents on the left hand side of the pages. One image advertises WantJava, which is the ISP that hosts JSP Explorer, servlets.com and open source projects such as JBoss. The other image advertises JSP Explorer.

Optimizing a Query on a Collection by Jack Shirazi, author of Java Performance Tuning

This article as written does not take advantage of an 'incremental' approach to putting together sample code. One suggestion is for each test to be shown separately (an 'interactive' approach), instead of combined into one big test suite (a 'batch' approach). This is probably good advice in any case - instead of providing a whack of code for the reader to comb through after they have skimmed over the article, the article could be more interactive, presenting each test separately and thereby reinforcing the main points more effectively. I provided one such interactive test example (tests 5 and 6 in the Eliminating Casts section), but didn't rewrite the entire article. The code should really be condensed and reorganized so that it gets to the point better, but I didn't want to spend too much time fussing with it. In particular, initializeList() doesn't add much value by this time in the article, and should be moved to a support class.

As a point of interest, the calls to System.currentTimeMillis() are expensive, and are included in the timing. This skews the test results. The tests would be more accurate if test5() and test6() ran under the control of a for loop, and sets of invocations of test5() were timed as a group, then another set of invocations of test6() were timed as a group..

I provided two code examples that run the entire test suite at the end of the article. In the first code example I didn't show any code for the reader to mess with. The second (and admittedly very long) example shows the main class in its entirety . Spending more time organizing the rest of the code into logical 'chunks' would allow the reader access to the parts of the code that they want to. The visual representation of the sample code in the "Eliminating Casts" section was edited for brevity, but the last code example was not - although it was quite long. An editor might well desire to edit the visual appearance of this extremely long code example. As described in the documentation, editing the visual appearance of the sample code has no effect on the actual stored code.

I made the following changes to the code:

placed each class into a package called com.oreilly.jpt.test2
public attribute added to class statements in ListTest.java and ListStringTest.java
converted System.out to reference out instead
eliminated static methods and variables
added throws clauses (should have been there in the first place)
corrected folded string constants

Andy and David's Top Ten Internationalization Tips by Andy Deitsch and David Czarnecki, coauthors of Java Internationalization

Sections 1 and 3 was a nice example of how to use JSP Explorer. Section 2 was written for command-line invocation, and I am awaiting a response from David re. JSP invocation. I corrected errors in Section 3 (missing quotation marks around Strings, and missing semicolons at the end of the statements).

For section 4, I wanted to see what a shift-JIS file looked like, so I grabbed a news release from NTT DoCoMo (the first bullet point on https://www.nttdocomo.co.jp/i/java.html) and saved it to a file (shiftJIS.txt). I then guessed at what the appropriate code might be to display it and appended two lines to the code example provided by the author.

Section 5 was a beautiful demo of 'live' code exposition and JSP Explorer.

The code in section 6 did not work. I've asked the authors to help me out.

Sections 7 and 8 had no code examples.

Sections 9 and 10 were ideal candidates for JSP Explorer. The authors made a slight leap when they introduced Locale.GERMAN without telling the reader how the German formatting was achieved. I added an extra example, then asked the reader to follow my lead for Locale.FRENCH.

Designing Internationalized User Interface Components for Web Applications by David Czarnecki, coauthor of Java Iternationalization

Example 1-1 is a tag library descriptor (XML), which cannot be animated without some code to drive it. Example 1-2 is more XML, this time for configurating the web application. Example 1-3 is the code that implements the tag library. Java servers require a restart whenever the tag library code changes (Tomcat 4.x running under JDK 1.4 promises to remove this restriction), so the reader is not free to play with this code via JSP Explorer.

Examples 1-4 through 1-6 are text resource bundles and should not be altered by the reader.

Example 1-7 is a perfect candidate for JSP Explorer, so I replaced the displayed code with a reference to a JSP explorer page. The original code is still visible next to the Try It! button. I have yet to get this example working (this is not a JSP Explorer problem, I just can't get the example to work at all!), and await help from the author before being able to complete the task of converting the remainder of the article to use JSP Explorer.

I found the process of making up a working example to be time-consuming and error-prone, and I finally gave up. Surely every reader must have the same experience. Once the author has a working setup they can share it with the world, saving each reader considerable time and frustration.

Hans's Top Ten JSP Tips by Hans Bergsten, author of JavaServer Pages

In the spirit of JSP Explorer ('show me it working and let me play with it'), every example should work. I therefor extended section 1 to demonstrate how includes work, subject to JSP Explorer's include action limitation, described above.

Sections 2 through 4 discuss the limitations on the <jsp:forward> action and the response.sendRedirect() method, which also apply to JSPs created by JSP Explorer. Sample pages could be created, but since they would not utilize JSP Explorer, I didn't bother.

Section 5 had no code, and would have expanded to an entire article itself had a working example been provided. A reference to another article would have been the best option here - in fact, portions of David Czarnecki's article entitled Designing Internationalized User Interface Components for Web Applications would have been a good start.

Section 6 is a warm-up for section 7, so I deferred examples until then.

The code example in sections 7 and 8 were incomplete in that they lacked source code to a suitable UserInfoBean class. I have supplied UserInfoBean so that the code works.

Section 8 would have benefited from a reference to another article that delved into the subject in more detail.