简介
如果您已经开发出相当酷的控件，并且希望所有人都使用它。那么就不能只给人们发送一个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 |
所有说明文档的根目录。en表示english（这显示也可以支持其他语言）。dev2dev文件夹在此用来表示公司名称。该文件夹也包含了内容表格文件。doc文件夹将被添加到zip安装文件中的help目的文件夹。安装过程最终将把这些文件放在c:eaweblogic81workshophelp目录下。 |
|
.../java-class/*.html |
生成的javadoc。不要把它与javadoc-tag文件夹（如下）混淆。 |
|
.../javadoc-tag/jc/*.html |
java控件属性的描述。例如，emailer控件属性将在该文件夹中的emailer.html文件中描述。它类似于 javadocs 的 emailer.xml 文件。 |
|
.../guide/*.html |
该控件的用户指南。可以使用任何您想使用的文件夹和文件名称（“指南”只是一个建议用名）。在本例中，我们将只在该文件夹中创建一个包含使用emailer控件的步骤的index.html文件。 |
最终的emailer控件本身必须从emailerapp/emailer项目添加到zip安装文件（当然了，除 doc 文件夹外）中的/controls文件夹中。安装过程最终将把这些文件放在每个使用该控件的应用程序中，置于app-infib文件夹中。
此外，必须随控件提供至少一个例子应用程序（示例）。它必须能够说明如何使用控件。我建议编写两个示例。下面是我们将研究的示例。
|
应用程序文件夹和文件 |
内容 |
|
emailerapp/webappemailersample/* |
web应用程序示例。这是一个基于web的电子邮件站点。它使用轮询来接收新邮件。 |
|
emailerapp/wsemailersample/* |
web服务示例。调用emailer来订购t恤衫。订购确认也是通过电子邮件接收的。这说明了如何发送和接收电子邮件。 |
它们都将被复制到zip安装文件中的目的文件夹/samples/partners/dev2dev中，安装过程最终将它们放在c:eaweblogic81samples目录下。
注意，这种应用程序文件夹结构只是一种建议，但是它比较接近规定的zip安装结构。
项目完成之后，对它的构建将产生一个zip安装文件，它具有图2所示的结构。
图2. zip安装文件结构
生成javadoc
默认情况下，当编译源代码时，weblogic workshop并不创建javadoc。这一步必须手动添加到构建过程中。为此，要遵循下面的指令：
1. 创建ant构建文件：进入菜单tools|project properties| emailer。在出现的窗口中选择build类别，并单击export to ant file。单击ok 关闭对话框。这就创建了emailerappmailerxported_build.xml文件。把文件重命名为build.xml，取代原来不标准的文件名。
2. 选择使用ant脚本：再次打开emailer项目属性。仍然是在build类别下，单击use ant build。这将自动选择build.xml作为ant文件，并把它作为构建目标进行“构建”。再单击ok。图3说明了最初的两个步骤。
图3. 导出构建脚本
3. 用<javadoc>扩展ant脚本：添加下列代码：
<javelin ...> ... </javelin>
<!-- add this call right after the <javelin> tag of the
compile target. -->
<antcall target="javadoc"/>
...
<!-- add this target right after the compile target. -->
<target name="javadoc">
<javadoc author="false"
destdir="{project.local.directory}/doc/java-class"
version="true"
use="true"
windowtitle="dev2dev -- documenting controls">
<fileset dir="{src.path}" defaultexcludes="yes">
<include name="dev2dev/emailer/**.java" />
<!-- exclude any class that’s not part of the visible api. -->
</fileset>
<doctitle><![cdata[<h1>dev2dev -- documenting controls</h1>]]></doctitle>
<bottom><![cdata[copyright notice goes here.]]></bottom>
</javadoc>
</target>
现在，无论何时想重新生成javadoc，只需执行javadoc构建项目，生成的javadoc将放在/doc/java-class目录下。
编写用户指南
这是发挥您创造性的部分。编写一个或多个描述如何使用控件的html 页面。将它保存在新建文件夹/emailerapp/emailer/doc/guide中。还应该包含关于示例项目的信息。您应当参考weblogic workshop cascading stylesheet (css) 和javascrip文件，如下所示：
<head>
...
<link href="../../../workshop.css" rel="stylesheet" type="text/css"/>
<a href="../../core/index.html" id="index"></a> <!-- points to the main help site -->
<script language="javascript" src="../../../core/topicinfo.js"></script>
<script language="javascript" src="../../../core/cookieclass.js"></script>
<script language="javascript" src="../../../core/displaycontent.js"></script>
</head>
<body>
<script language="javascript">
<!--
displayinframes(); // change the display to the standard frame layout.
//-->
</script>
... insert the documentation here ...
<script language="javascript">
<!--
writetopicinfo(); //insert the standard footer.
//-->
</script>
</body>
合并完成后，最终结果将如图4所示。
图 4. 用户指南
编写html文件时，要问自己一个非常重要的问题：文件放在哪里？css文件放在帮助根文件夹c:/bea/weblogic81/workshop/help/doc/en中。所以html文件以小于这个级别的数量而终止。因此，要引用css，往往必须把级数“……”放在前面。javascript文件在帮助根目录下的core文件夹中。题头中的<a>将不会显示出来，但是displayinframes()要使用它找出帮助站点的根目录。所有这些（css、javascript、<a>标签）都必须指向处于正确的相对位置的文件。
所有超链接都应当遵循下面的格式，这样框架布局才能正确显示。例如：
<a href="javascript:reloadtoc(’../javadoc-tag/jc/emailer.html’)">:emailer tag</a>再次强调，通常使用相对于当前文件的文件夹路径。
编写控件属性描述
控件标签xml文件必须包含在控件中。它列出了控件的各种属性（参数）。以emailer.xml文件为例。要确保每个属性都有一个好的<description>。确保它包含属性类型，以及每种类型的默认值、最大值、最小值和规定值。
现在来编写另一个控件属性提供在线帮助的html文件。创建emailerapp/emailer/doc/javadoc-tag/jc文件夹并添加emailer.html文件。它至少应该包含一段每个属性的综合描述。它也应该指向同样的css和javascript文件，并具有<a>标签。下面就是一个例子：
<html>
<head>
<title>:emailer annotation</title>
<!-- other header tags as required here. -->
<link href="../../../../workshop.css" rel="stylesheet" type="text/css"/>
<a href="../../../core/index.html" id="index"></a> <!-- points to the main help site -->
<script language="javascript" src="../../../../core/topicinfo.js"></script>
<script language="javascript" src="../../../../core/cookieclass.js"></script>
<script language="javascript" src="../../../../core/displaycontent.js"></script>
</head>
<body>
<script language="javascript">
<!--
displayinframes(); // change the display to the standard frame layout.
//-->
</script>
<div id="topictitle">
<h1 class="title">:emailer tag</h1>
</div>
<div id="topictext">
<p>here are the attribute descriptions for a emailer control:</p>
<h2>syntax</h2>
<p class="syntax">:emailer</p>
<p class="syntaxindent">transport=
"<span class="syntaxpartname">imap</span>" |
"<span class="syntaxpartname">pop3</span>"</p>
<p class="syntaxindent">receivehost=
"<span class="syntaxpartname">smtporpop3servertoreceiveemails</span>"</p>
<p class="syntaxindent">sendhost=
"<span class="syntaxpartname">smtpservertosendemails</span>"</p>
<p class="syntaxindent">username=
"<span class="syntaxpartname">smtporpop3username</span>"</p>
<p class="syntaxindent">password=
"<span class="syntaxpartname">smtporpop3password</span>"</p>
<h2>attributes</h2>
<p class="attribute"><a name="transport"></a>transport</p>
<p class="partdesc">mandatory. enter of email server (can be ’imap’ or ’pop3’).</p>
<p class="attribute"><a name="receivehost"></a>receivehost</p>
<p class="partdesc">mandatory. pop3 or imap email server’s address
(to receive emails).</p>
<p class="attribute"><a name="sendhost"></a>sendhost</p>
<p class="partdesc">mandatory. smtp email server’s address (to send emails).</p>
<p class="attribute"><a name="username"></a>username</p>
<p class="partdesc">mandatory. pop3 or imap email server user name.</p>
<p class="attribute"><a name="sendhost"></a>sendhost</p>
<p class="partdesc">mandatory. pop3 or imap email server password.</p>
<script language="javascript">
<!--
writetopicinfo();
//-->
</script>
</body>
</html>
图5显示了产生的页面。
图5. 控件属性
编写内容表
下一步是列出仅以weblogic 特定于workshop 的 xml文件格式所编写的所有文件。在emailerapp/emailer/doc文件夹中创建toc.xml文件。该文件只不过是一组分级的<toc-node>标签。每个标签代表帮助系统的目录树中的一个文档或文件夹。在各级标签的顶部有一个<toc-reference>标签，它指示了“插入”这些节点的位置。这有点像是帮助文件的扩展点。控件通常应该插入到名为“extensions”的引用中，如下所示：
<?xml version="1.0" encoding="iso-8859-1"?>
<toc-root component="other" xmlns="http://www.bea.com/help/toc.xsd">
<toc-reference anchor="extensions">
<toc-node label="emailer control" url="toc.html">
<toc-node label="user’s guide" url="guide/index.html"/>
<toc-node label=":emailer tag" url="javadoc-tag/jc/emailer.html"/>
<toc-node label="java api reference"
url="java-class/dev2dev/emailer/package-summary.html"/>
</toc-node>
</toc-reference>
</toc-root>
这里列出的html文件和toc.xml文件本身的位置是相关的。您可能怀疑为什么要列出java-class/dev2dev/emailer/package-summary.html文件，而不是更合适的java-class/index.html。因为在撰写此文时，当帮助系统中有两个完全一样的url时，就可能发生冲突。通过指向dev2dev 文件夹中的文件，就可以避免冲突。
toc.html文件包含了该内容表格的人类可读版本，而且必须遵循与用户指南和标签引用（就css、javascript和<a> tag而言）同样的语法规则，除了文件是在……/……(上一级文件夹名)文件夹中找到的。如下所示：
<html>
<head>
<link href="../../workshop.css" rel="stylesheet" type="text/css"/>
<a href="../../core/index.html" id="index"></a> <!-- points to the main help site -->
<script language="javascript" src="../../core/topicinfo.js"></script>
<script language="javascript" src="../../core/cookieclass.js"></script>
<script language="javascript" src="../../core/displaycontent.js"></script>
</head>
<body>
<script language="javascript">
<!--
displayinframes(); // change the display to the standard frame layout.
//-->
</script>
<h1>emailer control</h1>
<p>this is the complete set of documentation for the emailer control:</p>
<ul>
<li><a href="javascript:reloadtoc(’guide/index.html’)">user’s guide</a></li>
<li><a href="javascript:reloadtoc(’javadoc-tag/jc/emailer.html’)"
>:emailer tag</a></li>
<li><a href="javascript:reloadtoc
(’java-class/java-class/dev2dev/emailer/package-summary.html’)"
>java api reference</a></li>
</ul>
<script language="javascript">
<!--
writetopicinfo();
//-->
</script>
</body>
</html>
图6显示了内容表格的html表示：
图6. html格式的内容表格
这两个文件代表了要求的最终说明文档，但是这还没有完成，我们还必须编写几个例子。
开发示例
虽然只要求有一个示例，但是我还是建议编写两个示例应用程序。一个是web应用程序，另一个是web服务。这两种应用程序都是现在最流行的。这些示例应该具有完备的文档，不管是内联的(javadoc)还是在控件的用户指南中。因为本文的目标不是解释如何使用emailer控件，所以您可以自主决定如何编写示例。分别在控件的应用程序的/emailerapp/webappemailersample 和 /emailerapp/wsemailersample 文件夹中创建这些项目。下面的这些图（图7、图8和图9）可以指导您。
图7. web应用程序流程
图 8. web应用程序动作
图 9. web服务
如果您不想开发这些应用程序，它们会在完成的项目中提供。我建议您提供小的、简单的应用程序，来说明如何在一个不同的场景中使用控件。不要想着必须在同一个示例中显示出所有使用控件的方式，这将把用户弄糊涂。
打包控件
现在已经准备好要分发控件了。这可以用正确的文件夹中的一个单独的zip文件来实现，它包含了我们先前创建的所有元素。在准备期间，build.xml文件必须用下面的代码稍做修改。该命令生成三个文件夹：controls、help和samples。这些文件夹对安装过程来说是必需的：
<!-- modify these properties. i prefer to use relative paths. -->
<property name="app.local.directory" value="emailerapp" />
<property name="project.local.directory" value="emailerapp/emailer" />
<property name="deliverable.docs.directory" value="doc" />
...
<target name="make-deliverable" depends="build">
<zip update="false" destfile="" >
<zipfileset dir="{app.local.directory}/app-inf/lib"
includes="*.jar" excludes="doc/**" prefix="controls" />
<zipfileset dir="{project.local.directory}/"
prefix="help/doc"/>
<zipfileset dir="{app.local.directory}"
includes="webappemailersample/**,wsemailersample/**"
prefix="samples/partners/dev2dev"/>
</zip>
</target>
要产生zip文件，首先构建整个emailer项目。然后右击emailer，并在菜单中选择build control deliverable。确保zip文件emailer.zip创建在/emailerapp文件夹中。
验证说明文档
我们就要完成了。把emailer.zip复制到文件夹c:eaxt_components中，它是已安装组件的默认文件夹。最后一步是确保编写的帮助文件能够合并到帮助系统中。合并在第一次使用控件时完成。所以我们需要产生一个哑应用程序，并插入控件。那时，将添加下列文件夹：c:eaweblogic81samplespartnersdev2dev，包含两个示例；c:eaweblogic81workshophelpdocnpartnersdev2dev，包含html文件。
使用web浏览器，打开位于c:eaweblogic81workshophelpdocnreindex.html的帮助文件。页面出现在“user-installed extensions”类别下。如果不在这里，确保toc.xml文件的语法有效。您需要卸载控件（清除两个dev2dev文件夹），并重新安装，然后在已修复的帮助文件再次合并之前把它重新插入到项目中。
另一种测试是进入项目的源视图中，单击:emailer标签，并敲击f1键。将会出现上下文帮助。类似地，当光标停在任何一个emailer相关的api 上时，您可以按下f1键，javadoc就会出现。
结束语
在本文中，我们了解了如何编写全面而有用的说明文档。但是值得这么做吗？
设想一下您不知道如何开车。如果有人只是交给您一部新车的钥匙，然后说“祝您好运”，你有什么感觉？您的开车体验很可能是灾难性的。可能您以后再也不想开车了。换一种情况，如果随车子交给您的还有它的使用手册、司机指南，并进行驾驶培训，那么您很可能会成功，并且将与新车形影不离。车子应该是放在silver platter上交给您的。
总之，为控件添加说明文档是控件开发过程的重要组成部分。
在下一篇文章中，我们将介绍文档模板，一个鲜为人知的扩展weblogic workshop的方法。
下载
通过单击下面的链接可以获取本文中所描述的扩展的源代码。每个链接都是一个压缩的weblogic workshop应用程序。要启动它，请解压缩zip文件，然后只需双击work 文件。您需要选择一个运行时环境，选择默认的（示例）环境就可以。
- start.zip (320 kb)
- finish.zip (4 mb)
补充阅读
- workshop controls and extensions: part 1 - writing an extension
- advanced controls development primer
- developing advanced controls在线文档
- control and extension validation process
- the cranky user: the importance of documentation
原文出处
http://dev2dev.bea.com/pub/a/2005/06/wlwseries_extensions2.html
| 作者简介 | |
| emmanuel proulx是j2ee和enterprise javabeans(jvb)方面的专家，他还是获得weblogic server 7.0 认证的工程师。 | |
闽公网安备 35060202000074号