Package javax.naming.ldap

为提升扩展操作和控制支持。

See: 描述

接口摘要

接口	描述
Control	这是一个提升控制接口中定义的 RFC 2251。
ExtendedRequest	这是一个扩展接口提升操作请求的定义在 RFC 2251。
ExtendedResponse	这个接口代表一个LDAP扩展操作响应的定义在 RFC 2251。
HasControls	该接口返回控件对象返回NamingEnumerations。
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	这类实现的LDAPv3扩展要求STARTTLS定义在 Lightweight Directory Access Protocol (v3): Extension for Transport Layer Security用于STARTTLS的对象标识符是1.3.6.1.4.1.1466.20037没有扩展请求值定义。
StartTlsResponse	这类实现的LDAPv3扩展响应定义为将 Lightweight Directory Access Protocol (v3): Extension for Transport Layer Security STARTTLS的对象标识符是1.3.6.1.4.1.1466.20037没有扩展响应值定义。
UnsolicitedNotificationEvent	这类代表一个事件来响应一个不请自来的LDAP服务器发送解雇通知。

异常摘要

异常	描述
LdapReferralException	这个抽象类是用来表示一个LDAP查询的例外。

Package javax.naming.ldap Description

为提升扩展操作和控制支持。

这个包的扩展目录操作的java命名和目录interface^TM（JNDI）。 JNDI提供命名和目录的功能，用java编程语言编写的应用程序。它被设计为独立于任何特定的命名或目录服务实现。因此，各种各样的服务-新的，新兴的，已经部署的-可以以一种常见的方式进行访问。

这个包是应用和服务供应商处理LDAPv3扩展操作和控制，所定义的RFC 2251。此包中的核心接口LdapContext，定义方法进行扩展操作和处理控件的背景。

扩展操作

此包定义了代表论点扩展的操作界面和接口ExtendedRequest，ExtendedResponse代表扩展操作的结果。一个扩展的响应总是成对的一个扩展的请求，但不一定是相反的。也就是说，你可以有一个扩展的请求，没有相应的扩展响应。

一个应用程序通常不直接处理这些接口。相反，它涉及实现这些接口的类。应用程序获取这些类是部分曲目的扩展操作规范通过因特网，或从目录供应商供应商特定的扩展操作。请求类应该有一个接受类型安全和用户友好的方式的参数的构造函数，而响应类应该有访问类型安全和用户友好的方式响应的数据的方法。在内部，请求/响应类处理编码和解码的误码率值。

例如，假设一个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;
    }
}

控制

这个包定义了代表LDAPv3控制接口 Control。它可以被发送到LDAP服务器控件（请求控制）或控制返回LDAP服务器（控制）。不同于扩展的请求和响应，不必在请求控制和响应控制之间进行任何的配对。您可以发送请求控制，并期望没有响应控制返回，或在不发送任何请求控件的同时接收响应控件。

一个应用程序通常不直接处理这个接口。相反，它涉及实现此接口的类。应用程序获取控制班作为控制标准的剧目，通过因特网的一部分，或从目录供应商供应商特定的控件。请求控制类应该有一个接受类型安全和用户友好的方式的参数的构造函数，而响应控件类应该有一个用于获取类型安全和用户友好方式响应的数据的访问方法。在内部，请求/响应控制类处理编码和解码的误码率值。

例如，假设一个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服务器发回一个“改变”的控制响应的改造是成功的。这将使应用程序可以使用该功能提供一个类ChangeIDControl。一个应用程序将执行一个更新，然后尝试获取更改的身份证。

// 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类。的 VendorXControlFactory将用于服务供应商时，供应商接收响应控件从LDAP服务器。

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