軟體套件 javax.naming.ldap

提供對 LDAPv3 擴展操作和控制元件的支持。

請參見：
描述

介面摘要

Control	此介面表示在 RFC 2251 中定義的 LDAPv3 控制元件。
ExtendedRequest	此介面表示在 RFC 2251 中定義的 LDAPv3 擴展操作請求。
ExtendedResponse	此介面表示在 RFC 2251 中定義的 LDAP 擴展操作回應。
HasControls	此介面用於返回控制元件，並使物件返回在 NamingEnumeration 中。
LdapContext	此介面表示一個上下文，在該上下文中可以利用 LDAPv3 樣式的控制元件執行操作，並且可以執行 LDAPv3 樣式的擴展操作。
UnsolicitedNotification	此介面表示在 RFC 2251 中定義的未經請求的通知。
UnsolicitedNotificationListener	此介面用於處理 UnsolicitedNotificationEvent。

類別摘要

BasicControl	此類別提供 Control 介面的基本實作。
ControlFactory	此抽象類別表示用於創建 LDAPv3 控制元件的處理器。
InitialLdapContext	此類別是執行 LDAPv3 樣式的擴展操作和控制元件的初始上下文。
LdapName	此類別表示 RFC 2253 指定的標識名。
ManageReferralControl	將參考和其他特殊 LDAP 物件作為普通 LDAP 物件處理的請求。
PagedResultsControl	請求由 LDAP 伺服器以指定的大小批量返回搜尋操作的結果。
PagedResultsResponseControl	指示一批搜尋結果的末尾。
Rdn	此類別表示相對標識名，或 RDN，它是一個 RFC 2253 指定的標識名元件。
SortControl	請求 LDAP 伺服器在返回搜尋操作的結果前對這些結果進行排序。
SortKey	排序鍵及其關聯的排序參數。
SortResponseControl	指示搜尋結果的請求排序是否成功。
StartTlsRequest	此類別實作在 Lightweight Directory Access Protocol (v3): Extension for Transport Layer Security 中定義的 StartTLS 的 LDAPv3 擴展請求。
StartTlsResponse	此類別實作在 Lightweight Directory Access Protocol (v3): Extension for Transport Layer Security 中定義的 StartTLS 的 LDAPv3 擴展回應。
UnsolicitedNotificationEvent	此類別表示為回應 LDAP 伺服器發送的未經請求的通知而觸發的事件。

異常摘要

LdapReferralException

此抽象類別用於表示 LDAP 參考異常。

軟體套件 javax.naming.ldap 的描述

提供對 LDAPv3 擴展操作和控制元件的支持。

此套件擴展 Java Naming and Directory Interface^TM (JNDI) 的目錄操作。 JNDI 向使用 Java 程式語言編寫的應用程序提供命名和目錄功能。它被設計成與任何特定的命名或目錄服務實作無關。因此可以使用共同的方式對多種服務（新的、新出現的及已經部署的服務）進行存取。

此套件用於處理 LDAPv3 擴展操作和控制元件的應用程序和服務提供者，這在 RFC 2251 中定義。此套件中的核心介面是 LdapContext，該介面定義了一些在上下文中執行擴展操作和處理控制元件的方法。

擴展操作

此套件定義了介面 ExtendedRequest 來表示擴展操作的參數，定義了介面 ExtendedResponse 來表示擴展操作的結果。擴展回應始終與擴展請求成對出現，但反過來不一定成立。即擴展請求可以沒有對應的擴展回應。

應用程序通常不直接處理這些介面，而是處理實作 這些介面的類別。應用程序可能作為通過 IETF 進行標準化的擴展操作清單的一部分獲取這些類別，也可能從特定於供應商的擴展操作的目錄供應商獲取這些類別。請求類別應該具有以型別安全的、使用者友好的方式接受參數的建構子，而回應類別應該具有以型別安全的、使用者友好的方式獲取回應資料的存取方法。請求/回應類別在內部處理編碼和解碼的 BER 值。

例如，假定 LDAP 伺服器支持“獲取時間”擴展操作。它將提供諸如 GetTimeRequest 和 GetTimeResponse 之類別的類別，以便應用程序可以使用此功能。應用程序將按以下方式使用這些類別：

GetTimeResponse resp =
    (GetTimeResponse) ectx.extendedOperation(new GetTimeRequest());
long time = resp.getTime();

GetTimeRequest 和 GetTimeResponse 類別可能按照以下方式定義：

public class GetTimeRequest implements ExtendedRequest {
    // User-friendly constructor 
    public GetTimeRequest() {
    };

    // Methods used by service providers
    public String getID() {
        return GETTIME_REQ_OID;
    }
    public byte[] getEncodedValue() {
        return null;  // no value needed for get time request
    }
    public ExtendedResponse createExtendedResponse(
        String id, byte[] berValue, int offset, int length) throws NamingException {
        return new GetTimeResponse(id, berValue, offset, length);
    }
}
public class GetTimeResponse() implements ExtendedResponse {
    long time;
    // called by GetTimeRequest.createExtendedResponse()
    public GetTimeResponse(String id, byte[] berValue, int offset, int length) 
        throws NamingException {
        // check validity of id
        long time =  ... // decode berValue to get time
    }

    // Type-safe and User-friendly methods
    public java.util.Date getDate() { return new java.util.Date(time); }
    public long getTime() { return time; }

    // Low level methods
    public byte[] getEncodedValue() {
        return // berValue saved;
    }
    public String getID() {
        return GETTIME_RESP_OID;
    }
}

控制元件

此套件定義了介面 Control 來表示 LDAPv3 控制元件。它可以是發送到 LDAP 伺服器的控制元件（請求控制元件）或由 LDAP 伺服器返回的控制元件（回應控制元件）。與擴展請求和回應不同，在請求控制元件和回應控制元件之間不存在任何必然的配對關係。可以發送請求控制元件而不要求返迴響應控制元件，也可以收到回應控制元件而沒有發送任何請求控制元件。

應用程序通常不直接處理此介面，而是處理實作 此介面的類別。應用程序可能作為通過 IETF 進行標準化的控制元件清單的一部分獲取控制元件類別，也可能從特定於供應商的控制元件的目錄供應商獲取這些類別。請求控制元件類別應該具有以型別安全的、使用者友好的方式接受參數的建構子，而回應控制元件類別應該具有以型別安全的、使用者友好的方式獲取回應資料的存取方法。請求/回應控制元件類別在內部處理編碼和解碼的 BER 值。

例如，假定 LDAP 伺服器支持“簽章結果”請求控制元件，將此控制元件與請求一起發送時，它將請求伺服器對操作的結果進行數位簽章。它將提供 SignedResultsControl 類別，以便應用程序可以使用此功能。應用程序將按以下方式使用此類別：

Control[] reqCtls = new Control[] {new SignedResultsControl(Control.CRITICAL)};
ectx.setRequestControls(reqCtls);
NamingEnumeration enum = ectx.search(...);

SignedResultsControl 類別可能按照以下方式定義：

public class SignedResultsControl implements Control {
    // User-friendly constructor 
    public SignedResultsControl(boolean criticality) {
        // assemble the components of the request control
    };

    // Methods used by service providers
    public String getID() {
        return // control's object identifier
    }
    public byte[] getEncodedValue() {
        return // ASN.1 BER encoded control value
    }
    ...
}

當服務提供者接收回應控制元件時，它將使用 ControlFactory 類別產生實作 Control 介面的特定類別。

LDAP 伺服器可以利用 LDAP 操作及列舉結果（如列舉或搜尋操作返回的那些結果）發迴響應控制元件。LdapContext 提供方法 (getResponseControls()) 來獲取利用 LDAP 操作發送的回應控制元件，而 HasControls 介面用於檢索與列舉結果關聯的回應控制元件。

例如，假定 LDAP 伺服器發回“更改 ID”控制元件來回應成功修改。它將提供 ChangeIDControl 類別，以便應用程序可以使用此功能。應用程序將執行更新，然後試圖獲取更改 ID。

// Perform update
Context ctx = ectx.createSubsubcontext("cn=newobj");

// Get response controls
Control[] respCtls = ectx.getResponseControls();
if (respCtls != null) {
    // Find the one we want
    for (int i = 0; i < respCtls; i++) {
        if(respCtls[i] instanceof ChangeIDControl) {
            ChangeIDControl cctl = (ChangeIDControl)respCtls[i];
            System.out.println(cctl.getChangeID());
        }
    }
}

供應商可能提供以下 ChangeIDControl 和 VendorXControlFactory 類別。當服務提供者從 LDAP 伺服器接收回應控制元件時，該提供者將使用 VendorXControlFactory。

public class ChangeIDControl implements Control {
    long id;

    // Constructor used by ControlFactory
    public ChangeIDControl(String OID, byte[] berVal) throws NamingException {
        // check validity of OID
        id = // extract change ID from berVal
    };

    // Type-safe and User-friendly method
    public long getChangeID() {
        return id;
    }

    // Low-level methods
    public String getID() {
        return CHANGEID_OID;
    }
    public byte[] getEncodedValue() {
        return // original berVal
    }
    ...
}
public class VendorXControlFactory extends ControlFactory {
    public VendorXControlFactory () {
    }

    public Control getControlInstance(Control orig) throws NamingException {
        if (isOneOfMyControls(orig.getID())) {
            ... 

            // determine which of ours it is and call its constructor
            return (new ChangeIDControl(orig.getID(), orig.getEncodedValue()));
        }
        return null;  // not one of ours
    }
}

套件規範

JNDI API 規範及相關文檔可在 JNDI documentation 中找到。

從以下版本開始：

1.3