软件包 javax.naming.ldap 的描述
提供对 LDAPv3 扩展操作和控件的支持。
此包扩展 Java Naming and Directory InterfaceTM (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(respCtlsinstanceof ChangeIDControl) {
ChangeIDControl cctl = (ChangeIDControl)respCtls;
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
}
}
包规范
以下文档可以在 Java 技术站点找到：
JNDI API Document (Postscript)
JNDI API Document (PDF)
从以下版本开始：
1.3
