Workshop控件和扩展：第2部分

　　 
　　BEA WebLogic Workshop控件应该附有可靠的说明文档。在WebLogic Workshop控件和扩展系列文章的第2部分，我们将讨论为了使控件可用，甚至被BEA验证过程接受，需要采取的步骤。

我们将向一个看起来很简单的控件添加JavaDoc、用户指南、属性描述、示例应用程序，以及把它合并到WebLogic Workshop帮助系统所需的基础架构。

　　简介

　　如果您已经开发出相当酷的控件，并且希望所有人都使用它。那么就不能只给人们发送一个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格式的：

clearcase/" target="_blank" >cccccc border=0>

应用程序文件夹和文件	内容
EmailerApp/Emailer/doc/en /partners/dev2dev/...	所有说明文档的根目录。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 认证的工程师。

原文转自：http://www.ltesting.net