簡(jiǎn)介

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

　　說(shuō)明文檔的重要性不只體現(xiàn)在使終端用戶興奮方面，它還是控件的驗(yàn)證過(guò)程的一個(gè)重要方面。驗(yàn)證意味著一個(gè)獨(dú)立的機(jī)構(gòu)（例如，ComponentSource.com），按照特定的測(cè)試計(jì)劃評(píng)估控件，以確保該控件在WebLogic Workshop 中良好地運(yùn)行。

　　起始點(diǎn)

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

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

• API 說(shuō)明文檔
  
• 一份用戶指南
  
• 控件屬性描述
  
• 一張內(nèi)容表
  
• 兩個(gè)使用該控件的示例應(yīng)用程序

　　最后，我們將測(cè)試控件的說(shuō)明文檔。

　　注重：擴(kuò)展也可以提供說(shuō)明文檔，但是不如控件的說(shuō)明文檔重要。API和控件屬性說(shuō)明文檔，還有示例應(yīng)用程序不會(huì)應(yīng)用到擴(kuò)展中。您可以使用文中描述的方法為擴(kuò)展編寫(xiě)用戶指南和內(nèi)容表。

　　驗(yàn)證過(guò)程

　　驗(yàn)證過(guò)程針對(duì)BEA WebLogic Workshop版本來(lái)驗(yàn)證控件和擴(kuò)展，證實(shí)它們能夠良好地共同運(yùn)行。

　　驗(yàn)證不是強(qiáng)制性的。您可以擴(kuò)展WebLogic Workshop，然后直接把產(chǎn)品分發(fā)給用戶。您還可以把創(chuàng)建的產(chǎn)品郵寄給知識(shí)庫(kù)，甚至是ComponentSource站點(diǎn)。有人選擇不驗(yàn)證控件和擴(kuò)展，因?yàn)檫@個(gè)過(guò)程有點(diǎn)昂貴。但是要使控件和擴(kuò)展進(jìn)入BEA’s PRemier Component Gallery站點(diǎn)，就要求進(jìn)行驗(yàn)證。

　　Emailer控件

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

圖1. 項(xiàng)目結(jié)構(gòu)

　　本文不包括控件編寫(xiě)這個(gè)主題。假如需要關(guān)于該主題的更多信息，請(qǐng)參考文章Advanced Controls Development Primer，或查看在線說(shuō)明文檔。

　　在這里我們可以看到該控件提供了三個(gè)方法和一個(gè)回調(diào)。在內(nèi)部它使用timer控件。該控件可以用于發(fā)送電子郵件（sendMail()方法）和接收電子郵件（getMail()或調(diào)用start()并等待receiveMail()方法回調(diào)）。

　　關(guān)于源代碼的注釋：

• 當(dāng)使用回調(diào)把事件推進(jìn)到用戶類時(shí)，還要提供輪詢機(jī)制，這很重要。這是因?yàn)榛卣{(diào)不能被web應(yīng)用程序使用。
  
• 該控件有一整套JavaDoc。假如控件還沒(méi)有良好的JavaDoc，那么現(xiàn)在就動(dòng)手編寫(xiě)它們。
  
• 該控件拋出的異常應(yīng)該在ControlException或其子類內(nèi)部。

　　目錄結(jié)構(gòu)

　　我們從一個(gè)包含多個(gè)項(xiàng)目的應(yīng)用程序開(kāi)始，而最終我們希望能產(chǎn)生一個(gè)包含項(xiàng)目的控件、說(shuō)明文檔和示例的ZIP安裝文件。該ZIP文件有一個(gè)我們將要在此進(jìn)行討論的非凡結(jié)構(gòu)。

　　首先，需要有下面的一組說(shuō)明文檔，全部是Html格式的：

應(yīng)用程序文件夾和文件

內(nèi)容

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