Workshop 控件和扩展：第2部分

　　简介

　　假如您已经开发出相当酷的控件，并且希望所有人都使用它。那么就不能只给人们发送一个ZIP文件，然后希望他们能使用它。您必须把控件交付到silver platter 上去。这个过程中的一个重要部分就是说明文档，本文将讨论为控件添加说明文档需要采取的步骤。

　　说明文档的重要性不只体现在使终端用户兴奋方面，它还是控件的验证过程的一个重要方面。验证意味着一个独立的机构（例如，ComponentSource.com），按照特定的测试计划评估控件，以确保该控件在WebLogic Workshop 中良好地运行。

　　起始点

　　作为本文的基础，让我们从一个已有的控件开始，该控件不具备所有必需的说明文档。它是一个发送和接收电子邮件的helper组件。我们随后将通过添加必需的说明文档使该控件完整。参阅下载区，获得到该基本控件的链接。假如您已经下载了代码，就可以通过本文，把技术应用到基本控件上。

　　一旦完成之后，最终的控件将具有：

• API 说明文档
• 一份用户指南
• 控件属性描述
• 一张内容表
• 两个使用该控件的示例应用程序

　　最后，我们将测试控件的说明文档。

　　注重：扩展也可以提供说明文档，但是不如控件的说明文档重要。API和控件属性说明文档，还有示例应用程序不会应用到扩展中。您可以使用文中描述的方法为扩展编写用户指南和内容表。

　　验证过程

　　验证过程针对BEA WebLogic Workshop版本来验证控件和扩展，证实它们能够良好地共同运行。

　　验证不是强制性的。您可以扩展WebLogic Workshop，然后直接把产品分发给用户。您还可以把创建的产品邮寄给知识库，甚至是ComponentSource站点。有人选择不验证控件和扩展，因为这个过程有点昂贵。但是要使控件和扩展进入BEA’s Premier Component Gallery站点，就要求进行验证。

　　Emailer控件

　　现在让我们转向基本控件。Emailer控件方便了电子邮件消息的发送和接收。下载区的start.zip提供了该控件。解压缩该文件并双击EmailerApp.work。选择默认（示例）WebLogic Workshop服务器实例。图1显示了我们讨论的控件。

图1. 项目结构

　　本文不包括控件编写这个主题。假如需要关于该主题的更多信息，请参考文章Advanced Controls Development Primer，或查看在线说明文档。

　　在这里我们可以看到该控件提供了三个方法和一个回调。在内部它使用timer控件。该控件可以用于发送电子邮件（sendMail()方法）和接收电子邮件（getMail()或调用start()并等待receiveMail()方法回调）。

　　关于源代码的注释：

• 当使用回调把事件推进到用户类时，还要提供轮询机制，这很重要。这是因为回调不能被web应用程序使用。
• 该控件有一整套JavaDoc。假如控件还没有良好的JavaDoc，那么现在就动手编写它们。
• 该控件抛出的异常应该在ControlException或其子类内部。

　　目录结构

　　我们从一个包含多个项目的应用程序开始，而最终我们希望能产生一个包含项目的控件、说明文档和示例的ZIP安装文件。该ZIP文件有一个我们将要在此进行讨论的非凡结构。

　　首先，需要有下面的一组说明文档，全部是Html格式的：

应用程序文件夹和文件

内容

EmailerApp/Emailer/doc/en
/partners/dev2dev/...

所有说明文档的根目录。en表示English（这显示也可以支持其他语言）。dev2dev文件夹在此用来表示公司名称。该文件夹也包含了内容表格文件。doc文件夹将被添加到ZIP安装文件中的help目的文件夹。安装过程最终将把这些文件放在C:eaweblogic81workshophelp目录下。

.../java-class/*.html

生成的JavaDoc。不要把它与javadoc-tag文件夹（如下）混淆。