簡介

　　假如您已經開發(fā)出相當酷的控件，并且希望所有人都使用它。那么就不能只給人們發(fā)送一個Zip文件，然后希望他們能使用它。您必須把控件交付到silver platter 上去。這個過程中的一個重要部分就是說明文檔，本文將討論為控件添加說明文檔需要采取的步驟。

　　說明文檔的重要性不只體現在使終端用戶興奮方面，它還是控件的驗證過程的一個重要方面。驗證意味著一個獨立的機構（例如，ComponentSource.com），按照特定的測試計劃評估控件，以確保該控件在WebLogic Workshop 中良好地運行。

　　起始點

　　作為本文的基礎，讓我們從一個已有的控件開始，該控件不具備所有必需的說明文檔。它是一個發(fā)送和接收電子郵件的helper組件。我們隨后將通過添加必需的說明文檔使該控件完整。參閱下載區(qū)，獲得到該基本控件的鏈接。假如您已經下載了代碼，就可以通過本文，把技術應用到基本控件上。

　　一旦完成之后，最終的控件將具有：

• API 說明文檔
• 一份用戶指南
• 控件屬性描述
• 一張內容表
• 兩個使用該控件的示例應用程序

　　最后，我們將測試控件的說明文檔。

　　注重：擴展也可以提供說明文檔，但是不如控件的說明文檔重要。API和控件屬性說明文檔，還有示例應用程序不會應用到擴展中。您可以使用文中描述的方法為擴展編寫用戶指南和內容表。

　　驗證過程

　　驗證過程針對BEA WebLogic Workshop版本來驗證控件和擴展，證實它們能夠良好地共同運行。

　　驗證不是強制性的。您可以擴展WebLogic Workshop，然后直接把產品分發(fā)給用戶。您還可以把創(chuàng)建的產品郵寄給知識庫，甚至是ComponentSource站點。有人選擇不驗證控件和擴展，因為這個過程有點昂貴。但是要使控件和擴展進入BEA’s PRemier Component Gallery站點，就要求進行驗證。

　　Emailer控件

　　現在讓我們轉向基本控件。Emailer控件方便了電子郵件消息的發(fā)送和接收。下載區(qū)的start.zip提供了該控件。解壓縮該文件并雙擊EmailerApp.work。選擇默認（示例）WebLogic Workshop服務器實例。圖1顯示了我們討論的控件。

圖1. 項目結構

　　本文不包括控件編寫這個主題。假如需要關于該主題的更多信息，請參考文章Advanced Controls Development Primer，或查看在線說明文檔。

　　在這里我們可以看到該控件提供了三個方法和一個回調。在內部它使用timer控件。該控件可以用于發(fā)送電子郵件（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文件夾（如下）混淆。