使用 JSP Explorer 快速进行 Java 代码的测试和文档的编制

好的文档是任何新软件发布时最关键的部分之一，也是最常被忽视的问题之一。不论文档被忽视的原因是个人或公司想尽可能快地用一个新产品去占领市场，还是开发者极少有为他们自己的创造编制文档的意识（像传统智慧所弘扬的那样），文档的缺乏都导致了最终用户处于困境。JSP Explorer 是一个基于 Java 技术的工具，它为寻求为自己的代码编制文档的开发者和寻求学习及试验新 API 的最终用户都提供了可能的解决方案。

介绍 JSP Explorer

JSP Explorer 由 mslinn.com（请参阅 参考资料）开发，它是一个使 API 文档更加生动的 Web 应用程序。假设有一段原始代码，JSP Explorer 就会动态地生成那些代码的 HTML 显示，并带有一个 Try It!按钮。这个 HTML 可被包含在任何 javadoc（或任何 HTML 文档）中，提供正在归档的代码的“现场直播”式的演示。当阅读该文档的人单击 Try It!按钮时，JSP Explorer 就被启动，并预装载 JSP 或 Java 代码片段，如清单 1 所示。

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);
  }
%>

当运行 Windows 2000 的客户机访问上述页面时，IE 5.0 将显示如清单 2 所示的页面。

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

JSP Explorer 是如何工作的

JSP Explorer 的基本操作是相当简单、直观的。用户界面（user interface，UI）由两个框架组成：一个文本输入框架，您可在这里输入您的代码；一个输出框架，用于显示程序在服务器上执行后的结果。输入您的代码，在文本输入框架单击 Run it!按钮，然后等待 JSP Explorer 根据您在用户界面中设置的选项生成完整的 JSP 页。完成之后，新的 JSP 页显示在输出框架中。

文本框架由导入命令输入框、JSP 代码输入框和 applet 代码输入框组成。文本可以作为纯 Java 或 JSP 代码输入到 JSP 框。下拉菜单提供了 JSP、Java 和 applet 代码三个选项。选择 JSP将把您所输入的代码片段直接粘贴到结果 JSP 页。选择 Java将把代码粘贴到 JSP 页中由标记 <% 和 %> 括起来的部分，在 JSP 代码中，这些标记表示一块嵌入的 Java 代码。从下拉菜单中选择 Applet将使第三个文本框中的代码被编译成 Java applet。假设 JSP 文本框中包含有把 applet 嵌入到结果 JSP 页中的代码，就应选择这一选项。图 1 展示了 JSP Explorer 用户界面。

图 1. JSP Explorer 用户界面

正如您能从用户界面中看到的那样，您可以选择让 JSP 页使用一个预定义的样式表（它精细地格式化了输出），也可选择把 JSP 输出包在 HTML 标记 <pre> 中，该标记保护了 Web 浏览器在解释 HTML 时将会忽略的输出的新行和空格。另外，您可以查看生成的 JSP 页的源代码，而不必执行该 JSP 页。这个选项对想查看正确的 JSP 页示例，尤其是查看如何把 Java 代码嵌入到 JSP 页中的示例的编程新手很有帮助。

从样本代码中生成“现场直播”式的代码文档的操作也相当简单。当您在用户界面中单击 HTML按钮时，JSP Explorer 将生成封装了您的样本代码的 HTML 文件并将它显示在结果框架中。您接着就可以把内容拷贝、粘贴到另一个 Web 页上。生成的 HTML 文件将用您嵌入到代码框架中的代码启动 JSP Explorer，然后创建显示样本代码和一个 Try It!按钮的 HTML 文档。单击 Try It!按钮就可启动 JSP Explorer 并立即运行那些代码。

交互式文档的想法是吸引人的。例如，以 HTML 模式运行显示在图 1 中的代码样本将生成包含在图 1 底部的 Web 页的片段。请注意引入的那些被输入到 JSP Explorer 中的源代码和能在新的浏览器窗口中启动 JSP Explorer 的按钮。

谁将使用 JSP Explorer?

想生成交互式 HTML 文档的开发者和将使用那些文档来学习新 API 的用户很可能是使用 JSP Explorer 最多的人。寻求快速得到代码原型的方法或快速测试代码的方法的开发者们也会发现 JSP Explorer 是有用的。

用 JSP Explorer 测试代码是很容易的：只要把您的代码输入到编辑窗口中，然后单击 Run it!观察其输出即可。虽然这一功能对简单程序来说是很棒的，但对于更实用的代码来说却很麻烦。文本窗口只是一个基础 HTML 表单元素，没有多数现代代码编辑器都包含的有帮助的格式化。我本人是想念语法突出显示、智能跳格和括号匹配的。敲 tab 键 ― 一个编程中常见的操作 ― 将导致 Web 页移到下一个表单元素，这是一个恼人的、非期望的结果。解决方法是：可以在另一个编辑器中写代码，想测试它时把它剪切、粘贴到 Web 页中。这是非常有用的，特别是当您没有一个用于测试代码的配备有 servlet 容器的 Web 服务器时。

如果您的确已经安装了一台 Web 服务器用来执行 JSP 页，在本地开发程序以及在 Web 开发环境中运行它将可以更快。因为 servlet 容器在您的控制下，所以您可以用 servlet 调试来诊断代码中的问题。JSP Explorer 为 Borland 的 JBuilder 提供了一个插件，用以协助 HTML 的生成。生成的 HTML 可以被粘贴回 .java 文件，用以协助“现场直播”式的 javadoc 的创建。

JSP Explorer 的问题

JSP Explorer 中存在的一些小问题阻碍了它成为一个完美的开发工具。首先，错误报告处理本可以更清楚些。为证明这一点，我写了一个使用了未声明变量的简单程序。跟编译过程生成的对 Java 异常的完全堆栈跟踪一样，产生的出错消息 ― “变量未定义” ― 被淹没在输出窗口所显示的一栏无法编译的类中。

虽然这对老练的开发者而言可能没什么问题，他们已经习惯于深入到代码堆中去搜寻相关出错消息，但是对初学的 Java 程序员来说却是相当使人畏缩的。如果出错消息在服务器那边分析，然后以简短、有意义的格式发给客户机，那么 JSP Explorer 就将变得有用得多。Java 编译器就是一个出错消息经过良好格式化的优秀示例：它们都简短，并用对问题的描述及问题在代码中出现的位置清楚地标识了错误。

除出错消息的问题之外，我还发现不可能对输入到 JSP 页中的代码片段进行调试。因为 servlet 容器存在于不在开发者控制之下的远程机器上，所以要把调试器连接到容器进程上是不可能的。尽管把 JSP Explorer 安装在本地 Web 服务器上可以彻底减轻这个问题（查看 参考资料），但这还是限制了您开发、测试有价值代码的能力。

最后，从零开始创建 applet 太困难了。JSP Explorer 强制的 applet 类的命名规定是相当明确的。因此，要创建一个新的 applet，用户必须单击位于文档页面中 Applet 部分的 New Applet链接。此链接在 JSP 框中装入一个 JSP 页框架，并在 applet 框中装入一个 applet 框架，而且包含了从 JSP 页正确地启动 applet 的完整代码。

框架代码使 JSP 页可以正确地引用在服务器那边编译了的 applet。复杂的命名方案对支持多个用户编译多个 applet 来说是必要的，同时也一定要小心避免意外删除或改动框架代码，否则会在一定程度上破坏系统。applet 代码另一个小小的恼人之处是输入到文本输入区顶端的 import 语句并不改变 applet 代码；它们只改变 JSP 代码。这样，任何 applet 要用到的 Java 类都必须在 applet 代码的文本输入框中导入。

结论

对那些需要为 JSP 页或 Java 代码快速测试简单想法及编制文档的程序员和开发者而言，JSP Explorer 是一个强大的帮手。虽然拙劣的出错报告和编辑环境使 JSP Explorer 难以成为一个专门的开发工具，但它确实提供了一条通过使用“现场直播”式的代码片段样本来展示 API 如何工作的快速、简单的途径。与数据库、servlet 及其它远程或本地资源集成的能力使它成为一个万能工具。只要您将注意力从 JSP Explorer 环境中的大量开发转移到小的或已测试过的应用程序上，JSP Explorer 就将证明它是一个对您的代码进行测试和文档编制及学习新 API 的有用、易用的工具。

查看本文来源