附錄 B

指令行參考

此附錄描述如何從指令行操作 Sun Java^TM Wireless Toolkit for CLDC，並詳述生成和執行應用程式所需的步驟。此外，還描述 Sun Java^TM Wireless Toolkit for CLDC 的憑證管理員公用程式 (名稱為 MEKeyTool)，以及 MIDlet 簽署公用程式 (其名稱為 JadTool) (Java Application Descriptor Tool)。

B.1 先決條件

從指令行生成和執行應用程式之前，請確認您的 Java SE 軟體開發工具組版本是 1.4.2 或更新版本。請確定您的路徑中包含 jar 指令。若要尋找開發工具組的版本，請於指令行執行 jar 指令，然後執行 java -version。

如需更多範例，請參閱示範應用程式 bin 目錄下的 build.bat 與 run.bat 兩個檔案。這些檔案位於：

Windows:	toolkit`\apps\`demo`\bin`
Linux:	toolkit`/apps/`demo`/bin`

toolkit 是 Sun Java^TM Wireless Toolkit for CLDC 的安裝目錄，demo 是一個示範應用程式的名稱。

B.2 開發周期

如需開發 MIDP 應用程式的完整說明，請參閱第 2 章。這一節描述如何從指令行完成開發周期的每一個步驟。

B.2.1 生成

在使用者介面上，生成專案只需一個步驟。但在背景，其實需執行兩個步驟。首先，Java 原始碼檔案編譯成 Java 類別檔案。接著，預先驗證類別檔案，這表示準備好類別檔案，以用於 CLDC KVM。

使用 Java SE 開發工具組的 javac 編譯器編譯 Java 原始碼檔案。您可以使用現有的 Sun Java^TM Wireless Toolkit for CLDC 專案目錄結構。您必須使用 -bootclasspath 選項，告訴編譯器使用 MIDP API，而且您可以使用 -d 選項，指示編譯器放置已編譯類別檔案的位置。

下列範例會示範如何編譯 MIDP 2.0 應用程式，把 src 目錄中的原始碼檔案，編譯成類別檔案放在 tmpclasses 目錄中。為清楚起見，每行多加了換行符號。

Windows

javac  -bootclasspath ..\..\lib\cldcapi10.jar;..\..\lib\midpapi20.jar  -d tmpclasses  src\*.java

Linux

javac  -bootclasspath ../../lib/cldcapi10.jar;../../lib/midpapi20.jar  -d tmpclasses  src/*.java

如果要使用工具組支援的選擇性 API，請把它們的 JAR 檔案加到 -bootclasspath 選項。

如需 javac 的詳細資訊，請參閱 Java SE 文件。

下一個步驟是預驗證類別檔案。在 Sun Java^TM Wireless Toolkit for CLDC 的 bin 目錄中有一個方便的公用程式，叫做 preverify。preverify 指令的語法如下：

preverify [options] files | directories

部分選項如下：

-classpath classpath

指定要載入其類別的來源目錄或 JAR 檔案 (以分號區隔清單)。

-d output-directory

指定輸出類別的目標目錄。預驗證之前，此目錄必須存在。如果未使用此選項，預先驗證器會將類別放置於 output 目錄中。

在編譯範例之後，使用下列指令驗證已編譯的類別檔案。同樣為清楚起見，每行多加了換行符號。

Windows

preverify  -classpath ..\..\lib\cldcapi10.jar;..\..\lib\midpapi20.jar  -d classes  tmpclasses

Linux

preverify  -classpath ../../lib/cldcapi10.jar;../../lib/midpapi20.jar  -d classes  tmpclasses

執行此指令後，完成預先驗證的類別檔案會放置於 classes 目錄中。如果應用程式使用 WMA、MMAPI 或其他版本的 CLDC 或 MIDP，請確定在 classpath 中包含相關的 .jar 檔案。

B.2.2 封裝

若要封裝 MIDlet 套裝軟體，您必須建立一個清單檔案，再生成一個應用程式 JAR 檔案，最後建立一個 MIDlet 套裝軟體描述元。

依 MIDP 規格所指定，建立包含適當屬性的清單檔案。您可以使用任何文字編輯器，建立清單檔案。清單可能含有下列內容：

MIDlet-1: My MIDlet, MyMIDlet.png, MyMIDlet
MIDlet-Name: MyMIDlet
MIDlet-Vendor: My Organization
MIDlet-Version: 1.0
MicroEdition-Configuration: CLDC -1.0
MicroEdition-Profile: MIDP -2.0

建立 JAR 檔案，內含清單及套裝軟體的類別與資源檔案。若要建立 JAR 檔案，請使用 Java SE 軟體開發工具組隨附的 jar 工具。語法如下：

jar cfm file manifest -C class-directory . -C resource-directory .

引數如下：

file - 要建立的 JAR 檔案。

manifest - MIDlet 的清單檔案。

class-directory - 包含應用程式類別的目錄。

resource -directory - 包含應用程式資源的目錄。

例如，若要建立一個名為 MyApp.jar 的 JAR 檔案，其類別位於 classes 目錄中，而資源位於 res 目錄中，請使用下列指令：

jar cfm MyApp.jar MANIFEST.MF -C classes . -C res .

依 MIDP 規格所指定，建立包含適當屬性的 JAD 檔案。您可以使用任何文字編輯器來建立 JAD 檔案。此檔案必須使用 .jad 副檔案名。

備註 - 您必須將 MIDlet-Jar-Size 項目設定為上一個步驟所建立的 JAR 檔案大小。

例如，JAD 檔案可能包含下列內容：

MIDlet-Name: MyMIDlet
MIDlet-Vendor: My Organization
MIDlet-Version: 1.0
MIDlet-Jar-URL: MyApp.jar
MIDlet-Jar-Size: 24601

B.2.3 執行

您可以從指令行執行模擬器。Sun Java^TM Wireless Toolkit for CLDC 的 bin 目錄包含 emulator 指令。emulator 指令的語法如下：

emulator options

一般選項包括：

-help - 顯示有效選項清單。

-version - 顯示關於模擬器版本的資訊。

-Xquery - 在標準輸出位元流上顯示模擬器面板資訊，然後立即結束。此資訊包括面板名稱、螢幕大小和其他功能。

與執行 MIDlet 套裝軟體有關的選項包括：

-Xdevice:skin-name - 在使用指定面板名稱的模擬器上執行應用程式。如需面板名稱清單，請參閱第 4.1 節, 模擬器面板。

-Xdescriptor:jad-file - 在本機上使用指定的 JAD 檔案執行應用程式。

-classpath classpath - 指定執行應用程式必需的程式庫的類別路徑。在本機上執行應用程式時，應使用此選項。

-Dcom.sun.midp.io.http.proxy - 於執行期間設定 HTTP 和 HTTPS 代理伺服器。例如：

-Dcom.sun.midp.io.http.proxy=proxy-host:proxy-port

-Dcom.sun.midp.midlet.platformRequestCommand - 指定應用程式呼叫 URL 時要使用的瀏覽器。例如：

-Dcom.sun.midp.midlet.platformRequestCommand=browser

範例呼叫可能類似於：

emulator -Dcom.sun.midp.midlet.platformRequestCommand=firefox -Xjam:install=URL-to-app-using-platformRequest-method

如果您希望每次都使用同樣的瀏覽器，可以將以下指令行加入至 toolkit/lib/system.config：

com.sun.midp.midlet.platformRequestCommand: 瀏覽器

Windows：在 Windows 中，如果未指定此參數，則將使用預設瀏覽器。

Linux：對於 Linux 則必須指定此參數，因為 Linux 系統一般沒有預設瀏覽器。如果未指定此參數，則當應用程式嘗試開啟 URL 時無任何反應。

-Xjam:command=application - 使用應用程式管理軟體 (Application Management Software, AMS) 從遠端執行應用程式，以使用 OTA 供裝執行。如果未使用引數指定任何應用程式，將執行圖形 AMS。指令如下：

install=jad-file-url | force | list | storageNames|

使用指定的 JAD 檔案將應用程式安裝到裝置上。

以及

run=[storage-name | storage-number]

執行之前安裝的應用程式。應用程式是使用其有效的儲存裝置名稱或儲存裝置號碼來指定的。

remove=[storage-name | storage-number | all]

移除之前安裝的應用程式。應用程式是使用其有效的儲存裝置名稱或儲存裝置號碼來指定的。指定 all，則移除之前安裝的所有應用程式。

transient=jad-file-url - 使用指定的 JAD 檔案來安裝、執行和移除應用程式。指定 transient 將使應用程式安裝並執行，然後再移除三次。

B.2.4 除錯

您可以在模擬器使用下列選項，進行除錯與追蹤。

-Xverbose:trace-options - 依照由逗號分隔的選項，顯示追蹤輸出，如下所示：

gc - 追蹤資源回收

class - 追蹤類別載入

all - 使用全部追蹤選項

-Xdebug - 啟用執行階段除錯。也必須使用 -Xrunjdwp 選項。

-Xrunjdwp:debug-settings - 依照由逗號分隔的除錯設定，啟動 Java 除錯線路協定階段作業。也必須使用 -Xdebug 選項。有效的除錯設定包括：

transport=transport-mechanism - 與除錯程式通訊時使用的傳輸機制。唯一支援的傳輸機制是 dt_socket。

address=host:port - 除錯程式連線的傳輸位址。您可以不提供 host。如果省略 host，即假設主機是 localhost。

server={y|n} - 啟動除錯代理程式做為伺服器。除錯程式必須連接到指定的連接埠。可能值為 y 與 n。目前，只支援 y (模擬器必須做為伺服器)。

B.3 啟動工具組 GUI 元件

Sun Java^TM Wireless Toolkit for CLDC 的元件全部都可以從指令行啟動。每個元件都位於工具組的 bin 目錄中。

表格 B-1 工具組元件指令
指令	描述
`DefaultDevice`	顯示對話方塊，讓您選擇預設模擬器面板
`ktoolbar`	啟動使用者介面。
`prefs`	啟動工具組偏好
`utils`	啟動工具組公用程式視窗

B.4 設定模擬器偏好

您可以使用 emulator 指令的 --Xprefs 選項，從指令行變更模擬器偏好。格式如下：

-Xprefs:filename

提供的 filename 為特性檔案的完整路徑名稱，這個值會置換偏好對話方塊中的值。特性檔案可包含下表所述特性：

表格 B-2 模擬器偏好特性清單
特性名稱	特性說明與法定值
`http.version`	網路配置 > HTTP 版本值： HTTP/1.1 \| HTTP/1.0
`http.proxyHost`	網路配置 > HTTP 位址值：主機名稱
`http.proxyPort`	網路配置 > HTTP 連接埠值： integer
`https.proxyHost`	網路配置 > HTTPS 位址值：主機名稱
`https.proxyPort`	網路配置 > HTTPS 連接埠值： integer
`kvem.memory.monitor.enable`	監視器 > 啟用記憶體監視器值： true \| false
`kvem.netmon.comm.enable`	監視器 > 啟用通訊監視值： true \| false
`kvem.netmon.datagram.enable`	監視器 > 啟用資料封包監視值： true \| false
`kvem.netmon.http.enable`	監視器 > 啟用 HTTP 監視值： true \| false
`kvem.netmon.https.enable`	監視器 > 啟用 HTTPS 監視值： true \| false
`kvem.netmon.socket.enable`	監視器 > 啟用通訊端監視值： true \| false
`kvem.netmon.ssl.enable`	監視器 > 啟用 SSL 監視值： true \| false
`kvem.profiler.enable`	監視器 > 啟用效能評測值： true \| false
`netspeed.bitpersecond`	效能 > 位元/秒組合方塊值： integer
`netspeed.enableSpeedEmulation`	效能 > 啟用流量模擬值： true \| false
`screen.graphicsLatency`	效能 > 圖形基元等待時間值： integer
`screen.refresh.mode`	效能 > 顯示更新 (單選按鈕) 值： default \| immediate \| periodic
`screen.refresh.rate`	效能 > 顯示更新 (滑動軸) 值： integer
`vmspeed.bytecodespermilli`	效能 > 啟用虛擬機器速度模擬 (核取方塊) 值： integer
`vmspeed.enableEmulation`	效能 > 啟用虛擬機器速度模擬 (滑動軸) 值： true \| false
`storage.root`	儲存裝置 > 儲存裝置根目錄值： String (appdb 相對路徑)
`storage.size`	儲存裝置 > 儲存裝置大小值： integer
`mm.control.capture`	MMedia > 音效擷取值： true \| false
`mm.control.midi`	MMedia > MIDI 音調值： true \| false
`mm.control.mixing`	MMedia > 音效混合值： true \| false
`mm.control.record`	MMedia > 音效記錄值： true \| false
`mm.control.volume`	值： true \| false
`mm.format.midi`	MMedia > MIDI 格式值： true \| false
`mm.format.video`	MMedia > 視訊格式值： true \| false
`mm.format.wav`	MMedia > WAV 音效格式值： true \| false
`wma.client.phoneNumber`	WMA > 下一個模擬器的電話號碼值： integer
`wma.server.firstAssignedPhoneNumber`	WMA > 優先指定的電話號碼值： integer
`wma.server.percentFragmentLoss`	WMA > % 隨機訊息分割遺失值： integer
`wma.server.deliveryDelayMS`	WMA > 訊息分割傳送延遲 (ms) 值： integer

B.5 使用安全功能

從指令行也能使用 Sun Java^TM Wireless Toolkit for CLDC 完整的安全功能。您可以調整模擬器的預設保護網域、簽署 MIDlet 套裝軟體和管理憑證。

B.5.1 變更模擬器的預設保護網域

若要調整模擬器的預設保護網域，請在 emulator 指令中使用下列選項：

-Xdomain domain-type

指定 MIDlet 套裝軟體的安全網域。網域類型包括 untrusted、trusted、minimum 和 maximum。

B.5.2 簽署 MIDlet 套裝軟體

JadTool 是一個指令行介面，可依據 MIDP 2.0 規格，使用公開金鑰加密來簽署 MIDlet 套裝軟體。簽署 MIDlet 套裝軟體的過程，是將簽署人憑證與 JAR 檔案的數位簽名加入 JAD 檔案。JadTool 也可以簽署支付款項更新 (JPP) 檔案。

JadTool 只使用來自 Java SE 平台金鑰庫的憑證與金鑰。Java SE 軟體提供指令行工具 keytool 來管理 Java SE 平台金鑰庫。

JadTool 封裝在 JAR 檔案中。若要執行它，請開啟指令提示符號，將目前目錄切換至 toolkit\bin，然後輸入下列指令：

java -jar JadTool.jar command

指令如下：

-help

顯示 JADTool 的使用方法說明。

-addcert -alias alias [-keystore keystore] [-storepass password] [-certnum number] [-chainnum number] [-encoding encoding] -inputjad | inputjpp input-file -outputjad | outputjpp output-file

將指定金鑰庫中金鑰組的憑證加入 JAD 檔案或 JPP 檔案中。

-addjarsig -jarfile jarfile -keystore keystore -alias alias -storepass password -keypass password -inputjad input-jadfile -outputjad output-jadfile

將指定 JAR 檔案的數位簽名加入指定的 JAD 檔案中。-jarfile 的預設值是 JAD 檔案中的 MIDlet-Jar-URL 特性。

-showcert [([-certnum number] [-chainnum number]) |-all [-encoding encoding] -inputjad filename

顯示指定 JAD 檔案中的憑證清單。

-addjppsig -alias alias -keypass password [-keystore keystore] [-storepass password] [-encoding encoding] -inputjpp filename -outputjpp filename

將輸入 JPP 檔案的數位簽名加入指定的輸出 JPP 檔案中。

預設值如下所示：

-encoding -UTF-8

-jarfile - JAD 檔案中的 MIDlet-Jar-URL 特性

-keystore - %HOMEPATH%\.keystore

-certnum - 1

-chainnum - 1

B.5.3 管理憑證

MEKeyTool 用於管理憑證授權單位 (CA) 的公開金鑰，因此在功能上類似 Java SE SDK 隨附的 keytool 公用程式。使用金鑰有助於透過 SSL 進行安全的 HTTP 通訊 (HTTPS)。

使用 MEKeyTool 之前，您必須先具備 Java Cryptography Extension 金鑰庫的存取權。您可以使用 Java SE keytool 公用程式建立一個。

Windows

http://java.sun.com/javase/6/docs/technotes/tools /windows/keytool.html

Linux

http://java.sun.com/javase/6/docs/technotes/tools /solaris/keytool.html

若要執行 MEKeyTool，請開啟指令提示符號，將目前目錄變更為 toolkit\bin，然後輸入下列指令：

Windows：	toolkit`\bin\mekeytool.exe -`command
Linux：	toolkit`/bin/mekeytool -`command

隨後為指令關鍵字。請注意，當 MEKeyTool 從安裝目錄執行時，預設鍵以及您所建立的鍵將在您的個人目錄 workdir\appdb 中常駐。

-help

顯示 MEKeyTool 的使用方法說明。

-import -alias alias [-keystore JCEkeystore] [-storepass storepass] -domaindomain-name

使用指定的 Java Cryptography Extension 金鑰庫密碼，將公開金鑰從指定的 JCE 金鑰庫匯入 ME 金鑰庫。預設 ME 金鑰庫是 workdir\appdb\_main.mks，而預設 Java Cryptography Extension 金鑰庫是 user.home\.keystore。

-list

列出 ME 金鑰庫中的金鑰，包括各金鑰的所有者與有效期限。ME 金鑰庫是 workdir\appdb\_main.mks。

-delete (-owner owner | -number key-number)

從指定所有者的指定 ME 金鑰庫中刪除一個金鑰。ME 金鑰庫是 workdir\appdb\_main.mks。

備註 - Sun Java^TM Wireless Toolkit for CLDC 包含一個名稱為 _main.mks 的 ME 金鑰庫，位於 appdb 子目錄中。此金鑰庫包含預設 Java SE 平台金鑰庫中存在的所有憑證 (此金鑰庫隨附於 Java SE SDK 的安裝中)。

B.6 使用 Stub 產生器

行動用戶端可以使用 Stub 產生器存取 Web 服務。wscompile 工具會產生在 XML (JAX) RPC 用戶端與服務中使用的 Stub、Tie、Serializer 與 WSDL 檔案。此工具會讀取配置檔案，該檔案可指定 WSDL 檔案、模型檔案或編譯的服務端點介面。Stub 產生器的指令語法如下：

wscompile [options] configuration-files

B.6.1 選項

表格 B-3 `wscompile` 指令的選項
選項	描述
`-d` output directory	指定放置所產生輸出檔案的位置
`-f:`features	啟用指定功能
`-features:`features	與 `-f:`features 相同
`-g`	產生除錯資訊
`-gen`	與 `-gen:client` 相同
`-gen:client`	產生用戶端工件 (Stub 等)
`-httpproxy:`host:port	指定 HTTP 代理伺服器 (預設連接埠為 8080)
`-import`	僅產生介面與值類型
`-model` file	寫入內部模型至指定的檔案
`-O`	最佳化產生的程式碼
`-s` directory	指定放置所產生原始碼檔案的位置
`-verbose`	輸出關於編譯器處理內容的訊息
`-version`	顯示版本資訊
`-cldc1.0`	設定 CLDC 版本為 1.0 (預設值)。浮點數及雙精度浮點數變為 String。
`-cldc1.1`	設定 CLDC 版本為 1.1 (可使用浮點數及雙精度浮點數)
`-cldc1.0info`	顯示所有的 CLDC 1.0 資訊和警告訊息。

備註 - 務必指定一個 -gen 選項。-f 選項需要以逗號分隔的功能清單。

表格 B-4 列出可以跟在 -f 選項後面的功能 (以逗號分隔)。wscompile 工具會讀取 WSDL 檔案、編譯的服務端點介面 (SEI) 或模型檔案做為輸入。[檔案類型] 欄說明哪些檔案可以與特定功能共同使用。

表格 B-4 `wscompile` 的受支援指令功能 ( `-f` )
選項	描述	檔案類型
`explicitcontext`	開啟明確的服務環境的對映	WSDL
`nodatabinding`	關閉文字列編碼資料連結	WSDL
`noencodedtypes`	關閉編碼類型資訊	WSDL、SEI、模型
`nomultirefs`	關閉多重參照支援	WSDL、SEI、模型
`novalidation`	關閉匯入的 WSDL 文件完全驗證	WSDL
`searchschema`	積極搜尋子類型模式	WSDL
`serializeinterfaces`	開啟介面類型直接串列化	WSDL、SEI、模型
`wsi`	啟用 WSI-Basic Profile 功能 (預設)
`resolveidref`	解析 `xsd:IDREF`
`nounwrap`	取消不換行

範例

wscompile -gen -d generated config.xml
wscompile -gen -f:nounwrap -O -cldc1.1 -d generated config.xml

指令行參考

B.1 先決條件

B.2 開發周期

B.2.1 生成

B.2.2 封裝

B.2.3 執行

B.2.4 除錯

B.3 啟動工具組 GUI 元件

表格 B-1 工具組元件指令

B.4 設定模擬器偏好

B.5 使用安全功能

B.5.1 變更模擬器的預設保護網域

B.5.2 簽署 MIDlet 套裝軟體

B.5.3 管理憑證

B.6 使用 Stub 產生器

B.6.1 選項

表格 B-3 `wscompile` 指令的選項

表格 B-4 `wscompile` 的受支援指令功能 ( `-f` )

指令行參考

B.1 先決條件

B.2 開發周期

B.2.1 生成

B.2.2 封裝

B.2.3 執行

B.2.4 除錯

B.3 啟動工具組 GUI 元件

表格 B-1 工具組元件指令

B.4 設定模擬器偏好

B.5 使用安全功能

B.5.1 變更模擬器的預設保護網域

B.5.2 簽署 MIDlet 套裝軟體

B.5.3 管理憑證

B.6 使用 Stub 產生器

B.6.1 選項

表格 B-3 wscompile 指令的選項

表格 B-4 wscompile 的受支援指令功能 ( -f )

表格 B-3 `wscompile` 指令的選項

表格 B-4 `wscompile` 的受支援指令功能 ( `-f` )