软件包 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