Sun ONE Application Server 7 管理員指南

本章描述 Sun ONE Application Server 使用的 J2EE 資源，並論述建立與管理這些資源所使用的方法。

關於 J2EE 命名服務與資源

包含 EJB、Web 應用程式元件與應用程式用戶端的 J2EE 應用程式可以存取廣泛的資源，例如，資源管理程式、資料來源 (例如 SQL 資料來源)、連線 Factory、郵件階段作業、Java Message Service (JMS) 目標物件以及 URL 連線 Factory。J2EE 平台透過 Java 命名與目錄 (JNDI) 命名服務向應用程式展示此類資源。

JDBC 資料來源

JDBC 資料來源是 J2EE 資源，您可以使用 Sun ONE Application Server 來建立並管理該資源。

JDBC API 是與關係資料庫系統具有連接性的 API。JDBC API 具有兩個元件：

JDBC DataSource 物件表示以 Java 程式設計語言撰寫的資料來源。從基本上來說，資料來源是儲存資料的設備。可以如大公司複雜的資料庫一樣複雜，也可以如具有欄和列的檔案一樣簡單。JDBC 資料來源是可以透過 Sun ONE Application Server 建立並管理的 J2EE 資源。

Java 郵件階段作業

JMS 目標是可以透過 Sun ONE Application Server 建立並管理的 J2EE 資源。

許多網際網路應用程式需要發送電子郵件通知的功能。因此，J2EE 平台包含 JavaMail API 及其 JavaMail 服務提供者，JavaMail API 可讓應用程式元件傳送網際網路郵件。JavaMail API 具有兩個元件：

Java 郵件階段作業是可以透過 Sun ONE Application Server 建立並管理的 J2EE 資源。如需關於 Java 郵件階段作業的更多資訊，請參閱關於 Java 郵件資源。

JMS 目標

Java Messaging Service (JMS) 是標準的訊息傳送 API，支援可靠的點對點訊息傳送以及出版訂閱模型。此規格需要可以執行點對點訊息傳送與出版訂閱訊息傳送的 JMS 提供者。

JMS 提供兩種一般類型的管理物件：連線 Factory 與目標。雖然這兩者均封裝特定的提供者資訊，但是其在 JMS 用戶端內的功能大不相同。連線 Factory 用於建立訊息伺服器的連線，而目標物件用於識別 JMS 訊息傳送服務使用的實體目標。

關於 Java 命名與目錄介面 (JNDI)

本章節論述 Java 命名與目錄介面 (JNDI)。Java 命名與目錄介面 (JNDI) 是存取各種命名與目錄服務的應用程式設計介面 (API)。J2EE 元件透過呼叫 JNDI 查找方法來尋找物件。

JNDI 架構

JNDI 架構由應用程式設計介面 (API) 與服務提供者介面 (SPI) 組成。Java 應用程式使用 JNDI API 存取各種命名與目錄服務。SPI 可讓各種命名與目錄服務以透明方式被插接，從而允許使用 JNDI API 的 Java 應用程式存取其服務。下圖 JNDI 架構簡介列舉可透過 JNDI API 存取的服務：

J2EE 命名服務

JNDI 名稱是一個易懂的物件名稱。透過 J2EE 伺服器提供的命名與目錄服務，這些名稱與其物件相對應。因為 J2EE 元件透過 JNDI API 存取此服務，通常物件易懂名稱指的是物件 JNDI 名稱。Pointbase 資料庫的 JNDI 名稱是 jdbc/Pointbase。啟動該資料庫後，Sun ONE Application Server 會從配置檔案中讀取資訊，並自動在名稱空間中加入 JNDI 資料庫名稱。

需要 J2EE 應用程式用戶端、企業 Bean 與 Web 元件來存取 JNDI 命名環境。

此應用程式元件命名環境是在部署或組合時允許自訂應用程式元件企業邏輯的一種機制。使用此應用程式元件環境可自訂應用程式元件，而無需存取或變更應用程式元件源代碼。

J2EE 容器執行應用程式元件環境，並將其作為 JNDI 命名環境提供給應用程式元件實例。應用程式元件環境使用如下：

應用程式元件企業方法使用 JNDI 介面存取此環境。應用程式元件提供者在部署描述元中宣告所有環境項目，這些項目是應用程式元件期望在運行時間在其環境中提供的項目。

此容器提供儲存應用程式元件環境的 JNDI 命名環境實現，並且還提供讓部署程式建立並管理每個應用程式元件環境的工具。

部署程式使用容器提供的工具初始化在應用程式元件部署描述元中宣告的環境項目。此部署程式可以設定並修改環境項目的值。

在運行時間，此容器可讓應用程式元件實例使用環境命名環境。此應用程式元件實例使用 JNDI 介面取得環境項目值。

每個應用程式元件均定義其自身的環境項目集。在同一容器中應用程式元件的所有實例共用同樣的環境項目。不允許應用程式元件實例在運行時間修改此環境。如需關於 J2EE 容器 (例如 Web 容器與 EJB 容器) 使用 JNDI 命名服務來查看物件的更多資訊，請參閱配置 J2EE 容器。

命名參考與連結資訊

資源參考是部署描述元中的元素，用於識別資源的元件編碼名稱。更具體地來說，編碼名稱參考資源的連線 Factory。在下面一節所提供的範例中，資源參考名稱為 jdbc/SavingsAccountDB。

資源的 JNDI 名稱與資源參考名稱不相同。此命名方法需要您在部署之前對映這兩個名稱，但是也會分離資源中的元件。因為此分離作用，以後元件需要存取另一個資源時，您不必變更程式碼中的名稱。這種靈活性也可讓您更容易從預先存在的元件中組合 J2EE 應用程式。

下表 JNDI 查找及其關聯的參考列示 JNDI 查找以及與其關聯的、由 Sun ONE Application Server 使用的 J2EE 資源之參考。

表格 10-1 JNDI 查找及其關聯的參考
JNDI 查找名稱	關聯的參考
java:comp/env	應用程式環境項目
java:comp/env/jdbc	JDBC DataSource 資源管理程式連線 Factory
java:comp/env/ejb	EJB 參考
java:comp/UserTransaction	UserTransaction 參考
java:comp/env/mail	JavaMail 階段作業連線 Factory
java:comp/env/url	URL 連線 Factory
java:comp/env/jms	JMS 連線 Factory 與目標
java:comp/ORB	應用程式元件共用的 ORB 實例

J2EE 標準部署描述元中的命名參考

命名參考是應用程式使用的字串，用於查找給定的命名環境中之物件。對於每個 J2EE 應用程式來說，均具有命名環境，並且在標準元件部署描述元中配置參考。本章節描述在 Sun ONE Application Server 中使用的標準部署描述元功能。本節包含以下主題：

應用程式環境項目

使用 <env-entry> 定義的環境項目提供指定 J2EE 應用程式部署時間參數的一種方法。請注意，在 Web 應用程式中，可以使用 <context-param> 定義 Servlet 環境初始化參數，但是使用 <env-entry> 是優選的方法，因為應用程式部署程式可以透過明確地指定這些應用程式參數的名稱、類型與值來配置它們。

以下範例描述在 J2EE 標準部署描述元中指定的 <env-entry> 語法：

<env-entry>
<description> Send pincode by mail </description>
<env-entry-name> mailPincode </env-entry-name>
<env-entry-value> false </env-entry-value>
<env-entry-type> java.lang.Boolean </env-entry-type>
</env-entry>

<env-entry-type> 標籤指定此項目的完整類別名稱。此處為 snippet 碼，使用應用程式元件中的 JNDI 查找 <env-entry> (snippet 術語指的是 Servlet/JSP 或實體 Bean 或 IIOP 應用程式用戶端)：

Context initContext = new InitialContext();
Boolean mailPincode = (Boolean)
initContext.lookup("java:comp/env/mailPincode");

// 使用者可以在子環境中使用相對名稱
Context envContext = initContext.lookup("java:comp/env");
Boolean mailPincode = (Boolean)
envContext.lookup("mailPincode");

EJB 參考

除部署描述元支援外，JNDI 命名服務可讓應用程式使用「邏輯」名稱 (稱為 EJB 參考) 對映至企業 Bean 的本地介面，如以下範例所述：

<ejb-ref>
<ejb-ref-name> ejb/EmplRecord </ejb-ref-name>
<ejb-ref-type> Entity </ejb-ref-type>
<home> com.wombat.empl.EmployeeRecordHome </home>
<remote> com.wombat.empl.EmployeeRecord </remote>
<ejb-link> EmployeeEJB </ejb-link> </ejb-ref>

應用程式元件 (例如 JSP) 可以使用 JNDI 存取 EJB 本地物件，如以下範例所述：

Context initContext = new InitialContext();
Context envContext = initContext.lookup("java:comp/env");
Object result = envContext.lookup("ejb/EmplRecord");
EmployeeRecordHome emplRecordHome = (EmployeeRecordHome)
javax.rmi.PortableRemoteObject.narrow(result, EmployeeRecordHome.class);

ejb-ref-name 元素定義在應用程式碼中使用的字串 (如以上提供的範例)。ejb-link 元素將此參考連結至使用在 ejb-jar.xml 中定義的實體 Bean 之 ejb-name 元素定義的目標企業 Bean。在不修改應用程式部署描述元或企業 Bean 描述元的情況下，也可能提供此連結。

資源管理程式連線 Factory 的參考

Factory 是應需要建立其他物件的物件。資源 Factory 可以建立資源物件 (例如資料庫連線或訊息服務連線)。透過標準部署描述元中的 <resource-ref> 元素來配置這些連線。

宣告對 JDBC 連線 Factory 的參考，此 Factory 會傳回 javax.sql.DataSource 物件類型：

<resource-ref>
<description> Primary database </description>
<res-ref-name> jdbc/primaryDB </res-ref-name>
<res-type> javax.sql.DataSource </res-type>
<res-auth> Container </res-auth>
</resource-ref>

<resource-ref>
<description> mail Session </description>
<res-ref-name> mail/Session </res-ref-name>
<res-type> javax.mail.Session </res-type>
<res-auth> Container </res-auth>
</resource-ref>

<res-type> 是資源 Factory 的完全合格類別名稱。<res-auth> 變數的值可以指定為 Container 或 Application。若要瞭解有關配置 Java 郵件階段作業資源 Factory 的更多資訊，請參閱關於 Java 郵件資源。

如果指定 Container，則 Web 容器在將資源 Factory 連結至 JNDI 查找登錄之前會處理此認證。如果指定 Application，則 Servlet 必須以程式化方式處理認證。在描述資源類型的單獨子環境下，查找的不同資源 Factory 如下所示：

以下為 snippet 碼，用於取得自應用程式元件與處理認證的容器之間的 JDBC 連線：

InitialContext initContext = new InitialContext();
DataSource source =
(DataSource) initContext.lookup("java:comp/env/jdbc/primaryDB");
Connection conn = source.getConnection();

請注意，為了確保這些資源參考可以使用，在執行期間，res-ref-name 必須對映至有效的資源 Factory。

資源環境參考

資源環境參考提供透過 JNDI 查找，來存取與資源關聯的管理物件之方法。例如，應用程式可能需要存取 JMS Destination 物件。在標準部署描述元中定義的 <resource-env-ref> 元素可讓應用程式宣告資源需求。

<resource-env-ref> 與 <resource-ref> 元素之間的主要區別在於不存在特定的資源認證需求，資源 Factory 描述元必須備份這兩個元素。

<resource-env-ref>
<description> My Topic </description>
<res-env-ref-name> jms/MyTopic </res-ref-name>
<res-env-ref-type> javax.jms.Topic </res-type>
</resource-env-ref>

InitialContext initContext = new InitialContext();
javax.jms.Topic myTopic =
(javax.jms.Topic) initContext.lookup("java:comp/env/jms/MyTopic");

請注意，為了可以使用這些 resource-env-ref 變數，管理員必須在運行時間使目標資源 Factory 可用。如需關於存取 JMS 主題與佇列目標的更多資訊，請參閱第 11 章「使用 JMS 服務」。

UserTransaction 參考

J2EE 需要容器提供在 JNDI 名稱 java:comp/UserTransaction 下的 UserTransaction 物件執行。UserTransaction 物件可讓應用程式啟動、確定並中斷作業事件。

若要以程式化方式啟動並執行作業事件，元件會執行 JNDI 查找 java:comp/UserTransaction，取得容器預設作業事件協調者的參考。傳回的物件實施 javax.transaction.UserTransaction 介面，並可以用於在此程式中開始、確定、回轉作業事件與查詢作業事件狀態。Sun ONE Application Server 中的 JNDI 執行支援作業事件協調者的查找。如需關於 javax.transaction.UserTransaction 介面的更多資訊，請參閱使用作業事件服務。

初始命名環境

Sun ONE Application Server 中的命名支援主要以 J2EE 1.3 (具有一些加入的增強功能) 為基礎。應用程式元件透過 InitialContext() 建立初始環境時，Sun ONE Application Server 會傳回作為應用程式命名環境控點的物件。進而此物件為 java:comp/env namespace 提供子環境。每個應用程式取得自己的名稱空間，即每個應用程式具有 java:comp/env name 空間，並且在一個應用程式名稱空間中連結的物件與其他應用程式中連結的物件不相衝突。

COSNaming 服務

EJB 互用性協定需要使用 COSNaming 協定透過 JNDI API 查找 EJB 物件。

需要 EJB 容器能夠在 CORBA CosNaming 服務中出版 EJBHome 物件參考。CosNaming 服務必須在定義的 CosNaming 模組中執行 IDL 介面，並且必須允許用戶端透過 IIOP 進行解譯與列示作業。

CosNaming 服務必須滿足 CORBA 互用名稱服務規格中的需求，以向主機、連接埠與物件鍵值提供其根 NamingContext 物件。CosNaming 服務必須能夠對在廣告主機、連接埠與物件鍵值中的根 NamingContext 提供 IIOP 呼叫服務。

需要用戶端容器 (即 EJB、Web 或應用程式用戶端容器) 包含 JNDI CosNaming 服務提供者，該程式使用在互用名稱服務規格中定義的機制與伺服器 CosNaming 服務進行聯絡，並使用標準 CosNaming API 解譯 EJBHome 物件。JNDI CosNaming 服務提供者可以或不能使用 JNDI SPI 架構。JNDI CosNaming 服務提供者必須透過從以下 URL 建立物件參考，來存取伺服器 CosNaming 服務的根 NamingContext：

corbaloc:iiop:1.2@<host>:<port>/<objectkey> (其中 <host>、<port> 與 <objectkey> 是伺服器 CosNaming 服務宣傳的根 NamingContext 之對應值)，或使用對等的機制。

在部署期間，用戶端容器的開發人員應該取得伺服器 CosNaming 服務的主機、連接埠與物件鍵值以及用戶端元件部署描述元中的每個 ejb-ref 元素之伺服器 EJBHome 物件的 CosNaming 名稱 (例如，透過瀏覽伺服器名稱空間)。ejb-ref-name (JNDI 查找呼叫中的用戶端碼使用) 應該連接至 EJBHome 物件的 CosNaming 名稱。在運行時間，用戶端元件 JNDI 查找呼叫使用 CosNaming 服務提供者，此提供者與伺服器 CosNaming 服務進行聯絡，解譯 CosNaming 名稱，並向用戶端元件傳回 EJBHome 物件參考。

由於 EJBHome 物件名稱的範圍在提供的主機與連接埠中存取的 CosNaming 服務之名稱空間內，所以不必結合使用用戶端名稱空間與伺服器容器。

使用 CosNaming 的優點是可以更好地與互用性所需的 IIOP 基礎架構整合，並與非 J2EE CORBA 用戶端與伺服器互用。由於 CosNaming 僅儲存 CORBA 物件，因此，供應商可能將使用其他企業目錄服務存取其他資源。

Sun ONE Application Server 結合了基於 J2EE 1.3 規格的 JNDI 之所有命名資源。

若要支援全域 JNDI 名稱空間 (IIOP 應用程式用戶端可以存取)，Sun ONE Application Server 包含基於 J2EE 的 CosNaming 提供者，它支援 CORBA 參考 (遠端 EJB 參考) 的連結。傳回至 IIOP 用戶端的 InitialContext 是 CosNaming 提供者。Sun ONE Application Server 伺服器實例註冊 IIOP 用戶端查找與連結的實體 Bean。

請注意，Sun ONE Application Server 將儲存在 CosNaming 與本機 JNDI 命名環境中的物件視為暫時物件：即，在每個伺服器啟動以及應用程式重新載入時，所有相關的物件將再次與名稱空間連結。若要瞭解配置 CORBA/IIOP 用戶端支援的更多資訊，請參閱配置 CORBA/IIOP 用戶端伺服器。

JNDI 連線 Factory

對於 J2EE Web 應用程式，web.xml 檔案中的部署描述元是定義應用程式環境項目參考、資源管理程式 (例如 SQL 資料來源) 連線 Factory 參考或 EJB 參考的版面配置區。應用程式使用 J2EE 容器提供的 JNDI InitialNamingContext 查找這類參考。僅對部署描述元進行變更，即不需存取或修改應用程式來源碼，不同的應用程式伺服器環境就可攜帶這些應用程式。同樣，J2EE 需要實體 Bean (ejb-jar.xml) 的部署描述元與 IIOP 應用程式用戶端 (application-client.xml) 成為這些 JNDI 命名參考的主要設備。

連線 Factory 是產生連線物件的物件，其中連線物件可讓 J2EE 元件存取資源。資料庫的連線 Factory 是 javax.sql.DataSource 物件，該物件可建立 java.sql.Connection 物件。

在 Sun ONE Application Server 中，您可以配置存取以下資源與資源 Factory 的方法：

server.xml 的 <resources> </resources> 標籤中指定所有 Sun ONE Application Server 資源 Factory，並且這些 Factory 具有使用 jndi-name 屬性指定的 JNDI 名稱。此屬性用於註冊伺服器範圍的名稱空間中的 Factory。部署程式可以使用 resource-ref-mapping 元素，將使用者指定的應用程式特定資源參考名稱 (在 resource-ref 或 resource-env-ref 元素中宣告) 對映至這些伺服器範圍的資源 Factory。這樣可作出關於在給定的應用程式中使用哪個 JDBC 驅動程式 (與其他資源 Factory) 的部署時間決定。

自訂資源存取本機 JNDI 儲存庫，而外部資源存取外部 JNDI 儲存庫。兩種類型的資源均需要使用者指定的 Factory 類別元素、JNDI 名稱屬性等。在本章節中，我們將論述如何配置 J2EE 資源的 JNDI 連線 Factory 資源以及如何存取這些資源。

建立自訂資源的步驟

在 server.xml 中定義的 custom-resource 元素提供指定自訂伺服器範圍資源物件 Factory 的方式。這類物件 Factory 實施 javax.naming.spi.ObjectFactory 介面。此元素與伺服器範圍名稱空間中使用的 JNDI 名稱 (與其他 Sun ONE Application Server 資源一樣透過 jndi-name 子元素指定)、JNDI 類型、資源 Factory 類別名稱以及用於實例化同一資源 Factory 類別的標準特性集關聯。

您需要確保資源參考的環境參考與 EJB 參考連結至使用 server.xml 中的 custom-resource 與 external-jndi-resource 標籤定義的配置伺服器範圍資源。動態重新部署應用程式元件在 JNDI 命名環境中存在問題。Sun ONE Application Server 將釋放所有特定應用程式的參考，並將所有的新參考重新連結至新安裝的應用程式命名環境中。

在 [JNDI Name] 欄位中，輸入用於存取資源的名稱。該名稱將在 JNDI 命名服務中註冊。

在 [Resource Type] 欄位中，輸入完全合格的類型定義，如以上範例所示。[Resource Type] 定義格式應該如下所示：xxx.xxx。

在 [Factory Class] 欄位中，輸入您要建立的自訂資源之 Factory 類別名稱。[Factory Class] 是使用者指定的 Factory 類別名稱。此類別執行 javax.naming.spi.ObjectFactory 介面。

在 [Description] 欄位中，輸入要建立的資源之描述。此描述是字串值，最多可以為 250 個字元。

標示 [Custom Resource Enabled] 核取方塊，以啟用自訂資源。

按一下 [OK]，以儲存自訂資源。

建立外部 JNDI 資源

在 [JNDI Name] 欄位中，輸入用於存取資源的名稱。該名稱將在 JNDI 命名服務中註冊。

在 [Resource Type] 欄位中，輸入完全合格的類型定義，如以上範例所示。[Resource Type] 定義格式應該如下所示：xxx.xxx。

在 [JNDI Lookup] 欄位中，輸入要在外部儲存庫中查找的 JNDI 值。例如，如果您要建立連線至外部儲存庫，測試 Bean 類別的外部資源，[JNDI Lookup] 可以讀取 cn=testmybean。

在 [Factory Class] 欄位中，輸入 JNDI Factory 類別外部儲存庫。例如， com.sun.jndi.ldap。此類別執行 javax.naming.spi.ObjectFactory 介面。

在 [Description] 欄位中，輸入要建立的資源之描述。此描述是字串值，最多可以為 250 個字元。

標示 [External Resource Enable] 核取方塊，以啟用外部資源。

按一下 [OK]，以儲存自訂資源。

存取外部 JNDI 儲存庫

通常，在 Sun ONE Application Server 中運行的應用程式需要對外部 JNDI 儲存庫中儲存的資源之存取權。例如，一般 Java 物件可以作為每個 Java 綱目儲存在 LDAP 伺服器中。外部 JNDI 資源元素可讓使用者配置這類外部資源儲存庫。外部 JNDI Factory 必須實施 javax.naming.spi.InitialContextFactory 介面。

<資源>

<external-jndi-resource jndi-name="test/myBean"
jndi-lookup-name="cn=myBean"
res-type="test.myBean"
factory-class="com.sun.jndi.ldap.LdapCtxFactory">

對映應用程式資源參考

應用程式特定的資源參考必須對映至預先定義的伺服器範圍資源 Factory。Sun ONE Application Server 特定的資源參考對映元素用於此對映。

在以下範例中，我們將查看 Web 應用程式部署描述元 web.xml，其中資源參考指定給 JDBC DataSource。

<resource-ref>
<res-ref-name> jdbc/EstoreDataSource </res-ref-name>
<res-type> javax.sql.DataSource </res-type>
<res-auth> Container </res-auth>
</resource-ref>

所需的 res-ref-name 也可以對映至容器範圍的 Orcale JDBC 連線資源 Factory，如下所示：

<resource-ref>
<res-ref-name> jdbc/EstoreDataSource </resource-ref-name>
<jndi-name> jdbc/estore/InventoryDB </jndi-name>
</resource-ref>

關於 URL 連線 Factory 資源

URL 連線 Factory 不需要在 server.xml 中定義的任何資源。對應的 Sun ONE Application Server 應用程式 (Web 或 ejb) 部署描述元的 jndi-name 元素指定目標 URL。

例如，讓我們假設 Web 應用程式部署描述元 web.xml 指定 java.net.URL 資源參考，並且此參考對應於 sun-web.xml 中的 URL http://www.sun.com/index.html：

<resource-ref>
<res-ref-name>myURL</res-ref-name>
<res-type>java.net.URL</res-type>
<res-auth>Container </res-auth>
</resource-ref>

<sun-web-app>
<resource-ref>
<res-ref-name>myURL</res-ref-name>
<jndi-name> http://www.sun.com/index.html </jndi-name>
</resource-ref>
</sun-web-app>

對映應用程式資源環境參考

應用程式特定的資源環境參考宣告必須對映至應用程式伺服器運行時間環境中可用的目標資源物件。Sun ONE Application Server 特定的配置檔案中定義的資源環境對映元素讓部署程式如下對映：

<resource-env-ref>
<description> My Topic </description>
<res-env-ref-name> jms/MyTopic </res-ref-name>
<res-env-ref-type> javax.jms.Topic </res-type>
</resource-env-ref>

此參考對映至 server.xml 中定義的 jms/iMQ/Topics/Stocks/SUNW 主題。請參閱「Sun ONE Application Server Administrator's Configuration File Reference」，以取得更多資訊。

<resource-env-ref-mapping>
<res-env-ref-name> jms/MyTopic </res-ref-name>
<jndi-name> jms/iMQ/Topics/Stocks/SUNW </jndi-name>
</resource-env-ref-mapping>

對映 EJB 參考

也可以從 ejb-name 中分離在應用程式碼中使用的實際 ejb-name，使其用於目標企業 Bean。在不想修改 Web 應用程式部署描述元 web.xml 並使用企業 Bean 部署描述元的 ejb-name 時，會特別有用。Sun ONE Application Server 特定的配置在不使用 Sun ONE Application Server 特定部署描述元中的 ejb-ref-mapping 元素的情況下，可讓您將 ejb-ref-name 元素對映至目標 Bean 的 ejb-name。

<ejb-ref>
<ejb-ref-name> ejb/EmplRecord </ejb-ref-name>
<jndi-name> AccountEJB </jndi-name>
</ejb-ref-mapping>

關於持續性管理程式資源

此模組描述持續性，並建立使用 Sun ONE Application Server 支援的可插接式持續性管理程式的框架。

什麼是持續性？

大部分企業應用程式的主要功能是程式化處理永久性資料 (在應用程式之外的長期儲存資料)。雖然可以從暫存記憶體中讀取永久性資料，使用並修改它，但是也可以寫出至關係資料庫或平面檔系統進行長期儲存。

在物件導向程式設計系統中，永久性資料在記憶體中表示為由應用程式碼處理的一個或多個資料物件。一般地，可以透過下圖基本持續性機制所示的多個軟體層，進行資料儲存中的永久性資料與其作為記憶體中永久性資料物件的表示法之間的通訊：

每個資料儲存透過用於設定並維護資料儲存與應用程式之間的連線之驅動程式軟體，具有與外部世界相連接的介面。使用所建立的連線，查詢語言用於擷取資料儲存中的資訊，並將其讀入應用程式，或反之，將應用程式中的資料寫入資料儲存。另一層提供記憶體中資料物件與資料儲存中資訊之間的對映。

透過這種一般機制，程式設計者可以將應用程式使用並處理的永久性資料表示為運行時間物件。此機制支援所有基本的持續性作業，常縮寫為 CRUD：

持續性管理程式的角色

持續性管理程式 (PM) 使用 EJB 容器中的容器管理式持續性負責實體 Bean 的持續性。實體 Bean 提供者負責提供作為抽象類別的實體 Bean 類別。持續性管理程式提供者的工具負責提供具體實施。這些軟體可以透過對抽象實體 Bean 與相關的類別進行子分類，並提供具體實施或利用封裝與授權來實現其功能。

持續性管理程式工具提供的類別負責管理實體 Bean 之間的關係，並管理對其永久性狀態的存取。PM 工具同時還負責提供 java.util.Collection 類別的實施，這些類別用於維護容器管理式的關係 (CMR)。

預先部署 Bean 配置

企業 Java Bean 標準提供兩種類型的實體 Bean 持續性。它們為容器管理式的持續性 (CMP) 與 Bean 管理式的持續性 (BMP)。EJB 2.0 規格不會定義 EJB 伺服器與持續性管理程式之間的標準 API。

本節描述在部署與產生程式碼時的整合需求。可以使用部署平均分配多個項目。一般來說，部署程序可以分為三個主要步驟：配置、產生程式碼與安裝。

必須為 Bean 指定多項特性，包括所使用的持續性機制、持續性供應商與使用中的版本以及持續性機制需要的附加資訊。大多數持續性供應商具有專案的概念，表示所有關聯的 Bean 及其作為單一單元部署的相依類別。在每個專案中可以具有一個特定供應商的 xml 檔案。

支援部署的三個標準檔案包括 ejb-jar.xml、sun-ejb-jar.xml 與 sun-cmp-mappings.xml。在 sun-ejb-jar.xml 中的每個具有 CMP Bean 之 EJB 模組必須具有一個 <pm-descriptors>，並且至少其具有的一個 <pm-descriptor> 元素指定了五個屬性。這五個屬性為 pm-identifier、pm-version、pm-config、pm-class-generator 與 pm-mapping-factory。

Sun ONE Application Server 特定的描述元 (如 sunEjb_jar_2_0.DTD 中的描述元) 定義持續性管理程式相關的標籤。範例 CMP 描述元可能與 Sun ONE Application Server DTD 中定義的描述元類似：

PM 描述元包含一個或多個 pm 描述元，但是必須在任何給定的時間僅使用一個描述元

<!ELEMENT pm-descriptor ( pm-identifier, pm-version, pm-config?, pm-class-generator?,

此元素描述提供 PM 實施的供應商，例如，這可能是 Sun ONE Application Server Transparent Persistence、TopLink、Versant 或 CocoBase：

建立新的持續性管理程式

使用管理介面，您可以建立新的持續性管理程式實例。建立新持續性管理程式實例的步驟：

從管理介面的左窗格中，開啟您要建立新的持續性管理程式之 Sun ONE Application Server 實例，然後從顯示的伺服器元件清單中按一下 [Persistence Manager]。

如果已為 Sun ONE Application Server 的該特定實例建立了任何持續性管理程式，將會看到在管理介面右窗格中顯示的清單。

若要建立新的持續性管理程式，請按一下 [New]。將會看到圖建立新的持續性管理程式中顯示的以下視窗：

圖 10-5 建立新的持續性管理程式

此為應用程式伺服器執行期間使用的 JNDI 名稱，用於尋找代表應用程式的特定持續性管理程式。此名稱必須與 Sun 特定部署描述元的實體 Bean cmp-resource 元素中定義的名稱相同。

在 [Description] 欄位中，提供新持續性管理程式的說明。此欄位的值為字串，最多可以包含 250 個字元。

在 [Factory Class] 欄位中，提供持續性管理程式的 Factory 類別連線。setEntityContext 透過 JNDI 名稱查找來查找此連線 Factory。此 Factory 類別名稱是建立持續性管理程式實例的持續性管理程式 Factory 類別名稱。依預設，將此設定為 Sun ONE Application Server 內部持續性管理程式 Factory 類別。如果您使用替代的實施，必須確保此類別在伺服器類別路徑中可用。

從 [Connection Pool] 下拉式清單中，選取匯集新的持續性管理程式所在的資料庫連線區。使用連線匯集，實體 Bean 可以請求單一連線，並使用它執行多個用戶端執行緒的並行處理描述。與任何其他資料庫存取類似，持續性管理程式將使用連線匯集來改進效能與可延伸性。如果您尚未建立連線區，請選擇現有的連線區或「無選取」。

備註：將自動建立 JDBC 資源以讓 PM 運行時間連結至使用 JNDI 的連線區 - JDBC 資源的 JNDI 名稱將與 PM JNDI 名稱相同，均使用「PM」作為前綴。刪除持續性管理程式也會刪除關聯的 JDBC 資源。

若要啟用持續性管理程式，請標示 [Persistence Manager Enabled] 核取方塊。會立即為指定的連線 Factory 啟用持續性管理程式。

按一下 [OK]，以儲存變更。

關於 JDBC 資源

此模組一般說明有關 JDBC API 的資訊，而具體說明 JDBC 資源及其實施，以及在 Sun ONE Application Server 中的特定用法。

關於 JDBC API

JDBC API 是 Java API，用以虛擬存取任何類型的表格資料。(JDBC 是商標名稱，並不是縮寫，然而，JDBC 常常被認為表示「Java 資料庫連線」)。JDBC API 由類別集與以 Java 程式設計語言撰寫的介面 (提供工具/資料庫開發人員所使用的標準 API) 組成，並且 JDBC API 使得使用 all-Java API 寫入資料庫應用程式成為可能。

JDBC API 使 SQL 敘述很容易發送至關係資料庫系統，並支援所有的 SQL 方言。但是 JDBC 3.0 API 優於 SQL，同時，其可以與其他各種資料來源進行互動，例如資料庫之外的檔案。

JDBC API 的值是應用程式可以虛擬存取任何資料來源並且在任何使用 Java 虛擬機器的平台中執行此應用程式。換句話說，使用 JDBC API，無需寫入一個程式來存取 Sybase 資料庫，無需寫入另一個程式存取 Oracle 資料庫，無需另一個程式存取 IBM DB2 資料庫等。您可以使用 JDBC API 寫入單一程式，並且此程式能夠將 SQL 或其他敘述發送至適當的資料來源。並且，使用 Java 程式設計語言撰寫的應用程式，不必擔心寫入要在不同平台中執行的不同應用程式。Java 平台與 JDBC API 的組合可讓程式設計師只寫入一次程式碼，然後在任何地方執行此程式碼。

JDBC API 的功能？

基於 JDBC 技術的驅動程式 (JDBC 驅動程式) 可以執行以下三個動作：

關於資料庫存取模型

JDBC API 支援資料庫存取的兩層與三層模型。Sun ONE Application Server 結合了更通用的兩層資料庫存取模型。

兩層資料庫存取模型

在兩層資料庫存取模型中，Java applet 或應用程式使用 DBMS 專用協定直接與資料來源對話。此存取模型需要 JDBC 驅動程式，該驅動程式可以與正在存取的特定資料來源通訊。使用者指令將傳送至資料庫或其他資料來源，並且將那些敘述結果發回至使用者。資料來源可以位於使用者透過網路連線的另一台機器上。此配置指的是用戶端/伺服器配置。將使用者機器作為用戶端，儲存資料來源的機器作為伺服器。網路可以是企業內部網路，例如，在公司內部連線員工機器的網路，或者是網際網路。

三層資料庫存取模型

在三層資料庫存取模型中，Java Applet 或應用程式將指令傳送至服務的「中間層」，該層再將指令發送至資料來源。用戶端應用程式透過 HTTP、RM、CORBA 或其他呼叫與中間層通訊。中間層透過 DBMS 專用協定與資料來源進行通訊。資料來源處理指令，並將結果傳回中間層，該層再將其傳回使用者。MIS 指示器發現三層模型具有很大吸引力，因為中間層可以維護對存取的控制，以及維護對公司資料所作的各種更新。另一個優點是其簡化了應用程式的部署，最後，在許多情況下，三層架構可以提供效能優勢。

關於 JDBC 資料來源

DataSource 物件是表示以 Java 程式設計語言撰寫的資料來源。從基本上來說，資料來源是儲存資料的設備。其精密程度可以類似於大公司的複雜資料庫，也可以與具有列與欄的簡單檔案一樣。資料來源可以駐留在遠端伺服器上，或可以在本機桌面機器上。應用程式使用連線存取資料來源，DataSource 物件可以作為 DataSource 實例表示的特定資料來源連線之 Factory。DataSource 介面提供兩種建立與資料來源連線的方法。

DataSource 物件具有識別與描述其所表示的資料來源之特性。同時，DataSource 物件使用 JNDI 命名服務，並且在獨立於使用其的應用程式之外建立、部署並管理此物件。驅動程式供應商將提供作為其 JDBC 2.0 或 3.0 驅動程式產品部分的 DataSource 介面基本執行之類別。

DataSource 物件的特性

DataSource 物件具有識別與描述其表示的真實資料來源之特性集，這些特性包括資料庫伺服器位置、資料庫名稱、用於與伺服器通訊的網路協定等資訊。DataSource 特性遵循 JavaBeans 設計型樣，通常在部署 DataSource 物件時設定這些特性。

為了支援不同供應商之 DataSource 執行的一致性，JDBC 2.0 API 指定了標準的特性集與每個特性的標準名稱。

執行 DataSource 介面的類別實例表示一個特別的資料來源。此實例提供的每個連線將參考同一資料來源。在基本的 DataSource 執行中，對 DataSource.getConnection 方法的呼叫會傳回連線物件，與 DriverManager 功能傳回的連線物件類似，是資料來源的實體連線。

JNDI 提供一致的方法，用於應用程式在網路上查找與存取遠端服務。遠端服務可以是企業服務，包括訊息傳送服務或應用程式特定的服務，但是，JDBC 應用程式主要對資料庫服務感興趣。一旦建立了 DataSource 物件並使用 JNDI 命名服務註冊了該物件，應用程式便可以使用 JNDI API 存取 DataSource 物件，然後該物件用於連線至其所表示的資料來源。

執行連線匯集的 DataSource 物件也會產生 DataSource 類別表示的特定資料來源連線。但是，方法 DataSource.getConnection 傳回的連線物件是對 PooledConnection 物件的處理，而不是實體連線。應用程式僅以通常的方式使用連線物件，但不瞭解使用的是另一種方式。除了匯集的連線應該明確地關閉之外 (適用於所有連線)，連線匯集對應用程式碼無影響。當應用程式關閉匯集的連線時，此連線會結合可重新使用的連線區。下一次在呼叫 DataSource.getConnection 時，如果可以使用一個匯集的連線，則會傳回其中一個連線的處理。因為連線匯集避免在每次請求時建立一個新的實體連線，這有助於使應用程式的執行效能顯著加快。

也可以實施 DataSource 類別來使用分散式作業事件環境。例如，EJB 伺服器支援分散式作業事件，並且需要與此伺服器互動而實施的 DataSource 類別。在這種情況下，DataSource.getConnection 方法傳回可以在分散式作業事件中使用的 Connection 物件。作為規則，EJB 伺服器提供對連線匯集與分散式作業事件的支援。與連線匯集類似，可以內部處理作業事件管理，因此使用分散式作業事件很容易。唯一的需求是在分散作業事件 (涉及兩個或多個資料來源) 時，應用程式無法呼叫作業事件方法 (commit 或 rollback)，也無法在 auto-commit 模式下進行連線。這些限制的原因是作業事件管理程式開始並結束的分散式作業事件在其包含的範圍之內，因此，應用程式無法對作業事件開始或結束的時間進行任何影響。若要瞭解關於 Java 作業事件的更多資訊，請參閱第 9 章「使用作業事件服務」。

註冊 JDBC 資源

您可以使用管理介面或指令行介面在 Sun ONE Application Server 中註冊 JDBC 資源。

使用指令行註冊資源

用於註冊 JDBC 資源的 XML snippet 必須指定一些屬性，如下所示 (引用自 sun-server_7_0.dtd)。

請注意，所有指定的是應用程式參考的 J2EE 應用程式內部資料來源的符號名稱。pool-name 屬性指向具名的儲存區定義，此定義指定資料庫連接性的各個方面。管理員可以使用此啟用的屬性來關閉某些資源。

使用管理介面註冊資源

提供用於建立資源的 JNDI 名稱。

JDBC 資源儲存於 JNDI 儲存庫中，並使用 JNDI 名稱存取。JNDI 名稱在 Java:comp:env/ 下具有明確的根，因此無需指定名稱部分。建議 JDBC 資源 (DataSource) 儲存在 'jdbc' 子環境下，這樣 JNDI 名稱就類似於 jdbc/EmployeeDB_DS。

從 [Pool Name] 下拉式清單的儲存區名稱清單中，選取新資料來源的儲存區名稱。所有註冊的連線區將出現在此下拉式清單中。您選取的儲存區名稱指向具名的儲存區定義，此定義指定資料庫連接性的各個方面。更多的 JDBC 資源可以使用單一的儲存區定義。若要瞭解關於如何配置 JDBC 連線區的更多資訊，請參閱使用管理介面建立新的 JDBC 連線區。

在 [Description] 欄位中，提供描述資料來源用途的簡要說明。此說明不能超過 250 個字元。

標示 [Enabled] 核取方塊，以啟用或停用資料來源。只有啟用了資料來源，才能使用它連線至資料庫。

按一下 [OK]，以註冊新的資料來源，或按一下 [Cancel]，以取消新的資料來源。您按一下取消時，會返回至 JDBC 資源主頁面，從中您可以再次建立新的資料來源。

關於 JDBC 連線

Connection 物件表示與資料庫的連線。連線階段作業包括執行的 SQL 敘述以及透過該連線傳回的結果。單一應用程式可以與單一資料庫具有一個或多個連線，或可以與多個不同的資料庫具有多個連線。

使用者可以透過呼叫 Connection.getMetaData 方法，取得關於 Connection 物件資料庫的資訊。此方法傳回 DatabaseMetaData 物件，該物件包含關於資料庫表格、其支援的 SQL 語法、其儲存的程序以及此連線功能等方面的資訊。

應用程式使用 DataSource 物件產生的 Connection 物件。情況總是這樣，應用程式應該包含「finally」區塊，以確定連線已關閉 (即使已拋出異常)。如果 Connection 物件是匯集的連線，這樣做尤為重要，因為其會確保有效的連線會返回至可用連線的儲存區。以下程式碼分段 (其中 con 是 Connection 物件) 是關閉連線 (如果為有效連線) 的 finally 區塊範例。

請注意，finally 區塊顯示在 try/catch 區塊之後，如下例所示。其中 ds 為 DataSource 物件。

關於 JDBC URL

URL (統一資源位址) 提供尋找網際網路上資源的資訊。可以作為位址。

JDBC URL 提供識別資料來源的方法，以便適當的驅動程式會識別它，然後建立與資料來源的連線。驅動程式撰寫者是實際決定識別特定驅動程式的 JDBC URL 內容的人。使用者無需擔心如何形成 JDBC URL，只需使用 URL (隨使用者要使用的驅動程式一同提供)。JDBC 的任務是為驅動程式撰寫者提供某些慣例，讓其在結構化 JDBC URL 時，遵循這些慣例。

因為各種驅動程式均使用 JDBC URL，因此這些慣例有必要非常靈活。首先，可讓不同的驅動程式使用不同的機制命名資料庫。例如，ODBC 子協定，讓 URL 包含屬性值 (但不是必需的)。

第二，JDBC URL 可讓驅動程式撰寫者在 URL 內對所有需要的連線資訊進行編碼。例如，這可讓要與指定的資料庫進行通訊的 applet 開啟資料庫連線，而不需要使用者執行任何系統管理作業。

第三，JDBC URL 允許使用間接層級。意思是 JDBC URL 可以參考由網路命名系統動態轉換為實際名稱的邏輯主機名稱或資料庫名稱。這可讓系統管理員避免指定特定主機作為 JDBC 名稱一部分。其中有許多不同的網路名稱服務，並且對可以使用哪個服務沒有限制。

此處顯示 JDBC URL 的標準語法。其具有三個部分，用冒號分隔。

驅動程式的名稱或資料庫連接性機制的名稱，可能受一個或多個驅動程式支援。Sub-protocol 名稱的一個重要範例為 ODBC (為指定 ODBC 樣式的資料來源名稱之 URL 所保留)。例如，若要透過 JDBC-ODBC 橋接存取資料庫，可以使用 URL，例如 jdbc:odbc:fred。

在此範例中，subprotocol 為 ODBC，subname fred 為本機 ODBC 資料來源。

如果要使用網路名稱服務 (這樣，JDBC URL 中的資料庫名稱不必為其實際名稱)，命名服務可以為子協定。例如，URL 可以為：

jdbc:dcenaming:accounts-payable

在此範例中，URL 指定本機 DCE 命名服務應該將 accounts-payable 資料庫名稱解譯為一個更特定的名稱 (可用來連線至實際的資料庫)。

識別資料來源的方式。子名稱可以因子協定而有所不同。並且它可以具有驅動程式撰寫者選擇的任何內部語法，包括 sub-subname。使用 subname 為尋找資料來源提供充足的資訊。在上例中，因為 ODBC 提供了資訊的剩餘項目，所以使用 fred 已經足夠。但是遠端伺服器中的資料來源需要更多的資訊。例如，如果在網際網路上存取資料來源，網際網路位址應該作為 subname 一部分包含在 JDBC URL 中，並且應該遵循以下標準的 URL 命名慣例：

//hostname:port/subsubname

假如 dbnet 是用於連線至網際網路上主機的協定，則 JDBC URL 可能會如下所示：

jdbc:dbnet://wombat:356/fred

配置 JDBC 連線區

Sun ONE Application Server 可讓使用者建立具名的 JDBC 連線區。JDBC 連線區定義用於建立連線區的特性。命名儲存區定義後，可以重新使用定義來配置多重 JDBC 資源。每個具名的儲存區定義會在伺服器啟動時產生實體儲存區創設。如果兩個或多個 JDBC 資源指向同一個儲存區定義，在運行時，其會使用同一個連線的儲存區。

您可以使用管理介面與指令行介面建立並配置 JDBC 連線區，如以下章節詳細論述：

使用管理介面建立新的 JDBC 連線區

配置連線區設定

在此頁面的 [General] 區段內，指定基於下表指導原則所提供的參數之值：

表格 10-2 一般設定
參數	描述
Name	連線區名稱。
DataSource ClassName	供應商特定的類別名稱，執行 DataSource 和/或 XADataSource API。
Description	連線區說明。

在此頁面的 [Properties] 區段中，您可以指定標準特性與專用的 JDBC 連線區特性；許多特性是選擇性的。依預設，會提供所有的標準特性名稱。需要查閱資料庫供應商說明文件，以決定需要哪些標準特性與供應商特定特性。

在此視窗的 [Pool Settings] 區段內，指定基於下表指導原則所提供的參數之值：

表格 10-3 連線區設定
參數	描述
Steady Pool Size	請指定必須在儲存區中維護的最小連線數目。在連線指定給請求的執行緒時，會從儲存區中移除該連線，從而減少目前儲存區的大小。同時，固定的儲存區大小也指啟動伺服器時，加入至儲存區的項目數。
Max Pool Size	指定某時某點上儲存區中所允許的最大連線數目。
Pool Resize Quantity	儲存區向固定儲存區大小縮小時，是以批次來重調大小的。此值決定了批次的大小。值越大，會延遲連線的再循環；值越小，效率越低。請注意，儲存區容量僅在一段時間內的一次連線時增加，因此此欄位不會影響連線容量的增加。
Idle Timeout (以秒表示)	連線可以在儲存區中閒置的最大時間 (以秒表示)。這一時間過後，儲存區執行可以關閉此連線。
Max Wait tim	呼叫者在取得連線逾時之前等待的時間。預設等待時間很長，意思是呼叫者可以等待很長一段時間。

在此視窗的 [Connection Validation] 與 [Transaction Isolation] 區段中，基於下表中給定的指導原則，選取連線區的驗證方法以及作業事件隔離方法：

表格 10-4 連線驗證與作業事件隔離
參數	描述
Connection Validation Required	如果核取此欄位，則連線在傳送至應用程式之前會得到驗證。這可讓應用程式伺服器自動重新建立資料庫連線 (由於網路故障或資料庫伺服器當機，資料庫不可用時)。對連線進行驗證，會耗用額外的時間，並且會略微降低效能。
Validation Method	為了驗證資料庫連線，應用程式伺服器可以使用三種方法。需要瞭解資料庫的功能，以決定使用適當的一種方法。三種驗證方法為： auto-commit, meta-data - con.getAutoCommit() 與 con.getMetaData() 方法通常用於驗證連線，但是不幸的是，許多 JDBC 驅動程式快取這些呼叫結果，因此無法始終提供可靠的驗證。您應該洽詢您的供應商，以決定是否快取這些呼叫。 table：此方法需要應用程式伺服器對使用者指定的表格執行查詢。實際查詢為 "select (count *) from <table-name>"。雖然此表格不需要任何列，但是其必須存在並且可以存取。您不應該使用具有大量列的表格或已經常存取的表格。
Table Name	如果您選取了最後的驗證選項，從 [Validation Method] 下拉式清單中選取的 table 會在此處指定表格名稱。
Fail All Connections	如果決定單一連線無效，請核取此方塊，使儲存區中的所有連線無效，然後重新建立連線。如果未核取此方塊，僅有在使用這些連線時，才個別重新建立這些連線。
Transaction Isolation	允許您選取此連線的作業事件隔離層級。如果未指定，儲存區會使用 JDBC 驅動程式提供的預設隔離層級作業。
Guarantee Isolation Level	只有指定了隔離層級，此參數才可用。這確保了從儲存區中取得的任何連線均具有相同的隔離層級。例如，如果在上次使用隔離層級時，程式化變更了連線的隔離層級 (例如，con.setTransactionIsolation)，這種機制會將其變回至指定的隔離層級。

使用指令行介面建立新的 JDBC 連線區

本章節透過使用範例描述使用指令行介面建立 JDBC 連線區的方式。

下表列示需要建立連線區的所有選項，例如伺服器名稱、密碼。範例值已在下表中使用。建議您準備安裝 Sun ONE Application Server 特定的參數，然後再運行本節中解釋的指令。

表格 10-5 使用指令行介面建立 JDBC 連線區所需的選項
所需選項的說明	範例值
應用程式伺服器管理使用者名稱	admin
應用程式伺服器管理密碼	adminadmin
應用程式伺服器管理連接埠	8888
應用程式伺服器機器名稱	sas.sun.com
應用程式伺服器實例名稱	server1
連線區的資料來源類別名稱	oracle.jdbc.xa.client.OracleXADataSource 注意：使用您要為其建立連線區的資料庫之資料來源類別名稱。此範例使用的資料庫為 Oracle。
Jdbc 資源說明範例	Jdbc Resource
連線區說明範例	Jdbc Connection Pool
Jdbc 資源名稱	jdbc/SampleJdbcResource
連線區名稱	SampleJdbcConnectionPool
資料庫使用者名稱	oracle
資料庫密碼	oracle
Jdbc 連線 URL	jdbc:oracle:thin:@oracleserver.sun.com:1521:ORA

此範例建立名為 SampleJdbcConnectionPool 的 JDBC 連線區。在此範例中，使用兩個步驟程序，可以建立 JDBC 連線區，如下所示：

asadmin create-jdbc-connection-pool --user admin_user [--password admin_password] [--host localhost] [--port 4848] [--secure | -s] [--instance instancename] --datasourceclassname classname [--restype res_type] [--steadypoolsize 8] [--maxpoolsize 32] [--maxwait 60000] [--poolresize 2] [--idletimeout 300] [--isolationlevel isolation_level] [--isisolationguaranteed] [--isconnectvalidatereq=false] [--validationmethod auto-commit] [--validationtable tablename] [--failconnection=false] [--description text] [--property (name=value)[:name=value]*] connectionpool_id

asadmin create-jdbc-connection-pool --user admin --password adminadmin --host sas.sun.com --port 8888 --instance server1 --restype javax.sql.XADataSource --datasourceclassname oracle.jdbc.xa.client.OracleXADataSource --description "Sample Jdbc Connection Pool" --property User="oracle":Password="oracle":URL="jdbc\:oracle\:thin\:@oracleserver.sun.com\:1521\:ORA" SampleJdbcConnectionPool

既然已成功建立了 JDBC 連線區，您需要將變更套用至 Sun ONE Application Server 的目前實例。


註	如果您要為新的連線區啟動「全域作業事件支援」，請設定 --restype javax.sql.XADataSource。在 URL 特性中，使用 (\:) 取代冒號 (:)。

asadmin reconfig --user admin_user [--password admin_password] [--host localhost] [--port adminport] [--secure | -s] [--discardmanualchanges=false|--keepmanualchanges=false] instancename

例如，以下指令將變更套用至 server1 (Sun ONE Application Server 的實例)。

asadmin reconfig --user admin --password adminadmin --host sas.sun.com --port 8888 server1

將變更套用至 Sun ONE Application Server 實例後，您便會看到以下訊息。

使用指令行介面管理 JDBC 連線區

您可以使用指令行介面管理 JDBC 連線區及其特性，如本章節中所述：

列示連線區。以下指令列示為 server1 (步驟 2 中使用的 Sun ONE Application Server 實例) 建立的所有連線區。

asadmin list-jdbc-connection-pools --user admin --password adminadmin --host sas.sun.com --port 8888 server1

變更 JDBC 連線區特性。您可以依如下步驟變更 JDBC 連線區特性 (例如，maxPoolSize 特性)：

執行以下指令，以取得為 JDBC 連線區屬性 maxPoolSize 指定的值。

asadmin get -u admin -w adminadmin -H sas.sun.com -p 8888 server1.jdbc-connection-pool.SampleJdbcConnectionPool.maxPoolSize

您執行此指令時，會看到以下結果：

server1.jdbc-connection-pool.SampleJdbcConnectionPool.maxPoolSize = 32

透過執行以下指令，將 MaxPoolSize 值變更為 80：

asadmin set -u admin -w adminadmin -H sas.sun.com -p 8888 server1.jdbc-connection-pool.SampleJdbcConnectionPool.maxPoolSize="80"

依所示指定值後，您便會看到以下訊息：

屬性 maxPoolSize 設定為 80

使用以下指令，將變更套用至 Sun ONE Application Server 實例：

asadmin reconfig --user admin --password adminadmin --host sas.sun.com --port 8888 server1

變更 User 特性。在以下部分範例碼中，您可以將 "User" 特性從 oracle 變更為 System。

asadmin create-jdbc-connection-pool --user admin --password adminadmin --host sas.sun.com --port 8888 --instance server1 --restype javax.sql.XADataSource --datasourceclassname oracle.jdbc.xa.client.OracleXADataSource --description "Sample Jdbc Connection Pool" --property User="oracle":Password="oracle":URL="jdbc\:oracle\:thin\:@oracleserver.sun.com\:1521\ :ORA" SampleJdbcConnectionPool

執行以下指令，以變更 User 特性。

asadmin set -u admin -w adminadmin -H sas.sun.com -p 8888 server1.jdbc-connection-pool.SampleJdbcConnectionPool.property.User="System"

使用者的名稱從 Oracle 變更為 System。

變更使用者名稱之後，執行以下指令來套用變更：

asadmin reconfig --user admin --password adminadmin --host sas.sun.com --port 8888 server1

建立名為 SampleJdbcResource 的 JDBC 資源。您可以建立 JDBC 資源，如下詳述。以下是建立 JDBC 資源的語法：

asadmin create-jdbc-resource --user admin_user [--password admin_password] [--host localhost] [--port 4848] [--secure | -s] [--instance instancename] --connectionpoolid id [--enabled=true] [--description text] [--property (name=value)[:name=value]*] jndiname

請執行以下指令，以建立名為 SampleJdbcResource. 的 JDBC 資源。

asadmin create-jdbc-resource --user admin --password adminadmin --host sas.sun.com --port 8888 --instance server1 --description "Sample Jdbc Resource" --connectionpoolid SampleJdbcConnectionPool jdbc/SampleJdbcResource

您執行此指令時，會建立 JDBC 資源，然後將看到以下訊息：

使用 jndiname = jdbc/SampleJdbcResource 建立了外部 JDBC 資源

下一步，您需要運行以下指令，將變更套用至 Sun ONE Application Server 實例。

asadmin reconfig --user admin --password adminadmin --host sas.sun.com --port 8888 server1

請執行以下指令，以列示實例 server1 中的所有 JDBC 資源。

asadmin list-jdbc-resources --user admin --password adminadmin --host sas.sun.com --port 8888 server1

關於連線匯集

應用程式可以透過 JNDI 首先查找 DataSource，以取得連線。完成此作業的範例碼分段顯示如下：

取得 DataSource 之後，應用程式元件可以用兩種方法取得連線，這要取決於對 J2EE 部署描述元中 <res-auth> 元素的值設定。如果此元素的值為 Container，則應用程式可以使用 ds.getConnection() 方法 (即，不指定任何登入資訊) 取得連線。否則，應用程式必須提供登入資訊，以取得資源管理程式中的連線，如 ds.getConnecion.(userName, password)。

儲存區將提供對 getConnection() 所有請求的服務。將基於 server.xml 中描述的參數集建立 JDBC 連線區。建立連線區後，連線區包含最初可用的連線數目。因此，使用連線區中目前可用的連線，可以滿足 ds.getConnection() 請求。下一個請求 (如果未向連線區傳回先前的連線) 將發現連線區為空，並會建立增量的連線，前提是不超過連線區中指定的最大連線數限制。連線區執行會追蹤建立的連線數。如果 getConnection() 請求發現連線區為空，或者建立的連線數等於儲存區中的最大連線數，將會阻止目前的請求。只有在連線共用不可能的情況下，才發生此類問題，並且繼續，直到連線傳回到連線區為止。

在伺服器仍在執行的情況下，即使資料庫當機後又恢復，連線區仍會繼續正常工作，條件是必須啟用連線驗證，如配置連線區設定中所述。

依您從 [Validation Type] 下拉式清單中選取的值而定，儲存區執行程式執行以下參數：

如果您選擇 auto-commit 作為連線驗證類型，系統會透過執行 conn.getAutoCommit() 方法，查看連線是否有效。如果此方法未拋出 SQLException，那麼會假設 Connection 為有效。auto-commit 為此參數的預設選項。

如果您選擇 meta-data 作為連線驗證類型，那麼將會執行 conn.getMetaData() 方法，以檢查連線的複合資料；如果此方法未拋出 SQLException，那麼會假設 Connection 為有效。

如果您選擇 table 作為連線驗證類型，那麼將執行 "Select * From <table-name>" 查詢。如果此呼叫未拋出 SQLException，那麼會假設連線有效。

如果您啟用 fail-all-connections 特性，發現儲存區中的任何連線無效時，所有連線將關閉，並重新建立。否則，無效與重新建立是惰性的，在使用個別連線時才發生。

儲存區執行也提供再循環儲存區中所有可用連線的功能。因此，如果連線在超過指定的閒置期間仍被閒置，可能會關閉，並使儲存區的大小成為固定儲存區大小。如果儲存區最終仍為閒置，可能導致容器必須重新建立先前的連線，並且使儲存區永遠具有可用連線的固定儲存區。在決定是否設定相對於最大儲存區大小的固定儲存區大小時，您必須記住這一點。

監視 JDBC 連線匯集

您可能需要定期監視儲存區作業，以決定儲存區大小配置是否有效地工作。下表列示可以監視的所有 JDBC 連線匯集參數。

請注意，啟用監視技術與可以監視的屬性有可能在以後的版本中得到改進。

表格 10-6 用於監視的 JDBC 連線區參數
屬性名稱	資料類型	描述
total-threads-waiting	整數	等待 JDBC 連線的執行緒總數。
total-outbound-connections	整數	JDBC 連線驗證的故障總數
total-connections-timed-out	整數	逾時的連線請求總數。

關於連線共用

J2EE 應用程式取得的多個連線使用同一資源管理程式時，儲存區執行將在同一作業事件範圍內提供連線共用。可以從以下範例中瞭解作業事件範圍術語：

Bean_A 啟動作業事件 (Tx1)，並且取得連線。然後 Bean_A 呼叫同一作業事件 (Tx1) 中的 Bean_B 之方法。現在，如果 Bean_B 從同一 DataSource 中取得連線，並且使用同一登入資訊，很顯然，只有在 Bean_A 完成此作業事件時，才可以共用同一連線。同時請注意，只有資源共用範圍在 J2EE 部署描述元中設定為 Shareable 時，才能共用連線。如果不需要連線共用，則資源共用範圍必須在部署描述元中設定為 Unshareable。Sun ONE Application Server 提供連線共用，因為這會提供更佳的效能。

關於 JDBC 作業事件

作業事件由已經執行、完成，然後確定或回轉的一個或多個敘述組成。當呼叫方法 commit 或 rollback 時，目前的作業事件會結束，另一個作業事件會開始。

通常依預設，新的 Connection 物件在 auto-commit 模式中，意思是在完成敘述時，會自動對此敘述呼叫方法 commit。在這種情況下，由於會個別確定每個敘述，所以作業事件僅由一個敘述組成。如果已停用 auto-commit 模式，只有明確地呼叫了 commit 或 rollback 方法時，作業事件才會終止，因此此作業事件將包含上次呼叫 commit 或 rollback 後執行的所有敘述。在第二種情況下，作業事件中的所有敘述已確定或回轉為群組。

方法 commit 使得 SQL 敘述對資料庫所作的任何變更成為永久變更，並且此方法還釋放作業事件具有的任何鎖定。方法 rollback 將放棄那些變更。

在一個作業事件中的兩個更新中，有時您可能不想讓一個變更在一個更新中生效，除非另一個更新也受到了影響。透過停用 auto-commit，並且將兩個更新群組為一個作業事件，可以完成這一動作。如果兩個更新均成功，那麼會呼叫 commit 方法，使這兩個更新為永久更新，如果一個或兩個更新失敗，那麼會呼叫 rollback，在執行更新之前，會回復已存在的值。大多數 JDBC 驅動程式支援作業事件。

在 javax.sql 套裝軟體中的類別與介面使 Connection 物件可以成為分散式作業事件部分，即為與多個 DBMS 伺服器連線的作業事件。為了能夠加入分散式作業事件，Connection 物件必須由 DataSource 物件產生 (已執行此物件，以在中間層伺服器分散式作業事件基礎架構中使用)。與 DriverManager 產生的 Connection 物件不同，由 DataSource 物件產生的 Connection 物件依預設，將停用 auto-commit 模式。從另一方面來說，對 DataSource 物件的標準執行，將產生與 DriverManager 類別產生的物件相同的 Connection 物件。

Connection 物件為分散式作業事件部分時，作業事件管理程式會決定何時對此物件呼叫方法 commit 或 rollback。這樣，當 Connection 物件加入分散式作業事件時，應用程式不應該影響連線開始或結束，例如呼叫方法 Connection.commit 或 Connection.rollback，或開啟連線的 auto-commit 模式。這些會干涉作業事件管理程式處理分散式作業事件。

關於 Java 郵件資源

JavaMail API 允許存取包含在訊息儲存中的電子郵件訊息，並且允許使用訊息傳輸建立與發送電子郵件訊息。網際網路標準 MIME 訊息包含特定的支援。可以透過支援特定儲存與傳輸協定的協定提供者來存取訊息儲存與傳輸。JavaMail API 規格不需要任何特定的協定提供者，但是，JavaMail 包含 IMAP 訊息儲存提供者與 SMTP 訊息傳輸提供者。

JavaMail API 提供抽象類別集，用於定義組成郵件系統的物件。API 定義如 Message、Store 與 Transport 之類的類別。可以延伸 API，並且可以將其分為子類別，以提供新的協定，並在必要時新增功能。此外，API 提供抽象類別的具體子類別。這些子類別，包括 MimeMessage 與 MimeBodyPart，執行廣泛使用的網際網路郵件協定。

JavaMail API 主要由 IMAP、MAPI、CMC、c 用戶端與其他電子郵件訊息傳送系統 API 產生。JavaMail API 支援許多不同的訊息傳送系統執行，如不同的訊息儲存、不同的訊息格式、不同的訊息傳輸。JavaMail API 提供基本類別集與定義用戶端應用程式 API 的介面，開發人員可以將 JavaMail 類別分為子類別，以提供特定訊息傳送系統的執行，如 IMAP、POP3 與 SMTP。

關於 JavaMail 訊息處理程序

JavaMail API 執行以下功能，組成了典型用戶端應用程式的標準郵件處理程序：

建立了由標頭屬性集合組成的郵件訊息以及如在 Content-Type 標頭欄位中指定的某些已知資料類型的資料區塊。JavaMail 使用 Part 介面與 Message 類別來定義郵件訊息。它使用 JAF 定義的 DataHandler 物件包含在訊息中的資料。

建立 Session 物件，用於認證使用者，並且控制存取訊息儲存與傳輸。

將訊息發送至其接收者清單。

從訊息儲存中擷取訊息。

對擷取的訊息執行高層指令。高層指令 (如 view 與 print) 預定透過 JAF-Aware JavaBean 執行。



註	目前，JavaMail 框架不定義支援訊息傳送、安全性、取消連線作業、目錄服務或過濾功能的機制。

透過靜態 Factory 方法配置 JavaMail API 來建立 javax.mail.Session。Sun ONE Application Server 使用 JNDI 請求 Session 物件，並且使用 resource-ref 元素列示其對部署描述元中的 Session 物件的需要。JavaMail API Session 物件被認為是資源 Factory。

提供的訊息傳輸能夠處理 javax.mail.internet.InternetAddress 類型的位址與 javax.mail.internet.MimeMessage 類型的訊息。必須正確配置預設的訊息傳輸，才能使用 javax.mail.Transport 類別的發送方法發送此類訊息。

JavaMail API 的抽象層宣告了預定支援所有郵件系統支援的郵件處理功能之類別、介面與抽象方法。構成抽象層的 API 元素將被分為子類別，並在必要時延伸，以支援標準資料類型，並在必要時與訊息存取協定與訊息傳輸協定相接。

網際網路執行層使用網際網路標準 - RFC822 與 MIME 執行抽象層部分。

關於 JavaMail 的架構元件

Message 類別

Message 類別是抽象的類別，定義屬性集與郵件訊息內容。Message 類別中的屬性指定尋址資訊，並定義內容結構，包括內容類型。內容表示為涉及實際資料的 DataHandler 物件。

Message 類別執行 Part 介面。Part 介面定義需要使用的屬性，用於定義並格式化 Message 物件具有的資料內容，並且與郵件系統成功相接。Message 類別加入了透過訊息傳輸系統進行訊息路由所需的 From、To、Subject、Reply-To 與其他屬性。當 Message 類別包含在資料夾中時，Message 物件具有與之關聯的旗標集。JavaMail 提供支援特定訊息傳送執行的 Message 子類別。

訊息內容是位元組集合，或是位元組集合的參考，封裝在 Message 物件中。JavaMail 並不瞭解訊息內容的資料類型或格式。Message 物件透過中間層 JavaBean 啟動框架 (JAF) 與其內容進行互動。這種分隔可讓 Message 物件處理任何隨意內容，並透過呼叫同一種 API 方法以任何適當的傳輸協定來傳輸它。訊息接收者通常瞭解內容資料類型與格式，並且了解如何處理此內容。

同時，JavaMail API 支援多部分 Message 物件，其中每個 Bodypart 定義其自己的屬性集與內容。

訊息儲存與擷取

訊息儲存在 Folder 物件中。Folder 物件可以包含子資料夾以及訊息，因此提供了樹狀資料夾階層。Folder 類別宣告了擷取、附加、複製與刪除訊息的方法。Folder 物件也可以將事件發送至作為事件偵聽程式註冊的元件。

Store 類別

Store 類別定義具有資料夾階層及其訊息的資料庫。Store 類別還指定存取資料夾與擷取儲存在資料夾中的訊息之存取協定。Store 類別還提供建立資料庫連線、擷取資料夾與關閉連線的方法。執行訊息存取協定 (IMAP、POP3 等) 的服務提供者透過將 Store 類別進行子分類來開始。通常，使用者透過連線至特定的儲存執行，啟動郵件系統中的階段作業。

訊息構成與傳輸

用戶端透過實例化適當的 Message 子類別來建立新的訊息。用戶端會設定如接收者位址與主題等屬性，並且在 Message 物件中插入內容。最後，透過呼叫 Transport.send 方法發送此訊息。Transport 類別以將訊息路由到其目標位址的傳輸代理程式為模型。此類別提供將訊息發送至接收者清單的方法。呼叫 Message 物件中的 Transport.send 方法，會識別基於其目標位址的適當傳輸。

Session 類別

Session 類別定義全域特性與每個使用者郵件相關的特性，這些特性定義郵件啟用用戶端與網路之間的介面。

JavaMail 系統元件使用 Session 物件設定並取得特定特性。Session 類別同時還提供桌面應用程式可以共用的預設認證工作時段物件。Session 類別是最終的具體類別，不能進行子類別分類。Session 類別還可作為執行特定存取協定與傳輸協定的 Store 與 Transport 物件 Factory。透過對 Session 物件呼叫適當的 Factory 方法，用戶端可以取得支援特定協定的 Store 與 Transport 物件。

關於 JavaBean 啟動框架 (JAF)

JavaMail 使用 JavaBean 啟動框架 (JAF) 以便封裝訊息資料，並且處理要與資料互動的指令。與訊息資料互動應該透過不是由 JavaMail API 提供的支援 JAF 之 JavaBean 進行。

使用 JavaBean 啟動框架標準延伸，使用 Java 技術的開發人員可以利用標準服務決定資料任一部分的類型，封裝對它的存取，發現該資料中可用的作業，並且創設適當的 Bean 以執行上述作業。例如，如果瀏覽器取得 JPEG 影像，此框架會啟動瀏覽器將資料流識別為 JPEG 影像，從此類型，瀏覽器會找到並創設可以處理或檢視影像的物件。

JavaBean 啟動框架 API 支援各種 MIME 資料類型。JavaMail API 必須包含 javax.activation.DataContentHandlers，用於下表中指出的 Java 程式設計語言類型對應之以下 MIME 資料類型。

表格 10-7 Java 類型對映的 JavaMail API MIME 資料類型
MIME 類型	Java 類型
Text/Plain	java.lang.String
Multipart/	javax.mail.internet.MIME.Multipart
Message/rfc822	javax.mail.internet.MIME.Message

JavaBean 啟動框架將 MIME 資料類型的支援整合至 Java 平台。MIME 位元組串流可以使用 avax.activation.DataContentHandlerobjects，從 Java 程式設計語言物件轉換或轉換為 Java 程式設計語言物件。可以指定 JavaBean 元件對 MIME 資料作業，例如檢視或編輯資料。JavaMail API 使用 JavaBean 啟動框架來處理電子郵件訊息中包含的資料。雖然使用複雜電子郵件的應用程式可能需要此框架，但典型的 J2EE 應用程式不需直接使用 JavaBean 啟動框架。

關於 JavaMail 配置參數

Sun ONE Application Server 中的 JavaMail 資源使用以下配置參數。這些配置參數是將從 server.xml 檔案的 mail-resource 元素中讀取的名稱、值對。

JavaMail 階段作業參考的 J2EE 部署描述元

使用此伺服器註冊 JavaMail 資源後，可以使用 JNDI 查找在任何 J2EE 應用程式元件中參考此資源。為了部署參考資源管理程式連線 Factory 的應用程式，元件提供者必須在標準的 J2EE 1.3 部署描述元中宣告所有的資源管理程式連線 Factory 參考。

Sun ONE Application Server 部署描述元中的項目

如需參考郵件資源的每個已部署元件，部署程式必須將元件中使用的資源名稱對映於使用命名服務註冊的 DataSource 之實際 jndi 名稱。部署工具可以協助部署程式輕鬆進行此對映。此對映在 Sun ONE Application Server specific xml 中註冊。包含此對映的 Sun ONE Application Server 特定的 XML 分段如下所示：

建立新的 JavaMail 階段作業

您可以使用管理介面配置 JavaMail 階段作業。若要建立與配置新的 JavaMail 階段作業，請執行以下工作：

在 [JNDI Name] 文字欄位中，提供您要建立的 Java 郵件階段作業之 JNDI 名稱。使用此伺服器註冊 Java 郵件資源之後，便可以使用 JNDI 查找在任何 J2EE 應用程式元件中參考此資源。

在 [Mail Host] 文字欄位中，指定預設郵件伺服器的 DNS 名稱。如果協定特定的主機特性不存在，則 Store 與 Transport 物件的連線方法會使用此特性，來尋找目標主機。

在 [Default User] 文字欄位中，指定連線至郵件伺服器時提供的使用者名稱。如果協定特定的使用者名稱特性不存在，則 Store 與 Transport 物件的連線方法會使用此特性，以取得使用者名稱。

在 [Default Return Address] 欄位中，指定目前使用者的預設傳回位址。預設位址應該以下列形式表示：username@host。

在 [Description] 欄位中，提供此 Java 郵件階段作業的說明。

標示 [Java Mail Session Enabled] 核取方塊，以啟用您建立的 Java 郵件階段作業。

按一下 [OK]，以儲存您已經配置的新 JavaMail 階段作業。

配置進階資源特性

您可以使用管理介面為新的 JavaMail 階段作業配置一些附加特性。特性名稱與值對取決於使用中的郵件協定。也可以直接在 server.xml 檔案中指定這些特性。

在 [Store Protocol] 文字欄位中，指定您要在此特定 JavaMail 階段作業中使用的儲存協定，例如 POP3 或 IMAP。

在 [Store Protocol Class] 文字欄位中，指定您已指出的儲存協定之類別名稱，如給定的範例所示。

在 [Transport Protocol] 文字欄位中，指定您要在此特定 JavaMail 階段作業中使用的傳輸協定，例如 SMTP。

在 [Transport Protocol Class] 文字欄位中，指定您已為此階段作業指出的傳輸協定之類別名稱，如以上範例所示。

標示 [Debug Enabled] 核取方塊，以啟用對此 JavaMail 特定階段作業的除錯。啟用此核取方塊會開啟除錯模式。

按一下 [OK]，以儲存附加特性配置。

第 10 章 配置命名與資源