Java CGI HOWTO 中譯版 作者: David H. Silber [1]javacgi-document@orbits.com 譯者: [2]黃志偉 [3]cwhuang@phys.ntu.edu.tw v0.5, 1 December 1998 翻譯日期: 17 December 1998 _________________________________________________________________ 本文解釋如何設定你的伺服器，使其能使用 Java 來寫 CGI 程式，以及如何用 Java 來寫 CGI 程式．雖然 HOWTO 文件的目的是用在 Linux 作業系統上，但這 篇特別的文章事實上與特定版本的 UNIX 系統無關． _________________________________________________________________ 1. 簡介 * 1.1 預備知識 * 1.2 這份文件 * 1.3 軟體套件 * 1.4 The Mailing List 2. 設定伺服器以執行 Java CGI 程式 (解釋篇) * 2.1 系統需求 * 2.2 Java CGI 輔助軟體 * 2.3 解開原始檔 * 2.4 決定你的本地目錄策略 * 2.5 測試你的安裝 3. 設定伺服器以執行 Java CGI 程式 (簡略篇) 4. 執行一個 Java CGI 程式 * 4.1 以 CGI 模式執行 Java 程式的障礙 * 4.2 執行 Java CGI 解決問題 5. 使用 Java CGI 類別 * 5.1 CGI * 5.2 CGI_Test * 5.3 Email * 5.4 Email_Test * 5.5 HTML * 5.6 HTML_Test * 5.7 Text 6. 未來的計畫 7. 版本修改記錄 * 7.1 由 0.4 到 0.5 的修改 * 7.2 由 0.3 到 0.4 的修改 * 7.3 由 0.2 到 0.3 的修改 * 7.4 由 0.1 到 0.2 的修改 _________________________________________________________________ 1. 簡介 由於 Java 的設計方式程式設計師沒有簡易的方法可以取得系統的環境變數． 由 於 Java 發展工具 (JDK) 建立的方式，呼叫一個程式必須使用多重表 徵(tokens)， 這和標準的 HTML forms/CGI 運作方式不易配合． 有一些辦法可 以克服這些限制，而我就實作了其中一種．詳情請見下述． 我寫下前段的時間是 1996. 到現在 Java 的技術已經有很大的改變了。 目前可 能有更好的方法來執行伺服器端的 Java 程式 -- 也許你應該看一看 servlets(?). 1.1 預備知識 我假定你有 HTML 與 CGI 概念的一般知識，而且了解關於你的 HTTP 伺服器的最 基本知識． 你也應該知道如何寫 Java 程式，否則這些都沒有意義． 1.2 這份文件 本文的最新版本可以從此找到: [4]http://www.orbits.com/software/Java_CGI.html. 1.3 軟體套件 本文所提到的軟體套件的最新版本可由匿名 FTP 取得 [5]ftp://ftp.orbits.com/pub/software/java_cgi-0.5.tgz. 這套件包含本文的 SGML 原始檔． 這些套件的散布必須依據 GNU Library General Public License. 本文可依 Linux HOWTO 的版權聲明散布． 如果你使用本軟體，請製作一些參考指向 [6]http://www.orbits.com/software/Java_CGI.html， 以便讓其它人能找到 Java CGI 的類別． 我已經沒有時間再去維護這個套件，因此這或許是最後一版了。 如果有人非常地 喜歡這個程式，而想接手維護，請與我聯絡: [7]javacgi-document@orbits.com 1.4 The Mailing List 我已經建了一個 majordomo 通信論壇讓使用本程式的人們可以互相幫忙解決問題 。 請送信件到 [8]javacgi-request@orbits.com 內容包含 subscribe 這個字。 2. 設定伺服器以執行 Java CGI 程式 (解釋篇) 這一節教你安裝我的 Java CGI 套件，以及大量的解釋，讓你能夠了解你的行為 會導致什麼結果． 如果你只想安裝程式而不想了解為什麼，直接跳到 [9]設定伺 服器以執行 Java CGI 程式 (簡略篇)． 2.1 系統需求 本軟體應該能在已安裝 Java 程式發展工具的任何類 UNIX 的 web 伺服器上安裝 ． 我將它裝在執行 apache 伺服器的 Debian Linux 系統上． 如果你發覺它無 法在你的伺服器上運作，請利用通信論壇. 細節請見 [10]The Mailing List. 不幸的是，Java 執行時期解譯器似乎是吃記憶體的怪物 -- 如果你將使用許多 Java CGI 程式的話你可能要再丟數 MB 的 RAM 到你的伺服器裡． 2.2 Java CGI 輔助軟體 我寫的輔助軟體就叫做 Java CGI．你可從 [11]ftp://ftp.orbits.com/pub/software/java_cgi-0.5.tgz 取得(版本號碼可 能會改變)． 2.3 解開原始檔 找一個合適的目錄將套件解開． (如果你還沒有標準放置軟體的地方，我建議你 放在 /usr/local/src．) 用這個指令解開套件: gzip -dc java_cgi-0.5.tgz | tar -xvf - 這會產生一個叫 java_cgi-0.5 的目錄． 在那裡你可以找到本文其它地方提到的 檔案． (如果版本號碼改變了，就改用那套件裡的．) 2.4 決定你的本地目錄策略 你必須決定讓你的 Java CGI 程式住在那裡． 一般來說，你會希望放在和你的 cgi-bin 平行的目錄． 我的 apache 伺服器設定使用 /var/www/cgi-bin 為 cgi-bin 目錄， 因此我用 /var/www/javacgi 作為放置 Java CGI 程式的地方． 你可能不會想讓將你的 Java CGI 程式放進某一已存在的 CLASSPATH 目錄． 編 輯 Makefile 來反應你的系統配置．確定你用 root 簽入然後執行 make install． 這將編譯 Java 程式，修改 java.cgi 指令稿以符合你的系統，並且 將程式安裝進適當的位置． 如果你希望擁有本文的 HTML 版本以及一份 HTML 測 試文件，改用 make all． 2.5 測試你的安裝 由本套件安裝的 HTML 文件叫做 javacgitest.html, javaemailtest.html 以及 javahtmltest.html． 如果你在前節使用 make all，它們會放在你於 Makefile 中指定的 WEBDIR 目錄中． 如果不是，你可以執行 make test 從 javacgitest.html-dist, javaemailtest.html-dist 以及 javahtmltest.html-dist 來建立它們． 當你確定你的安裝可以正確運作後，你可能希望從你的 JAVACGI 目錄移除 CGI_Test, Email_Test 以及 HTML_Test 類別，還有從 WEBDIR 目錄移除 javacgitest.html, javaemailtest.html 以及javahtmltest.html，因為它們會 顯示應該只有伺服器管理者才看得到的使用者資訊． 3. 設定伺服器以執行 Java CGI 程式 (簡略篇) 1. 從 [12]ftp://ftp.orbits.com/pub/software/java_cgi-0.5.tgz. 取回 Java CGI 套件．(版本號碼可能會改變．) 2. 用這個指令解開套件: gzip -dc java_cgi-0.5.tgz | tar -xvf - (如果版本號碼改變了，就改用那套件裡的．) 3. 修改在新產生的 java_cgi-0.5 目錄裡的 Makefile 以符合你的系統． 4. 以 root 身份，執行 make install． 這將編譯 Java 程式，加上你系統特 定的資訊並安裝許多檔案． 如果你希望擁有本文的 HTML 版本以及一份 HTML 測試文件，改用 make all． 5. 然後應該就可以用了． 4. 執行一個 Java CGI 程式 4.1 以 CGI 模式執行 Java 程式的障礙 從 web 伺服器執行 Java 程式有兩個主要的問題: 你不能像一般執行檔一樣執行 Java 程式 你必需執行 Java 的執行時刻(run-time)解譯器並且以命令列的方式提供初始類 別(程式執行所需)． 在一個 HTML form 裡面沒有辦法提供命令列給 web 伺服器 ． Java 程式沒有一般的方法可以取得環境變數 Java 程式所需的每個環境變數都必需被傳入． (在 Java 程式中)沒有類似 C 語 言的 getenv() 函數． 4.2 執行 Java CGI 解決問題 為了處理這些困難，我寫了一個 CGI 指令稿程式，提供 Java 解譯器所需的資訊 ． java.cgi 指令稿 這個指令稿管理 HTTP 伺服器與你希望使用的 Java CGI 程式之間的互動． 它從 server 端提供的資料中取出你想要執行程式的名稱． 它將所有的環境變數資料 將髹到一個暫存檔裡．然後，它將這個檔案以及程式名稱加命令列中， 執行 Java 的執行時刻解譯器． java.cgi 指令稿的設定與安裝在 [13]決定你的本地目錄策略 一節說明． 從 HTML form 中引發 java.cgi 使用 Java CGI 程式的 HTML form 以下面的方式指定其行為:
其中 /cgi-bin/ 是你本地端的 CGI 二進位執行檔目錄， java.cgi 是允許我們 從 web 上執行 Java 程式的前端， 而 CGI_Test 是一個欲執行的 Java 程式名 稱的例子． 5. 使用 Java CGI 類別 目前為止支援三個主要類別 -- [14]CGI, [15]Email 以及 [16]HTML． 我正在考 慮分別加上處理 MIME 格式輸入與輸出的類別 -- MIMEin & MIMEout． 也有一些用來支援和測試的類別． [17]CGI_Test, [18]Email_Test 以及 [19]HTML_Test 是拿來測試你的安裝用的． 你也可拿來當做你自己程式中使用這 些類別庫的起點． [20]Text 類別是 Email 與 HTML 的基底類別． 5.1 CGI 類別語法 public class CGI 類別描述 CGI 類別持有的「CGI 資訊」 -- web 伺服器所設定的環境變數以及按下 submit 時由 form 所傳送來的名稱/數值． 所有的資訊都被存放在類別物件 Properties 中． 這個類別位於 ``Orbits.net'' 包裝(package)中． 成員摘要 _________________________________________________________________ CGI() // 建構子 getNames() // 取得名稱的串列 getValue() // 取得指定名稱的值 _________________________________________________________________ 請參閱 CGI_Test. CGI() 目的 建構一包含可用 CGI 資料的物件 語法 public CGI() 描述 當一 CGI 物件被建立時，所有可用的 CGI 資料被存放在新物件的局部儲 存空間中． getNames() 目的 列出已定義對應值的名稱． 語法 public Enumeration getNames () 描述 提供所有已定義對應值的名稱的完整列表． 返回 所有名稱的 Enumeration 物件． getValue() 目的 取回所指定對應於 name 的 value． 語法 public String getValue ( String name ) 描述 這個方法提供由 HTML form 送入的 names 與 values 之間的對應． 參數 name 所選擇的鍵值． 返回 一個包含對應值的 String 物件． 5.2 CGI_Test 這個類別提供兩個功能，一個如何使用 CGI 類別的例子以及一個用來確定 Java CGI 套件運作正常的測試程式． 成員摘要 _________________________________________________________________ main() // Program main(). _________________________________________________________________ 請參閱 [21]CGI. main() 目的 提供 main() 方法． 語法 public static void main( String argv[] ) 描述 這是 CGI 程式的入口，只不過返回可用的名稱/數值對與其現值的列表． 參數 argv[] 由 java.cgi 指令稿傳入的參數．目前未使用． 5.3 Email 類別語法 public class Email extends Text 類別描述 訊息由 Text 類別的 add*() 方法所建立，加入電子郵件專用的方法． 完成後， 訊息被送到它的目的地． 這個類別位於 ``Orbits.net'' 包裝中． 成員摘要 _________________________________________________________________ Email() // 建構子 send() // 送出電子郵件訊息 sendTo() // 增加訊息的目的地 subject() // 設定訊息的主題 _________________________________________________________________ 請參閱 Email_Test, Text. Email() 目的 建立一包含電子郵件訊息的物件． 語法 public Email() 描述 建立一空的訊息以利由此類別方法加以完成． 請參閱 Text. send() 目的 送出電子郵件訊息． 語法 public void send () 描述 本方法編排並送出訊息．如果目的位址還未設定，將不會有動作發生． sendTo() 目的 增加本訊息的目的地． 語法 public String sendTo ( String address ) 描述 將 address 加入到目的地列表中．一份電子郵件目的地的數目是沒有限 制的． 不過我相信如果你建了過大的列表，你將可能會超過你的郵件傳 送代理程式(MTA) 所能接受的大小或用光你的記憶體． 參數 address 本訊息欲送達的一個目的地． subject() 目的 設定本訊息的主題． 語法 public void subject ( String subject ) 描述 本方法設定電子郵件的 Subject: 欄位． 如果呼叫超過一次以上，會使 用最後一次呼叫的結果． 參數 subject Subject: 欄位的文字． 5.4 Email_Test 這個類別提供一個如何使用 Email 類別的例子以及一個用來確定 Java CGI 套件 運作正常的測試程式． 成員摘要 _________________________________________________________________ main() // Program main(). _________________________________________________________________ 請參閱 [22]Email. main() 目的 提供 main() 方法． 語法 public static void main( String argv[] ) 描述 這是 CGI 程式的入口，返回可用的名稱/數值對與其現值的列表． 它也 將列表送到由 Email 變數所指定的位址． 參數 argv[] 由 java.cgi 指令稿傳入的參數．目前未使用． 5.5 HTML 類別語法 public class HTML extends Text 類別描述 訊息由 Text 類別的 add*() 方法所建立，並加入 HTML 專用的方法． 完成後， 訊息被送到它的目的地． 目前，還沒有錯誤檢查機制以確保列表建立的方法被以正確的順序使用． 因此程 式設計者必須自行確定沒有違反 HTML 的語法． 這個類別位於 ``Orbits.net'' 包裝中． 成員摘要 _________________________________________________________________ HTML() // 建構子 author() // 設定文件作者的名字 definitionList() // 起始一定義列表 definitionListTerm() // 在定義列表中增加一項目 endList() // 結束列表 listItem() // 在列表中增加一項目 send() // 送出此 HTML 訊息 title() // 設定文件標題的文字 _________________________________________________________________ 請參閱 HTML_Test, Text. HTML() 目的 建立一包含 HTML 訊息的物件． 語法 public HTML() 描述 建立一空的訊息以利由 HTML 方法加以完成． 請參閱 Text. author() 目的 設定文件作者的名字． 語法 public void author ( String author ) 描述 將文件的作者名字設定為 author． 參數 author 用來作為此訊息作者的文字． 請參閱 title(). definitionList() 目的 起始一定義列表． 語法 public void definitionList () 描述 起始一定義列表． 一個定義列表是一種特別的列表，列表中的每一項是 由 項目 其後跟著定義的 文字 所形成的． 一定義列表的起始應跟著(至 少)一項目/文字配對以及一個 endList() 方法的呼叫． 請注意，目前列 表不能是巢狀的． 請參閱 definitionListTerm(), endList(), listItem(). definitionListTerm() 目的 在定義列表中增加一項目． 語法 public void definitionListTerm () 描述 在定義列表中增加一項目． 目前列表的項目部份的文字應該在此方法被 呼叫後並且在對應的 listItem 方法被呼叫前加入． 請參閱 definitionList(), listItem(). endList() 目的 結束一列表． 語法 public void endList () 描述 本方法結束一列表．注意，目前列表不能是巢狀的． 請參閱 definitionList(). listItem() 目的 在列表中增加一項目． 語法 public void listItem () public void listItem ( String item ) public boolean listItem ( String term, String item ) 描述 在列表中增加一項目． 如果使用第一種形式，目前列表項目的文字應在 此方法被叫後並在任何其它列表方法被呼叫前加入． 在第二及第三種形 式中，item 文字被指定為方法的參數而不是在其後被加入． 第三種形式 是定義列表專用並且同時指定列表的項目與定義文字部份． 參數 item 此列表項目的文字． term 此定義列表的項目部份的文字． 請參閱 definitionList(), definitionListTerm(), endList(). send() 目的 送出此 HTML 訊息． 語法 public void send () 描述 送出此 HTML 訊息． title() 目的 設定文件標題的文字． 語法 public void title ( String title ) 描述 設定此文件的標題文字． 參數 title 此文件標題的文字． 請參閱 author(). 5.6 HTML_Test 這個類別提供一個如何使用 HTML 類別的例子以及一個用來確定 Java CGI 套件 運作正常的測試程式． 成員摘要 _________________________________________________________________ main() // Program main(). _________________________________________________________________ 請參閱 [23]HTML. main() 目的 提供 main() 方法． 語法 public static void main( String argv[] ) 描述 這是 CGI 程式的入口，返回在一 HTML 文件中可用的名稱/數值配對與其 現值的列表，並將每一名稱/數值配對顯示在一定義列表的元素裡． 參數 argv[] 由 java.cgi 指令稿傳入的參數．目前未使用． 5.7 Text 類別語法 public abstract class Text 類別描述 本類別為 [24]Email 與 [25]HTML 的基礎類別． 訊息以此類別的方法建立，並 以衍生類別的方法完成並編排． 這個類別位於 ``Orbits.net'' 包裝中． 成員摘要 _________________________________________________________________ Text() // 建構子 add() // 加入文字到此物件 addLineBreak() // 加入分行符號 addParagraph() // 加入分段符號 _________________________________________________________________ 請參閱 [26]Email, [27]HTML. add() 目的 在此項目中加入文字． 語法 public void add ( char addition ) public void add ( String addition ) public void add ( StringBuffer addition ) 描述 在這個文字項目的內容中加入 addition． 參數 addition 加入此文字項目的文字． 請參閱 addLineBreak(), addParagraph(). addLineBreak() 目的 強迫在目前文字位置分行． 語法 public void addLineBreak () 描述 在目前位置加入一分行符號． 請參閱 add(), addParagraph(). addParagraph() 目的 起始一新的段落． 語法 public void add () 描述 在目前的文字位置起始一新的段落． 請參閱 add(), addLineBreak(). 6. 未來的計畫 * Email 類別的擴充: Email( int capacity ) 用來當我們知道需多少空間來儲存訊息時． sendTo( String [] address ) 增加原始電子郵件目的地的列表． sendCc( String address ) 增加一個複製電子郵件目的地． sendCc( String [] address ) 增加複製電子郵件目的地的列表． sendBcc( String address ) 增加一個 Blind Carbon-Copy 的電子郵件目的地． sendBcc( String [] address ) 增加 Blind Carbon-Copy 的電子郵件目的地列表 * HTML 類別的擴充: HTML( int capacity ) 用來當我們知道需多少空間來儲存訊息時． public void unorderedList() 起始一無序列表． public void orderedList() 起始一有序列表． public void directoryList() 起始一目錄列表． public void menuList() 起始一選單列表． void anchor( String anchorName ) 指定一錨(anchor)． void link( String url, String text ) 指定一連結． void applet( String url, String altText ) 指定一 applet 連結． * 允許巢狀的 HTML 列表． * 增加錯誤檢查碼以強迫修正 HTML 列表格式碼的順序． * 環境變數資料的檔案位置應能由 Makefile 設定． * 除去在處理 GET 方法的資料傳送時出現之假的空名稱/數值對． * 考慮讓 CGI 實作 java.util.Enumeration 界面以依序地提供變數名稱． * 加入一 Test 類別，使用本套件中的每個方法． * 說明 CGI_Test, Email_Test 與 HTML_Test 如何相互建立以提供偵錯目的用 的漸進測試． * 說明如何測試使用本套件的每一個特徵． 7. 版本修改記錄 7.1 由 0.4 到 0.5 的修改 * 更新文件與註解以反應新釋出的版本。 7.2 由 0.3 到 0.4 的修改 * 增添 HTML 類別提供的基本功能． * 增加 HTML_Test 類別與 javahtmltest.html-dist． * 增加 HTML 方法來處理定義列表． 7.3 由 0.2 到 0.3 的修改 * 加入 Text 與 Email 類別． HTML 也被加入，但此時只是一小部份而已． * 將不同的類別放入包裝中． 主要的類別在 Orbits.net.*，支援用的類別 Text 放在 Orbits.text.Text． * 將 CGItest 改為 CGI_Test． * 增加 Email_Test 類別． 7.4 由 0.1 到 0.2 的修改 * 環境變數被放入一暫存檔中而不是勉強擠入 Java 解譯器的命令列裡． CGI 類別與 java.cgi 已被修改． * 將 javacgitest.html 文件加入成為套件的一部份． * 安裝時由 make 所修改的檔案全都以結尾 -dist 來命名． References 1. mailto:javacgi-document@orbits.com 2. http://www.phys.ntu.edu.tw/~cwhuang/pub/ 3. mailto:cwhuang@phys.ntu.edu.tw 4. http://www.orbits.com/software/Java_CGI.html 5. ftp://ftp.orbits.com/pub/software/java_cgi-0.5.tgz 6. http://www.orbits.com/software/Java_CGI.html 7. mailto:javacgi-document@orbits.com 8. mailto:javacgi-request@orbits.com 9. file://localhost/tmp/zh-sgmltools.22000/Java-CGI-HOWTO.txt.html#install-short 10. file://localhost/tmp/zh-sgmltools.22000/Java-CGI-HOWTO.txt.html#mailing-list 11. ftp://ftp.orbits.com/pub/software/java_cgi-0.5.tgz 12. ftp://ftp.orbits.com/pub/software/java_cgi-0.5.tgz 13. file://localhost/tmp/zh-sgmltools.22000/Java-CGI-HOWTO.txt.html#make-programs 14. file://localhost/tmp/zh-sgmltools.22000/Java-CGI-HOWTO.txt.html#cgi-class 15. file://localhost/tmp/zh-sgmltools.22000/Java-CGI-HOWTO.txt.html#email-class 16. file://localhost/tmp/zh-sgmltools.22000/Java-CGI-HOWTO.txt.html#html-class 17. file://localhost/tmp/zh-sgmltools.22000/Java-CGI-HOWTO.txt.html#cgi-test-class 18. file://localhost/tmp/zh-sgmltools.22000/Java-CGI-HOWTO.txt.html#email-test-class 19. file://localhost/tmp/zh-sgmltools.22000/Java-CGI-HOWTO.txt.html#email-test-class 20. file://localhost/tmp/zh-sgmltools.22000/Java-CGI-HOWTO.txt.html#text-class 21. file://localhost/tmp/zh-sgmltools.22000/Java-CGI-HOWTO.txt.html#cgi-class 22. file://localhost/tmp/zh-sgmltools.22000/Java-CGI-HOWTO.txt.html#email-class 23. file://localhost/tmp/zh-sgmltools.22000/Java-CGI-HOWTO.txt.html#html-class 24. file://localhost/tmp/zh-sgmltools.22000/Java-CGI-HOWTO.txt.html#email-class 25. file://localhost/tmp/zh-sgmltools.22000/Java-CGI-HOWTO.txt.html#html-class 26. file://localhost/tmp/zh-sgmltools.22000/Java-CGI-HOWTO.txt.html#email-class 27. file://localhost/tmp/zh-sgmltools.22000/Java-CGI-HOWTO.txt.html#html-class