|
JNDI 1.2 | ||||||||
| PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES | ||||||||
See:
Description
| Interface Summary | |
| Control | This interface represents an LDAPv3 control as defined in RFC 2251. |
| ExtendedRequest | This interface represents an LDAPv3 extended operation request as defined in RFC 2251. |
| ExtendedResponse | This interface represents an LDAP extended operation response as defined in RFC 2251. |
| HasControls | This interface is for returning controls with objects returned in NamingEnumerations. |
| LdapContext | This interface represents a context in which you can perform operations with LDAPv3-style controls and perform LDAPv3-style extended operations. |
| UnsolicitedNotification | This interface represents an unsolicited notification as defined in RFC 2251. |
| UnsolicitedNotificationListener | This interface is for handling UnsolicitedNotificationEvent. |
| Class Summary | |
| ControlFactory | This abstract class represents a factory for creating LDAPv3 controls. |
| InitialLdapContext | This class is the starting context for performing LDAPv3-style extended operations and controls. |
| UnsolicitedNotificationEvent | This class represents an event fired in response to an unsolicited notification sent by the LDAP server. |
| Exception Summary | |
| LdapReferralException | This abstract class is used to represent an LDAP referral exception. |
Provides support for LDAPv3 extended operations and controls.
This package extends the directory operations of the Java Naming and Directory InterfaceTM (JNDI). JNDI provides naming and directory functionality to applications written in the Java programming language. It is designed to be independent of any specific naming or directory service implementation. Thus a variety of services--new, emerging, and already deployed ones--can be accessed in a common way.
This package is for applications and service providers that deal with LDAPv3 extended operations and controls, as defined by RFC 2251. The core interface in this package is LdapContext, which defines methods on a context for performing extended operations and handling controls.
This package defines the interface ExtendedRequest to represent the argument to an extended operation, and the interface ExtendedResponse to represent the result of the extended operation. An extended response is always paired with an extended request but not necessarily vice versa. That is, you can have an extended request that has no corresponding extended response.
An application typically does not deal directly with these interfaces. Instead, it deals with classes that implement these interfaces. The application gets these classes either as part of a repetoire of extended operations standardized through the IETF, or from directory vendors for vendor-specific extended operations. The request classes should have constructors that accept arguments in a type-safe and user-friendly manner, while the response classes should have access methods for getting the data of the response in a type-safe and user-friendly manner. Internally, the request/response classes deal with encoding and decoding BER values.
For example, suppose an LDAP server supports a "get time" extended operation. It would supply classes such as GetTimeRequest and GetTimeResponse, so that applications can use this feature. An application would use these classes as follows:
GetTimeResponse resp =
(GetTimeResponse) ectx.extendedOperation(new GetTimeRequest());
long time = resp.getTime();
The GetTimeRequest and GetTimeResponse classes might be defined as follows:
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()
GetTimeResponse(String id, byte[] berValue, int offset, int length)
throws NamingException {
// check validitly 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;
}
}
An application typically does not deal directly with this interface. Instead, it deals with classes that implement this interface. The application gets control classes either as part of a repetoire of controls standardized through the IETF, or from directory vendors for vendor-specific controls. The request control classes should have constructors that accept arguments in a type-safe and user-friendly manner, while the response control classes should have access methods for getting the data of the response in a type-safe and user-friendly manner. Internally, the request/response control classes deal with encoding and decoding BER values.
For example, suppose an LDAP server supports a "sort" request control, which when sent with a search request, asks the server to return the results of the search ordered by a particular attribute It would supply a class SortControl so that applications can use this feature. An application would use this class as follows:
Control[] reqCtls = new Control[] {new SortControl("age")};
ectx.setRequestControls(reqCtls);
NamingEnumeration enum = ectx.search(...);
The SortControl class might be defined as follows:
public class SortControl implements Control {
// User-friendly constructor
public SortControl(String attrID) {
// encode attrID
};
// Methods used by service providers
public String getID() {
return SORT_OID;
}
public byte[] getEncodedValue() {
return // encoded attrID
}
...
}
When a service provider receives response controls, it uses the ControlFactory class to produce specific classes that implement the Control interface.
An LDAP server can send back response controls with an LDAP operation and also with enumeration results, such as those returned by a list or search operation. The LdapContext provides a method (getResponseControls()) for getting the response controls sent with an LDAP operation, while the HasControls interface is used to retrieve response controls associated with enumeration results.
For example, suppose an LDAP server sends back a "change ID" control in response to a successful modification. It would supply a class ChangeIDControl so that the application can use this feature. An application would perform an update, and then try to get the change 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());
}
}
}
public class ChangeIDControl implements Control {
long id;
// Constructor used by ControlFactory
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 1.2 | ||||||||
| PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES | ||||||||