This class provides a basic implementation of the Control
interface. It represents an LDAPv3 Control as defined in
RFC 2251.

This interface represents an LDAPv3 control as defined in
RFC 2251.

The LDAPv3 protocol uses controls to send and receive additional data
to affect the behavior of predefined operations.
Controls can be sent along with any LDAP operation to the server.
These are referred to as request controls. For example, a
"sort" control can be sent with an LDAP search operation to
request that the results be returned in a particular order.
Solicited and unsolicited controls can also be returned with
responses from the server. Such controls are referred to as
response controls. For example, an LDAP server might
define a special control to return change notifications.

This interface is used to represent both request and response controls.

This abstract class represents a factory for creating LDAPv3 controls.
LDAPv3 controls are defined in
RFC 2251.

When a service provider receives a response control, it uses control
factories to return the specific/appropriate control class implementation.

ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
         requestName      [0] LDAPOID,
         requestValue     [1] OCTET STRING OPTIONAL }

This interface represents an LDAPv3 extended operation request as defined in
RFC 2251.


    ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
             requestName      [0] LDAPOID,
             requestValue     [1] OCTET STRING OPTIONAL }
It comprises an object identifier string and an optional ASN.1 BER
encoded value.

The methods in this class are used by the service provider to construct
the bits to send to the LDAP server. Applications typically only deal with
the classes that implement this interface, supplying them with
any information required for a particular extended operation request.
It would then pass such a class as an argument to the
LdapContext.extendedOperation() method for performing the
LDAPv3 extended operation.

For example, suppose the LDAP server supported a 'get time' extended operation.
It would supply GetTimeRequest and GetTimeResponse classes:


public class GetTimeRequest implements ExtendedRequest {
    public GetTimeRequest() {... };
    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;
    public GetTimeResponse(String id, byte[] berValue, int offset,
        int length) throws NamingException {
        time =      ... // decode berValue to get time
    }
    public java.util.Date getDate() { return new java.util.Date(time) };
    public long getTime() { return time };
    ...
}
A program would use then these classes as follows:


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

ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
     COMPONENTS OF LDAPResult,
     responseName     [10] LDAPOID OPTIONAL,
     response         [11] OCTET STRING OPTIONAL }

This interface represents an LDAP extended operation response as defined in
RFC 2251.


    ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
         COMPONENTS OF LDAPResult,
         responseName     [10] LDAPOID OPTIONAL,
         response         [11] OCTET STRING OPTIONAL }
It comprises an optional object identifier and an optional ASN.1 BER
encoded value.


The methods in this class can be used by the application to get low
level information about the extended operation response. However, typically,
the application will be using methods specific to the class that
implements this interface. Such a class should have decoded the BER buffer
in the response and should provide methods that allow the user to
access that data in the response in a type-safe and friendly manner.

For example, suppose the LDAP server supported a 'get time' extended operation.
It would supply GetTimeRequest and GetTimeResponse classes.
The GetTimeResponse class might look like:


public class GetTimeResponse implements ExtendedResponse {
    public java.util.Date getDate() {...};
    public long getTime() {...};
    ....
}
A program would use then these classes as follows:


GetTimeResponse resp =
    (GetTimeResponse) ectx.extendedOperation(new GetTimeRequest());
java.util.Date now = resp.getDate();

// Get search result
SearchResult res = (SearchResult)entry;
// do something with it

// Get entry controls
if (entry instanceof HasControls) {
    Control[] entryCtls = ((HasControls)entry).getControls();
    // do something with controls
}

This interface is for returning controls with objects returned
in NamingEnumerations.
For example, suppose a server sends back controls with the results
of a search operation, the service provider would return a NamingEnumeration of
objects that are both SearchResult and implement HasControls.


  NamingEnumeration elts = ectx.search((Name)name, filter, sctls);
  while (elts.hasMore()) {
    Object entry = elts.next();

    // Get search result
    SearchResult res = (SearchResult)entry;
    // do something with it

    // Get entry controls
    if (entry instanceof HasControls) {
        Control[] entryCtls = ((HasControls)entry).getControls();
        // do something with controls
    }
  }

This class is the starting context for performing
LDAPv3-style extended operations and controls.

See javax.naming.InitialContext and
javax.naming.InitialDirContext for details on synchronization,
and the policy for how an initial context is created.

Request Controls
When you create an initial context (InitialLdapContext),
you can specify a list of request controls.
These controls will be used as the request controls for any
implicit LDAP "bind" operation performed by the context or contexts
derived from the context. These are called connection request controls.
Use getConnectControls() to get a context's connection request
controls.

The request controls supplied to the initial context constructor
are not used as the context request controls
for subsequent context operations such as searches and lookups.
Context request controls are set and updated by using
setRequestControls().

As shown, there can be two different sets of request controls
associated with a context: connection request controls and context
request controls.
This is required for those applications needing to send critical
controls that might not be applicable to both the context operation and
any implicit LDAP "bind" operation.
A typical user program would do the following:


InitialLdapContext lctx = new InitialLdapContext(env, critConnCtls);
lctx.setRequestControls(critModCtls);
lctx.modifyAttributes(name, mods);
Controls[] respCtls =  lctx.getResponseControls();
It specifies first the critical controls for creating the initial context
(critConnCtls), and then sets the context's request controls
(critModCtls) for the context operation. If for some reason
lctx needs to reconnect to the server, it will use
critConnCtls. See the LdapContext interface for
more discussion about request controls.

Service provider implementors should read the "Service Provider" section
in the LdapContext class description for implementation details.

This interface represents a context in which you can perform
 operations with LDAPv3-style controls and perform LDAPv3-style
 extended operations.

 For applications that do not require such controls or extended
 operations, the more generic javax.naming.directory.DirContext
 should be used instead.

 Usage Details About Controls

 This interface provides support for LDAP v3 controls.
 At a high level, this support allows a user
 program to set request controls for LDAP operations that are executed
 in the course of the user program's invocation of
 Context/DirContext
 methods, and read response controls resulting from LDAP operations.
 At the implementation level, there are some details that developers of
 both the user program and service providers need to understand in order
 to correctly use request and response controls.

 Request Controls

 There are two types of request controls:

 Request controls that affect how a connection is created
 Request controls that affect context methods


 The former is used whenever a connection needs to be established or
 re-established with an LDAP server. The latter is used when all other
 LDAP operations are sent to the LDAP server.  The reason why a
 distinction between these two types of request controls is necessary
 is because JNDI is a high-level API that does not deal directly with
 connections.  It is the job of service providers to do any necessary
 connection management. Consequently, a single
 connection may be shared by multiple context instances, and a service provider
 is free to use its own algorithms to conserve connection and network
 usage. Thus, when a method is invoked on the context instance, the service
 provider might need to do some connection management in addition to
 performing the corresponding LDAP operations. For connection management,
 it uses the connection request controls, while for the normal
 LDAP operations, it uses the context request controls.
Unless explicitly qualified, the term "request controls" refers to
 context request controls.

 Context Request Controls
 There are two ways in which a context instance gets its request controls:

 ldapContext.newInstance(reqCtls)
 ldapContext.setRequestControls(reqCtls)

 where ldapContext is an instance of LdapContext.
 Specifying null or an empty array for reqCtls
 means no request controls.
 newInstance() creates a new instance of a context using
 reqCtls, while setRequestControls()
 updates an existing context instance's request controls to reqCtls.

 Unlike environment properties, request controls of a context instance
 are not inherited by context instances that are derived from
 it.  Derived context instances have null as their context
 request controls.  You must set the request controls of a derived context
 instance explicitly using setRequestControls().

 A context instance's request controls are retrieved using
 the method getRequestControls().

 Connection Request Controls
 There are three ways in which connection request controls are set:


 new InitialLdapContext(env, connCtls)
 refException.getReferralContext(env, connCtls)
 ldapContext.reconnect(connCtls);

 where refException is an instance of
 LdapReferralException, and ldapContext is an
 instance of LdapContext.
 Specifying null or an empty array for connCtls
 means no connection request controls.

 Like environment properties, connection request controls of a context
 are inherited by contexts that are derived from it.
 Typically, you initialize the connection request controls using the
 InitialLdapContext constructor or
 LdapReferralContext.getReferralContext(). These connection
 request controls are inherited by contexts that share the same
 connection--that is, contexts derived from the initial or referral
 contexts.

 Use reconnect() to change the connection request controls of
 a context.
 Invoking ldapContext.reconnect() affects only the
 connection used by ldapContext and any new contexts instances that are
 derived form ldapContext. Contexts that previously shared the
 connection with ldapContext remain unchanged. That is, a context's
 connection request controls must be explicitly changed and is not
 affected by changes to another context's connection request
 controls.

 A context instance's connection request controls are retrieved using
 the method getConnectControls().

 Service Provider Requirements

 A service provider supports connection and context request controls
 in the following ways.  Context request controls must be associated on
 a per context instance basis while connection request controls must be
 associated on a per connection instance basis.  The service provider
 must look for the connection request controls in the environment
 property "java.naming.ldap.control.connect" and pass this environment
 property on to context instances that it creates.

 Response Controls

 The method LdapContext.getResponseControls() is used to
 retrieve the response controls generated by LDAP operations executed
 as the result of invoking a Context/DirContext
 operation. The result is all of the responses controls generated
 by the underlying LDAP operations, including any implicit reconnection.
 To get only the reconnection response controls,
 use reconnect() followed by getResponseControls().

 Parameters

 A Control[] array
 passed as a parameter to any method is owned by the caller.
 The service provider will not modify the array or keep a reference to it,
 although it may keep references to the individual Control objects
 in the array.
 A Control[] array returned by any method is immutable, and may
 not subsequently be modified by either the caller or the service provider.

This class represents a distinguished name as specified by
RFC 2253.
A distinguished name, or DN, is composed of an ordered list of
components called relative distinguished names, or RDNs.
Details of a DN's syntax are described in RFC 2253.

This class resolves a few ambiguities found in RFC 2253
as follows:

 RFC 2253 leaves the term "whitespace" undefined. The
     ASCII space character 0x20 (" ") is used in its place.
 Whitespace is allowed on either side of ',', ';', '=', and '+'.
     Such whitespace is accepted but not generated by this code,
     and is ignored when comparing names.
 AttributeValue strings containing '=' or non-leading '#'
     characters (unescaped) are accepted.


String names passed to LdapName or returned by it
use the full Unicode character set. They may also contain
characters encoded into UTF-8 with each octet represented by a
three-character substring such as "\\B4".
They may not, however, contain characters encoded into UTF-8 with
each octet represented by a single character in the string:  the
meaning would be ambiguous.

LdapName will properly parse all valid names, but
does not attempt to detect all possible violations when parsing
invalid names.  It is "generous" in accepting invalid names.
The "validity" of a name is determined ultimately when it
is supplied to an LDAP server, which may accept or
reject the name based on factors such as its schema information
and interoperability considerations.

When names are tested for equality, attribute types, both binary
and string values, are case-insensitive.
String values with different but equivalent usage of quoting,
escaping, or UTF8-hex-encoding are considered equal.  The order of
components in multi-valued RDNs (such as "ou=Sales+cn=Bob") is not
significant.

The components of a LDAP name, that is, RDNs, are numbered. The
indexes of a LDAP name with n RDNs range from 0 to n-1.
This range may be written as [0,n).
The right most RDN is at index 0, and the left most RDN is at
index n-1. For example, the distinguished name:
"CN=Steve Kille, O=Isode Limited, C=GB" is numbered in the following
sequence ranging from 0 to 2: {C=GB, O=Isode Limited, CN=Steve Kille}. An
empty LDAP name is represented by an empty RDN list.

Concurrent multithreaded read-only access of an instance of
LdapName need not be synchronized.

Unless otherwise noted, the behavior of passing a null argument
to a constructor or method in this class will cause a
NullPointerException to be thrown.

This abstract class is used to represent an LDAP referral exception.
It extends the base ReferralException by providing a
getReferralContext() method that accepts request controls.
LdapReferralException is an abstract class. Concrete implementations of it
determine its synchronization and serialization properties.

A Control[] array passed as a parameter to
the getReferralContext() method is owned by the caller.
The service provider will not modify the array or keep a reference to it,
although it may keep references to the individual Control objects
in the array.

Requests that referral and other special LDAP objects be manipulated
as normal LDAP objects. It enables the requestor to interrogate or
update such objects.

This class implements the LDAPv3 Request Control for ManageDsaIT
as defined in
RFC 3296.

The control has no control value.

// Open an LDAP association
LdapContext ctx = new InitialLdapContext();

// Activate paged results
int pageSize = 20; // 20 entries per page
byte[] cookie = null;
int total;
ctx.setRequestControls(new Control[]{
    new PagedResultsControl(pageSize, Control.CRITICAL) });

do {
    // Perform the search
    NamingEnumeration results =
        ctx.search("", "(objectclass=*)", new SearchControls());

    // Iterate over a batch of search results
    while (results != null && results.hasMore()) {
        // Display an entry
        SearchResult entry = (SearchResult)results.next();
        System.out.println(entry.getName());
        System.out.println(entry.getAttributes());

        // Handle the entry's response controls (if any)
        if (entry instanceof HasControls) {
            // ((HasControls)entry).getControls();
        }
    }
    // Examine the paged results control response
    Control[] controls = ctx.getResponseControls();
    if (controls != null) {
        for (int i = 0; i < controls.length; i++) {
            if (controls[i] instanceof PagedResultsResponseControl) {
                PagedResultsResponseControl prrc =
                    (PagedResultsResponseControl)controls[i];
                total = prrc.getResultSize();
                cookie = prrc.getCookie();
            } else {
                // Handle other response controls (if any)
            }
        }
    }

    // Re-activate paged results
    ctx.setRequestControls(new Control[]{
        new PagedResultsControl(pageSize, cookie, Control.CRITICAL) });
} while (cookie != null);

// Close the LDAP association
ctx.close();
...

realSearchControlValue ::= SEQUENCE {
    size      INTEGER (0..maxInt),
                      -- requested page size from client
                      -- result set size estimate from server
    cookie    OCTET STRING
}

Requests that the results of a search operation be returned by the LDAP
server in batches of a specified size.
The requestor controls the rate at which batches are returned by the rate
at which it invokes search operations.

The following code sample shows how the class may be used:


    // Open an LDAP association
    LdapContext ctx = new InitialLdapContext();

    // Activate paged results
    int pageSize = 20; // 20 entries per page
    byte[] cookie = null;
    int total;
    ctx.setRequestControls(new Control[]{
        new PagedResultsControl(pageSize, Control.CRITICAL) });

    do {
        // Perform the search
        NamingEnumeration results =
            ctx.search("", "(objectclass=*)", new SearchControls());

        // Iterate over a batch of search results
        while (results != null && results.hasMore()) {
            // Display an entry
            SearchResult entry = (SearchResult)results.next();
            System.out.println(entry.getName());
            System.out.println(entry.getAttributes());

            // Handle the entry's response controls (if any)
            if (entry instanceof HasControls) {
                // ((HasControls)entry).getControls();
            }
        }
        // Examine the paged results control response
        Control[] controls = ctx.getResponseControls();
        if (controls != null) {
            for (int i = 0; i < controls.length; i++) {
                if (controls[i] instanceof PagedResultsResponseControl) {
                    PagedResultsResponseControl prrc =
                        (PagedResultsResponseControl)controls[i];
                    total = prrc.getResultSize();
                    cookie = prrc.getCookie();
                } else {
                    // Handle other response controls (if any)
                }
            }
        }

        // Re-activate paged results
        ctx.setRequestControls(new Control[]{
            new PagedResultsControl(pageSize, cookie, Control.CRITICAL) });
    } while (cookie != null);

    // Close the LDAP association
    ctx.close();
    ...

This class implements the LDAPv3 Control for paged-results as defined in
RFC 2696.

The control's value has the following ASN.1 definition:


    realSearchControlValue ::= SEQUENCE {
        size      INTEGER (0..maxInt),
                          -- requested page size from client
                          -- result set size estimate from server
        cookie    OCTET STRING
    }

realSearchControlValue ::= SEQUENCE {
    size      INTEGER (0..maxInt),
                      -- requested page size from client
                      -- result set size estimate from server
    cookie    OCTET STRING
}

Indicates the end of a batch of search results.
Contains an estimate of the total number of entries in the result set
and an opaque cookie. The cookie must be supplied to the next search
operation in order to get the next batch of results.

The code sample in PagedResultsControl shows how this class may
be used.

This class implements the LDAPv3 Response Control for
paged-results as defined in
RFC 2696.

The control's value has the following ASN.1 definition:


    realSearchControlValue ::= SEQUENCE {
        size      INTEGER (0..maxInt),
                          -- requested page size from client
                          -- result set size estimate from server
        cookie    OCTET STRING
    }

 Rdn rdn = new Rdn("cn", "Juicy, Fruit");
 System.out.println(rdn.toString());

 Rdn rdn = new Rdn("cn=Juicy\\, Fruit");
 System.out.println(rdn.toString());

This class represents a relative distinguished name, or RDN, which is a
component of a distinguished name as specified by
RFC 2253.
An example of an RDN is "OU=Sales+CN=J.Smith". In this example,
the RDN consist of multiple attribute type/value pairs. The
RDN is parsed as described in the class description for
LdapName.

The Rdn class represents an RDN as attribute type/value mappings,
which can be viewed using
Attributes.
In addition, it contains convenience methods that allow easy retrieval
of type and value when the Rdn consist of a single type/value pair,
which is how it appears in a typical usage.
It also contains helper methods that allow escaping of the unformatted
attribute value and unescaping of the value formatted according to the
escaping syntax defined in RFC2253. For methods that take or return
attribute value as an Object, the value is either a String
(in unescaped form) or a byte array.

Rdn will properly parse all valid RDNs, but
does not attempt to detect all possible violations when parsing
invalid RDNs. It is "generous" in accepting invalid RDNs.
The "validity" of a name is determined ultimately when it
is supplied to an LDAP server, which may accept or
reject the name based on factors such as its schema information
and interoperability considerations.


The following code example shows how to construct an Rdn using the
constructor that takes type and value as arguments:


     Rdn rdn = new Rdn("cn", "Juicy, Fruit");
     System.out.println(rdn.toString());
The last line will print cn=Juicy\, Fruit. The
unescapeValue() method can be
used to unescape the escaped comma resulting in the original
value "Juicy, Fruit". The escapeValue() method adds the escape back preceding the comma.

This class can be instantiated by a string representation
of the RDN defined in RFC 2253 as shown in the following code example:


     Rdn rdn = new Rdn("cn=Juicy\\, Fruit");
     System.out.println(rdn.toString());
The last line will print cn=Juicy\, Fruit.

Concurrent multithreaded read-only access of an instance of
Rdn need not be synchronized.

Unless otherwise noted, the behavior of passing a null argument
to a constructor or method in this class will cause NullPointerException
to be thrown.

// Open an LDAP association
LdapContext ctx = new InitialLdapContext();

// Activate sorting
String sortKey = "cn";
ctx.setRequestControls(new Control[]{
    new SortControl(sortKey, Control.CRITICAL) });

// Perform a search
NamingEnumeration results =
    ctx.search("", "(objectclass=*)", new SearchControls());

// Iterate over search results
while (results != null && results.hasMore()) {
    // Display an entry
    SearchResult entry = (SearchResult)results.next();
    System.out.println(entry.getName());
    System.out.println(entry.getAttributes());

    // Handle the entry's response controls (if any)
    if (entry instanceof HasControls) {
        // ((HasControls)entry).getControls();
    }
}
// Examine the sort control response
Control[] controls = ctx.getResponseControls();
if (controls != null) {
    for (int i = 0; i < controls.length; i++) {
        if (controls[i] instanceof SortResponseControl) {
            SortResponseControl src = (SortResponseControl)controls[i];
            if (! src.isSorted()) {
                throw src.getException();
            }
        } else {
            // Handle other response controls (if any)
        }
    }
}

// Close the LDAP association
ctx.close();
...

SortKeyList ::= SEQUENCE OF SEQUENCE {
    attributeType     AttributeDescription,
    orderingRule  [0] MatchingRuleId OPTIONAL,
    reverseOrder  [1] BOOLEAN DEFAULT FALSE }

Requests that the results of a search operation be sorted by the LDAP server
before being returned.
The sort criteria are specified using an ordered list of one or more sort
keys, with associated sort parameters.
Search results are sorted at the LDAP server according to the parameters
supplied in the sort control and then returned to the requestor. If sorting
is not supported at the server (and the sort control is marked as critical)
then the search operation is not performed and an error is returned.

The following code sample shows how the class may be used:


    // Open an LDAP association
    LdapContext ctx = new InitialLdapContext();

    // Activate sorting
    String sortKey = "cn";
    ctx.setRequestControls(new Control[]{
        new SortControl(sortKey, Control.CRITICAL) });

    // Perform a search
    NamingEnumeration results =
        ctx.search("", "(objectclass=*)", new SearchControls());

    // Iterate over search results
    while (results != null && results.hasMore()) {
        // Display an entry
        SearchResult entry = (SearchResult)results.next();
        System.out.println(entry.getName());
        System.out.println(entry.getAttributes());

        // Handle the entry's response controls (if any)
        if (entry instanceof HasControls) {
            // ((HasControls)entry).getControls();
        }
    }
    // Examine the sort control response
    Control[] controls = ctx.getResponseControls();
    if (controls != null) {
        for (int i = 0; i < controls.length; i++) {
            if (controls[i] instanceof SortResponseControl) {
                SortResponseControl src = (SortResponseControl)controls[i];
                if (! src.isSorted()) {
                    throw src.getException();
                }
            } else {
                // Handle other response controls (if any)
            }
        }
    }

    // Close the LDAP association
    ctx.close();
    ...

This class implements the LDAPv3 Request Control for server-side sorting
as defined in
RFC 2891.

The control's value has the following ASN.1 definition:


    SortKeyList ::= SEQUENCE OF SEQUENCE {
        attributeType     AttributeDescription,
        orderingRule  [0] MatchingRuleId OPTIONAL,
        reverseOrder  [1] BOOLEAN DEFAULT FALSE }

A sort key and its associated sort parameters.
This class implements a sort key which is used by the LDAPv3
Control for server-side sorting of search results as defined in
RFC 2891.

SortResult ::= SEQUENCE {
   sortResult  ENUMERATED {
       success                   (0), -- results are sorted
       operationsError           (1), -- server internal failure
       timeLimitExceeded         (3), -- timelimit reached before
                                      -- sorting was completed
       strongAuthRequired        (8), -- refused to return sorted
                                      -- results via insecure
                                      -- protocol
       adminLimitExceeded       (11), -- too many matching entries
                                      -- for the server to sort
       noSuchAttribute          (16), -- unrecognized attribute
                                      -- type in sort key
       inappropriateMatching    (18), -- unrecognized or inappro-
                                      -- priate matching rule in
                                      -- sort key
       insufficientAccessRights (50), -- refused to return sorted
                                      -- results to this client
       busy                     (51), -- too busy to process
       unwillingToPerform       (53), -- unable to sort
       other                    (80)
       },
 attributeType [0] AttributeType OPTIONAL }

Indicates whether the requested sort of search results was successful or not.
When the result code indicates success then the results have been sorted as
requested. Otherwise the sort was unsuccessful and additional details
regarding the cause of the error may have been provided by the server.

The code sample in SortControl shows how this class may be used.

This class implements the LDAPv3 Response Control for server-side sorting
as defined in
RFC 2891.

The control's value has the following ASN.1 definition:


    SortResult ::= SEQUENCE {
       sortResult  ENUMERATED {
           success                   (0), -- results are sorted
           operationsError           (1), -- server internal failure
           timeLimitExceeded         (3), -- timelimit reached before
                                          -- sorting was completed
           strongAuthRequired        (8), -- refused to return sorted
                                          -- results via insecure
                                          -- protocol
           adminLimitExceeded       (11), -- too many matching entries
                                          -- for the server to sort
           noSuchAttribute          (16), -- unrecognized attribute
                                          -- type in sort key
           inappropriateMatching    (18), -- unrecognized or inappro-
                                          -- priate matching rule in
                                          -- sort key
           insufficientAccessRights (50), -- refused to return sorted
                                          -- results to this client
           busy                     (51), -- too busy to process
           unwillingToPerform       (53), -- unable to sort
           other                    (80)
           },
     attributeType [0] AttributeType OPTIONAL }

This class implements the LDAPv3 Extended Request for StartTLS as
defined in
Lightweight Directory
Access Protocol (v3): Extension for Transport Layer Security

The object identifier for StartTLS is 1.3.6.1.4.1.1466.20037
and no extended request value is defined.

StartTlsRequest/StartTlsResponse are used to establish
a TLS connection over the existing LDAP connection associated with
the JNDI context on which extendedOperation() is invoked.
Typically, a JNDI program uses these classes as follows.


import javax.naming.ldap.*;

// Open an LDAP association
LdapContext ctx = new InitialLdapContext();

// Perform a StartTLS extended operation
StartTlsResponse tls =
    (StartTlsResponse) ctx.extendedOperation(new StartTlsRequest());

// Open a TLS connection (over the existing LDAP association) and get details
// of the negotiated TLS session: cipher suite, peer certificate, etc.
SSLSession session = tls.negotiate();

// ... use ctx to perform protected LDAP operations

// Close the TLS connection (revert back to the underlying LDAP association)
tls.close();

// ... use ctx to perform unprotected LDAP operations

// Close the LDAP association
ctx.close;

This class implements the LDAPv3 Extended Response for StartTLS as
defined in
Lightweight Directory
Access Protocol (v3): Extension for Transport Layer Security

The object identifier for StartTLS is 1.3.6.1.4.1.1466.20037
and no extended response value is defined.


The Start TLS extended request and response are used to establish
a TLS connection over the existing LDAP connection associated with
the JNDI context on which extendedOperation() is invoked.
Typically, a JNDI program uses the StartTLS extended request and response
classes as follows.


import javax.naming.ldap.*;

// Open an LDAP association
LdapContext ctx = new InitialLdapContext();

// Perform a StartTLS extended operation
StartTlsResponse tls =
    (StartTlsResponse) ctx.extendedOperation(new StartTlsRequest());

// Open a TLS connection (over the existing LDAP association) and get details
// of the negotiated TLS session: cipher suite, peer certificate, ...
SSLSession session = tls.negotiate();

// ... use ctx to perform protected LDAP operations

// Close the TLS connection (revert back to the underlying LDAP association)
tls.close();

// ... use ctx to perform unprotected LDAP operations

// Close the LDAP association
ctx.close;

This interface represents an unsolicited notification as defined in
RFC 2251.
An unsolicited notification is sent by the LDAP server to the LDAP
client without any provocation from the client.
Its format is that of an extended response (ExtendedResponse).

This class represents an event fired in response to an unsolicited
notification sent by the LDAP server.

This interface is for handling UnsolicitedNotificationEvent.
"Unsolicited notification" is defined in
RFC 2251.
It allows the server to send unsolicited notifications to the client.
A UnsolicitedNotificationListener must:

Implement this interface and its method
Implement NamingListener.namingExceptionThrown() so
that it will be notified of exceptions thrown while attempting to
collect unsolicited notification events.
Register with the context using one of the addNamingListener()
methods from EventContext or EventDirContext.
Only the NamingListener argument of these methods are applicable;
the rest are ignored for a UnsolicitedNotificationListener.
(These arguments might be applicable to the listener if it implements
other listener interfaces).