com.unboundid.util.json

Class LDAPConnectionDetailsJSONSpecification

java.lang.Object

com.unboundid.util.json.LDAPConnectionDetailsJSONSpecification

@NotMutable
 @ThreadSafety(level=COMPLETELY_THREADSAFE)
public final class LDAPConnectionDetailsJSONSpecification
extends java.lang.Object

This class provides a utility that may be used to obtain information that may be used to create LDAP connections to one or more servers from a definition contained in a JSON object. This makes it easier to create applications that provide the information necessary for creating LDAP connections and connection pools in a JSON-formatted configuration file.

The JSON-based specification is organized into five sections:

1. A "server-details" section that provides information about the directory server(s) to access. The specification supports accessing a single server, as well as a number of schemes for establishing connections across multiple servers.
2. A "communication-security" section that provides information that may be used to secure communication using SSL or StartTLS.
3. A "connection-options" section that can be used customize a number of connection-related options, like connect and response timeouts, whether to follow referrals, whether to retrieve schema from the backend server for client-side use, and whether to use synchronous mode for more efficient communication if connections will not be used in an asynchronous manner.
4. An "authentication-details" section that provides information for authenticating connections using a number of mechanisms.
5. A "connection-pool-options" section that provides information to use to customize the behavior to use for connection pools created from this specification.

Each of these sections will be described in more detail below.

The "server-details" Section

The JSON object that comprises the LDAP connection details specification must have a top-level "server-details" field whose value is a JSON object that provides information about the server(s) to which connections may be established. The value of the "server-details" field must itself be a JSON object, and that object must have exactly one field, which depends on the mechanism that the LDAP SDK should use to select the target directory servers.

The "server-details" Section for Connecting to a Single Server
When establishing a connection to a single server, the "server-details" value should be a JSON object that contains a "single-server" field whose value is a JSON object with "address" and "port" fields. For example, the following is a valid specification that may be used to establish connections to the server at ldap.example.com on port 389:

   {
     "server-details":
     {
       "single-server":
       {
         "address":"ldap.example.com",
         "port":389
       }
     }
   }
 

The "server-details" Section for Selecting from a Set of Servers in a Round-Robin Manner
If you have a set of servers that you want to connect to in a round-robin manner (in which the LDAP SDK will maintain a circular list of servers and each new connection will go to the next server in the list), the "server-details" value should be a JSON object that contains a "round-robin-set" field whose value is a JSON object that contains a "server" field with an array of JSON objects, each of which contains "address" and "port" fields for a target server. For example, the following is a valid specification that may be used to establish connections across the servers ldap1.example.com, ldap2.example.com, and ldap3.example.com, all on port 389:

   {
     "server-details":
     {
       "round-robin-set":
       {
         "servers":
         [
           {
             "address":"ldap1.example.com",
             "port":389
           },
           {
             "address":"ldap2.example.com",
             "port":389
           },
           {
             "address":"ldap2.example.com",
             "port":389
           }
         ]
       }
     }
   }
 

The "server-details" Section for Selecting from a Set of Servers in a Fewest Connections Manner
If you have a set of servers that you want to connect to in a manner that selects the server with the fewest established connections (at least connections created from this specification), the "server-details" value should be a JSON object that contains a "fewest-connections-set" field whose value is a JSON object that contains a "server" field with an array of JSON objects, each of which contains "address" and "port" fields for a target server. For example, the following is a valid specification that may be used to establish connections across the servers ldap1.example.com, ldap2.example.com, and ldap3.example.com, all on port 389:

   {
     "server-details":
     {
       "fewest-connections-set":
       {
         "servers":
         [
           {
             "address":"ldap1.example.com",
             "port":389
           },
           {
             "address":"ldap2.example.com",
             "port":389
           },
           {
             "address":"ldap2.example.com",
             "port":389
           }
         ]
       }
     }
   }
 

The "server-details" Section for Selecting from a Set of Servers in a Fastest Connect Manner
If you have a set of servers that you want to connect to in a manner that attempts to minimize the time required to establish new connections (by simultaneously attempting to create connections to every server in the set and taking the first connection to be established), the "server-details" value should be a JSON object that contains a "fastest-connect-set" field whose value is a JSON object that contains a "server" field with an array of JSON objects, each of which contains "address" and "port" fields for a target server. For example, the following is a valid specification that may be used to establish connections across the servers ldap1.example.com, ldap2.example.com, and ldap3.example.com, all on port 389:

   {
     "server-details":
     {
       "fastest-connect-set":
       {
         "servers":
         [
           {
             "address":"ldap1.example.com",
             "port":389
           },
           {
             "address":"ldap2.example.com",
             "port":389
           },
           {
             "address":"ldap2.example.com",
             "port":389
           }
         ]
       }
     }
   }
 

The "server-details" Section for Selecting from a Set of Servers in a Failover Manner
If you have a set of servers that you want to connect to in a manner that attempts to consistently establish connections to the same server (as long as it is available, and use a consistent failover order if the preferred server isn't available), the "server-details" value should be a JSON object that contains a "failover-set" field whose value is a JSON object that contains a "failover-order" field that provides a list of the details to use in order to establish the connections. For example, the following is a valid specification that may be used to always try to establish connections to ldap1.example.com:389, then try ldap2.example.com:389, and then try ldap3.example.com:389:

   {
     "server-details":
     {
       "failover-set":
       {
         "failover-order":
         [
           {
             "single-server":
             {
               "address":"ldap1.example.com",
               "port":389
             }
           },
           {
             "single-server":
             {
               "address":"ldap2.example.com",
               "port":389
             }
           },
           {
             "single-server":
             {
               "address":"ldap2.example.com",
               "port":389
             }
           }
         ]
       }
     }
   }
 

The failover set actually has the ability to perform failover across any kind of set. This is a powerful capability that can be useful to define a hierarchy of sets, for example for sets referring to servers in different data centers (e.g., to prefer connecting to one of the servers in the local data center over servers in a remote data center). For example, the following is a valid specification that may be used to connect to the server with the fewest connections in the east data center, but if no east servers are available then it will fail over to select the server with the fewest connections in the west data center:

   {
     "server-details":
     {
       "failover-set":
       {
         "failover-order":
         [
           {
             "fewest-connections-set":
             {
               "servers":
               [
                 {
                   "address":"ldap1.east.example.com",
                   "port":389
                 },
                 {
                   "address":"ldap2.east.example.com",
                   "port":389
                 }
               ]
             }
           },
           {
             "fewest-connections-set":
             {
               "servers":
               [
                 {
                   "address":"ldap1.west.example.com",
                   "port":389
                 },
                 {
                   "address":"ldap2.west.example.com",
                   "port":389
                 }
               ]
             }
           }
         ]
       }
     }
   }
 

For connections that are part of a connection pool, failover sets have the ability to assign a different maximum connection age to connections created to a non-preferred server. This can help allow failover connections to be migrated back to the preferred server more quickly once that server is available again. If you wish to specify an alternate maximum connection age for connections to a non-preferred server, you may include the "maximum-failover-connection-age-millis" field in the "failover-set" object. The value of this field should be a number that is greater than zero to specify the maximum age (in milliseconds) for those connections, or a value of zero to indicate that they should not be subject to a maximum age. If this field is not present, then these connections will be assigned the default maximum connection age configured for the pool.

The "communication-security" Section

This section may be used to provide information about the type of security to use to protect communication with directory servers. If the specification includes information about multiple servers, then all servers will use the same type of security.

If present, the "communication-security" field should have a value that is a JSON object. This object must have a "security-type" field with one of the following values:

• "none" -- Indicates that no communication security should be used. The communication will not be encrypted.
• "SSL" -- Indicates that all communication should be encrypted with the SSL (secure sockets layer) protocol, or more likely its more secure successor TLS (transport-layer security) protocol. You can also specify a value of "TLS" to use this type of security.
• "StartTLS" -- Indicates that the connection will be initially established in a non-secure manner, but will be immediately secured with the StartTLS extended operation.

If you do not wish to use any form of communication security, then the "security-type" field is the only one that should be present. For example, the following is a valid specification that will use unencrypted communication to the server ldap.example.com on port 389:

   {
     "server-details":
     {
       "single-server":
       {
         "address":"ldap.example.com",
         "port":389
       }
     },
     "communication-security":
     {
       "security-type":"none"
     }
   }
 

If you wish to secure the communication with either SSL or StartTLS, then there are a number of other options that may be specified using fields in the "communication-security" object. Those options fall into two basic categories: fields that provide information about how the client should determine whether to trust the certificate presented by the server, and fields that provide information about whether the client should present its own certificate to the server. The fields related to client trust include:

• "trust-all-certificates" -- Indicates whether the client should blindly trust any certificate that the server presents to it. Using blind trust is convenient for testing and troubleshooting purposes, but is not recommended for production use because it can leave the communication susceptible to man-in-the-middle attacks. If this field is present, then it should have a boolean value. If it is not present, a default value of false will be assumed. If it is present with a value of true, then the "use-jvm-default-trust-store", "trust-store-file", "trust-store-type", "trust-store-pin", and "trust-store-pin-file" fields should not be used.
• "use-jvm-default-trust-store" -- Indicates that certificates signed by an authority listed in the JVM's default set of trusted issuers should be trusted. If this field is present, it should have a boolean value. The JVM-default trust store may be used on its own or in conjunction with a trust store file.
• "trust-store-file" -- Specifies the path to a trust store file (in JKS or PKCS#12 format). If this is present, then the presented certificate will only be trusted if the trust store file contains information about all of the issuers in the certificate chain.
• "trust-store-type" -- Indicates the format for the trust store file. If this is present, then its value should be a string that is either "JKS" or "PKCS12". If it is not present, then a default trust store type of "JKS" will be assumed.
• "trust-store-pin" -- Specifies the PIN that should be used to access the contents of the trust store. If this field is present, then its value should be a string that is the clear-text PIN. If it is not present, then the PIN may be read from a file specified using the "trust-store-pin-file" field. If neither the "trust-store-pin" field nor the "trust-store-pin-file" field is present, then no PIN will be used when attempting to access the trust store (and in many cases, no trust store PIN will be required).
• "trust-store-pin-file" -- Specifies the path to a file that contains the PIN to use to access the contents of the trust store. If this field is present, then its value must be the path to a file containing a single line, which is the clear-text PIN. If it is not present, then the PIN may be obtained from the "trust-store-pin" field. If neither the "trust-store-pin" field nor the "trust-store-pin-file" field is present, then no PIN will be used when attempting to access the trust store (and in many cases, no trust store PIN will be required).
• "trust-expired-certificates" -- Indicates whether the client should trust certificates that are not yet valid or that have expired. If this field is present, then its value must be a boolean. If the value is true, then the certificate validity dates will not be taken into consideration when deciding whether to trust a certificate. If the value is false, then any certificate whose validity window does not include the current time will not be trusted (even if "trust-all-certificates" is true). If this field is not present, then a default of false will be assumed.
• "verify-address-in-certificate" -- Indicates whether the client should examine the information contained in the certificate to verify that the address the client used to connect to the server matches address information contained in the certificate (whether in the CN attribute of the certificate's subject, or in a subjectAltName extension of type dNSName, uniformResourceIdentifier, or iPAddress). If this field is present, then its value must be a boolean. If it is absent, then a default value of false will be assumed.

If none of the above fields are provided, then the JVM's default trust mechanism will be used. This will generally only trust certificates signed by a well-known certification authority.

The fields related to presenting a client certificate include:

• "key-store-file" -- Specifies the path to a key store file (in JKS or PKCS#12 format) that contains the certificate that the client should present to the server. If this is present, then the value must be a string that is the path to the key store file. If it is not present, then no key store file will be used.
• "key-store-type" -- Specifies the type of key store that should be used. If this is present, then its value must be a string, and that string should be "JKS" or "PKCS12" (if a "key-store-file" value is present), or "PKCS11" (if the client certificate is contained in a security module accessible via the PKCS#11 API. If this field is not present but a "key-store-file" value is provided, then a default value of "JKS" will be assumed.
• "key-store-pin" -- Specifies the PIN that should be used to access the contents of the key store. If this field is present, then its value should be a string that is the clear-text PIN. If it is not present, then the PIN may be read from a file specified using the "key-store-pin-file" field. If neither the "key-store-pin" field nor the "key-store-pin-file" field is present, then no PIN will be used when attempting to access the key store (although key stores generally require a PIN in order to access private key information).
• "key-store-pin-file" -- Specifies the path to a file containing the PIN that should be used to access the contents of the key store. If this field is present, then its value should be the path to a file containing the clear-text PIN. If it is not present, then the PIN may be obtained from the "key-store-pin" field. If neither the "key-store-pin" field nor the "key-store-pin-file" field is present, then no PIN will be used when attempting to access the key store (although key stores generally require a PIN in order to access private key information).
• "client-certificate-alias" -- Specifies the alias (also known as the nickname) of the client certificate that should be presented to the directory server. If this field is present, then its value should be a string that is the alias for a valid certificate that exists in the key store. If this field is not present, then the JVM will automatically attempt to select a suitable client certificate.

If none of the above fields are provided, then the client will not attempt to present a certificate to the server.

The following example demonstrates a simple specification that can be used to establish SSL-based connections to a single server. The client will trust any certificates signed by one of the JVM's default issuers, or any certificate contained in or signed by a certificate contained in the specified trust store file. As no key store is provided, the client will not attempt to present its own certificate to the server.

   {
     "server-details":
     {
       "single-server":
       {
         "address":"ldap.example.com",
         "port":636
       }
     },
     "communication-security":
     {
       "security-type":"SSL",
       "use-jvm-default-trust-store":true,
       "trust-store-file":"/path/to/trust-store.jks",
       "trust-store-type":"JKS",
       "verify-address-in-certificate":true
     }
   }
 

The "communication-security" field is optional, and if it is omitted from the specification then it will be equivalent to including it with a "security-type" value of "none".

The "connection-options" Section

The "connection-options" section may be used to provide information about a number of settings that may be used in the course of establishing a connection, or that may affect the behavior of the connection. The value of the "connection-options" field must be a JSON object, and the following fields may appear in that object:

• "connect-timeout-millis" -- Specifies the maximum length of time (in milliseconds) that a connection attempt may block while waiting for the connection to be established. If this field is present, then its value must be a positive integer to specify the timeout, or a value of zero to indicate that no timeout should be enforced by the LDAP SDK. Note that the underlying operating system may enforce its own connect timeout, and if that value is smaller than the LDAP SDK timeout then the operating system's timeout value will be used. If this field is not present, then a default of 60000 (1 minute) will be used.
• "default-response-timeout-millis" -- Specifies the default timeout (in milliseconds) that will be used when waiting for a response to a request sent to the server. If this field is present, then its value must be a positive integer to specify the timeout, or a value of zero to indicate that no timeout should be enforced. If this field is not present, then a default of 300000 (5 minutes) will be used. Note that this default response timeout can be overridden on a per-request basis using the setResponseTimeoutMillis method provided by the request object.
• "follow-referrals" -- Indicates whether the LDAP SDK should automatically attempt to follow any referrals that are returned during processing. If this field is present, the value should be a boolean. If it is absent, then a default of false will be assumed.
• "use-schema" -- Indicates whether the LDAP SDK should attempt to retrieve schema information from the directory server upon establishing a connection to that server, and should then use that schema information for more accurate client-side matching operations. If present, this field should have a boolean value. If it is not present, then a default value of false will be used.
• "use-synchronous-mode" -- Indicates whether connections should be created in synchronous mode, which may be more efficient and less resource intensive than connections not created in synchronous mode, but may only be used if no attempt will be made to issue asynchronous requests over the connection, or to attempt to use the connection simultaneously by multiple threads. If this field is present, then its value must be a boolean. If it is not present, then a default value of false will be used.

The "connection-options" field is optional, and if it is omitted from the specification then the default values will be used for all options.

The "authentication-details" Section

The "authentication-details" section may be used to provide information for authenticating the connections that are created. The value of the "authentication-details" field must be a JSON object, and it must include an "authentication-type" field to specify the mechanism to use to authenticate. The selected authentication type dictates the other fields that may be present in the object.

The "none" Authentication Type
If no authentication should be performed, then the "authentication-type" value should be "none". No other fields should be specified in the "authentication-details". For example:

   {
     "server-details":
     {
       "single-server":
       {
         "address":"ldap.example.com",
         "port":389
       }
     },
     "authentication-details":
     {
       "authentication-type":"none"
     }
   }
 

The "simple" Authentication Type
If you wish to authenticate connections with an LDAP simple bind, then you can specify an "authentication-type" value of "simple". The following additional fields may be included in the "authentication-details" object for this authentication type:

• "dn" -- The DN to use to bind to the server. This field must be present, and its value must be a string containing the bind DN, or an empty string to indicate anonymous simple authentication.
• "password" -- The password to use to bind to the server. If this field is present, then its value must be a string that contains the clear-text password, or an empty string to indicate anonymous simple authentication. If it is not provided, then the "password-file" field must be used to specify the path to a file containing the bind password.
• "password-file" -- The path to a file containing the password to use to bind to the server. If this field is present, then its value must be a string that represents the path to a file containing a single line that contains the clear-text password. If it is not provided, then the "password" field must be used to specify the password.

For example:

   {
     "server-details":
     {
       "single-server":
       {
         "address":"ldap.example.com",
         "port":389
       }
     },
     "authentication-details":
     {
       "authentication-type":"simple",
       "dn":"uid=john.doe,ou=People,dc=example,dc=com",
       "password-file":"/path/to/password.txt"
     }
   }
 

The "CRAM-MD5" Authentication Type If you wish to authenticate connections with the CRAM-MD5 SASL mechanism, then you can specify an "authentication-type" value of "CRAM-MD5". The following additional fields may be included in the "authentication-details" object for this authentication type:

• "authentication-id" -- The authentication ID to use to bind. This field must be present, and its value must be a string containing the authentication ID. Authentication ID values typically take the form "dn:" followed by the user DN, or "u:" followed by the username.
• "password" -- The password to use to bind to the server. If this field is present, then its value must be a string that contains the clear-text password, or an empty string to indicate anonymous simple authentication. If it is not provided, then the "password-file" field must be used to specify the path to a file containing the bind password.
• "password-file" -- The path to a file containing the password to use to bind to the server. If this field is present, then its value must be a string that represents the path to a file containing a single line that contains the clear-text password. If it is not provided, then the "password" field must be used to specify the password.

For Example:

   {
     "server-details":
     {
       "single-server":
       {
         "address":"ldap.example.com",
         "port":389
       }
     },
     "authentication-details":
     {
       "authentication-type":"CRAM-MD5",
       "authentication-id":"u:john.doe",
       "password-file":"/path/to/password.txt"
     }
   }
 

The "DIGEST-MD5" Authentication Type If you wish to authenticate connections with the DIGEST-MD5 SASL mechanism, then you can specify an "authentication-type" value of "DIGEST-MD5". The following additional fields may be included in the "authentication-details" object for this authentication type:

• "authentication-id" -- The authentication ID to use to bind. This field must be present, and its value must be a string containing the authentication ID. Authentication ID values typically take the form "dn:" followed by the user DN, or "u:" followed by the username.
• "authorization-id" -- The alternate authorization identity to use for the connection after the bind has completed. If present, the value must be a string containing the desired authorization identity. If this field is absent, then no alternate authorization identity will be used.
• "password" -- The password to use to bind to the server. If this field is present, then its value must be a string that contains the clear-text password, or an empty string to indicate anonymous simple authentication. If it is not provided, then the "password-file" field must be used to specify the path to a file containing the bind password.
• "password-file" -- The path to a file containing the password to use to bind to the server. If this field is present, then its value must be a string that represents the path to a file containing a single line that contains the clear-text password. If it is not provided, then the "password" field must be used to specify the password.
• "realm" -- The realm to use for the bind request. If this field is present, then its value must be a string containing the name of the realm. If it is not provided, then the realm will not be included in the bind request.
• "qop" -- The allowed quality of protection value(s) that may be used for the bind operation. If this field is present, then its value may be a single string or an array of strings indicating the allowed QoP values. Allowed values include "auth" (for just authentication), "auth-int" (for authentication followed by integrity protection for subsequent communication on the connection), and "auth-conf" (for authentication followed by confidentiality for subsequent communication on the connection). If this field is not present, then a default value of "auth" will be assumed.

For Example:

   {
     "server-details":
     {
       "single-server":
       {
         "address":"ldap.example.com",
         "port":389
       }
     },
     "authentication-details":
     {
       "authentication-type":"DIGEST-MD5",
       "authentication-id":"u:john.doe",
       "password-file":"/path/to/password.txt"
     }
   }
 

The "EXTERNAL" Authentication Type If you wish to authenticate connections with the EXTERNAL SASL mechanism, then you can specify an "authentication-type" value of "EXTERNAL". The connection must be secured with SSL or StartTLS, and the following additional field may be present in the "authentication-details" object:

• "authorization-id" -- The authorization identity for the bind request. If this field is present, then it must be a string containing the desired authorization ID, or an empty string if the server should determine the authorization identity. If this field is omitted, then the bind request will not include any SASL credentials, which may be required for use with some servers that cannot handle the possibility of an authorization ID in the bind request.

For Example:

   {
     "server-details":
     {
       "single-server":
       {
         "address":"ldap.example.com",
         "port":636
       }
     },
     "communication-security":
     {
       "security-type":"SSL",
       "use-jvm-default-trust-store":true,
       "trust-store-file":"/path/to/trust-store.jks",
       "trust-store-type":"JKS",
       "verify-address-in-certificate":true
     },
     "authentication-details":
     {
       "authentication-type":"EXTERNAL",
       "authorization-id":""
     }
   }
 

The "GSSAPI" Authentication Type If you wish to authenticate connections with the GSSAPI SASL mechanism, then you can specify an "authentication-type" value of "GSSAPI". The following additional fields may be included in the "authentication-details" object for this authentication type:

• "authentication-id" -- The authentication ID to use to bind. This field must be present, and its value must be a string containing the authentication ID. Authentication ID values for a GSSAPI bind request are typically the Kerberos principal for the user to authenticate.
• "authorization-id" -- The alternate authorization identity to use for the connection after the bind has completed. If present, the value must be a string containing the desired authorization identity. If this field is absent, then no alternate authorization identity will be used.
• "password" -- The password to use to bind to the server. If this field is present, then its value must be a string that contains the clear-text password, or an empty string to indicate anonymous simple authentication. If it is not provided, then the "password-file" field may be used to specify the path to a file containing the bind password. If authentication will require the use of cached credentials, then the password may be omitted.
• "password-file" -- The path to a file containing the password to use to bind to the server. If this field is present, then its value must be a string that represents the path to a file containing a single line that contains the clear-text password. If it is not provided, then the "password" field may be used to specify the password. If authentication will require the use of cached credentials, then the password may be omitted.
• "realm" -- The realm to use for the bind request. If this field is present, then its value must be a string containing the name of the realm. If it is not provided, then the JVM will attempt to determine the realm from the underlying system configuration.
• "qop" -- The allowed quality of protection value(s) that may be used for the bind operation. If this field is present, then its value may be a single string or an array of strings indicating the allowed QoP values. Allowed values include "auth" (for just authentication), "auth-int" (for authentication followed by integrity protection for subsequent communication on the connection), and "auth-conf" (for authentication followed by confidentiality for subsequent communication on the connection). If this field is not present, then a default value of "auth" will be assumed.
• "kdc-address" -- The address of the Kerberos KDC to use during authentication. If this field is present, then its value must be a string containing the target address. If it is not provided, then the JVM will attempt to determine the address of the KDC from the underlying system configuration.
• "config-file-path" -- The path to a JAAS configuration file to use for bind processing. If this field is present, then its value must be a string containing the path to a valid JAAS configuration file. If it is not provided, a temporary JAAS configuration file will be created for the bind operation.
• "renew-tgt" -- Indicates whether successful authentication should attempt to renew the ticket-granting ticket for an existing session. If this field is present, then its value must be a boolean. If it is not provided, then a default of false will be assumed.
• "require-cached-credentials" -- Indicates whether the authentication process should require the use of cached credentials leveraged from an existing Kerberos session rather than try to create a new session. if this field is present, then its value must be a boolean. If it is not provided, then a default of false will be assumed.
• "use-ticket-cache" -- Indicates whether the authentication process should leverage a ticket cache in order to leverage an existing Kerberos session if the user has already authenticated to the KDC. If present, then its value must be a boolean. If it is not provided, then a default of true will be used.
• "ticket-cache-path" -- Specifies the path to the Kerberos ticket cache to use. If this is provided, its value must be a string with the path to the desired ticket cache. If it is not provided, then the JVM will attempt to determine the appropriate ticket cache from the underlying system configuration.
• "use-subject-credentials-only" -- Indicates whether authentication should require the client will be required to use credentials that match the current subject. If it is provided, then the value must be a boolean. If it is not provided, then a default of true will be assumed.

For Example:

   {
     "server-details":
     {
       "single-server":
       {
         "address":"ldap.example.com",
         "port":389
       }
     },
     "authentication-details":
     {
       "authentication-type":"GSSAPI",
       "authentication-id":"john.doe@EXAMPLE.COM",
       "password-file":"/path/to/password.txt",
       "renew-tgt":true
     }
   }
 

The "PLAIN" Authentication Type If you wish to authenticate connections with the PLAIN SASL mechanism, then you can specify an "authentication-type" value of "PLAIN". The following additional fields may be included in the "authentication-details" object for this authentication type:

• "authentication-id" -- The authentication ID to use to bind. This field must be present, and its value must be a string containing the authentication ID. Authentication ID values typically take the form "dn:" followed by the user DN, or "u:" followed by the username.
• "authorization-id" -- The alternate authorization identity to use for the connection after the bind has completed. If present, the value must be a string containing the desired authorization identity. If this field is absent, then no alternate authorization identity will be used.
• "password" -- The password to use to bind to the server. If this field is present, then its value must be a string that contains the clear-text password, or an empty string to indicate anonymous simple authentication. If it is not provided, then the "password-file" field must be used to specify the path to a file containing the bind password.
• "password-file" -- The path to a file containing the password to use to bind to the server. If this field is present, then its value must be a string that represents the path to a file containing a single line that contains the clear-text password. If it is not provided, then the "password" field must be used to specify the password.

For Example:

   {
     "server-details":
     {
       "single-server":
       {
         "address":"ldap.example.com",
         "port":389
       }
     },
     "authentication-details":
     {
       "authentication-type":"PLAIN",
       "authentication-id":"dn:uid=john.doe,ou=People,dc=example,dc=com",
       "password-file":"/path/to/password.txt"
     }
   }
 

The "authentication-details" field is optional, and if it is omitted from the specification then no authentication will be performed.

The "connection-pool-options" Section

The "connection-pool-options" section may be used to provide information about a number of settings that may be used in the course of creating or maintaining a connection pool. The value of the "connection-pool-options" field must be a JSON object, and the following fields may appear in that object:

• "create-if-necessary" -- Indicates whether the connection pool should create a new connection if one is needed but none are available. If present, the value must be a boolean. If it is absent, then a default of true will be assumed.
• "health-check-get-entry-dn" -- The DN of an entry that should be retrieved during health check processing. If present, the value must be a string that represents the DN of the entry to retrieve, or an empty string to indicate that the server root DSE should be retrieved. If this field is absent, then no entry will be retrieved during health check processing.
• "health-check-get-entry-maximum-response-time-millis" -- The maximum length of time in milliseconds to wait for the entry to be returned in a get entry health check. If present, the value must be a positive integer. If it is not provided, then a default of 10000 (ten seconds) will be used.
• "initial-connect-threads" -- The number of threads to use when creating the initial set of connections for the pool. If this field is present, then the value must be a positive integer, with a value of one indicating that connection should be created in a single-threaded manner, and a value greater than one indicating that the initial connections should be established in parallel. If it is not provided, then a default of one will be used.
• "invoke-background-health-checks" -- Indicates whether the connection pool should periodically invoke health check processing on idle connections. If this field is present, then its value must be a boolean. If it is not present, then a default of true will be assumed.
• "invoke-checkout-health-checks" -- Indicates whether the connection pool should invoke health check processing on connections just before they are checked out of the pool to ensure that they are valid. If this field is present, then its value must be a boolean. If it is not present, then a default of false will be assumed.
• "invoke-create-health-checks" -- Indicates whether the connection pool should invoke health check processing on connections just after they are created. If this field is present, then its value must be a boolean. If it is not present, then a default of false will be assumed.
• "invoke-authentication-health-checks" -- Indicates whether the connection pool should invoke health check processing on connections just after they have been authenticated. This includes after a successful bind on a newly-created connection, and after calls to the connection pool's bindAndRevertAuthentication and releaseAndReAuthenticateConnection methods. If this field is present, then its value must be a boolean. If it is not present, then a default of false will be assumed.
• "invoke-exception-health-checks" -- Indicates whether the connection pool should invoke health check processing on connections just after an exception is caught that might indicate that the connection is no longer valid. Note that this only applies to exceptions caught during operations processed directly against the connection pool and not to exceptions caught on a connection checked out of the pool. If this field is present, then its value must be a boolean. If it is not present, then a default of true will be assumed.
• "invoke-release-health-checks" -- Indicates whether the connection pool should invoke health check processing on connections just before they are released back to the pool to ensure that they are valid. If this field is present, then its value must be a boolean. If it is not present, then a default of false will be assumed.
• "maximum-connection-age-millis" -- Specifies the maximum length of time (in milliseconds) that a connection should be allowed to remain established before it is eligible to be closed and replaced with a newly-created connection. If present, then the value must be a positive integer to specify the maximum age, or zero to indicate that no maximum age should be applied. If it is not present, then a default value of zero will be used.
• "maximum-defunct-replacement-connection-age-millis" -- Specifies the maximum connection age (in milliseconds) that should be used for connections created to replace a defunct connection. If present, then the value must be a positive integer to specify the maximum age, or zero to indicate that no maximum age should be applied. If it is not present, then the value of the "maximum-connection-age-millis" field will be used for connections created as replacements for defunct connections.
• "maximum-wait-time-millis" -- Specifies the maximum length of time (in milliseconds) that the pool should wait for a connection to be released if one is needed but none are immediately available. If present, then this value must be a positive integer to specify the length of time to wait, or zero to indicate that it should not wait at all. If it is not provided, then a default value of zero will be used.
• "retry-failed-operations-due-to-invalid-connections" -- Indicates whether the pool should automatically attempt to retry operations attempted directly against the pool (but not for connections checked out of the pool) if the initial attempt fails in a manner that may indicate that the connection is no longer valid. If this field is present, then its value may be either a boolean to indicate whether to enable retry for all types of operations or no operations, or it may be an array of strings indicating the operation types ("add", "bind", "compare", "delete", "extended", "modify", "modify-dn", or "search") that should be retried in the event of a failure. If this field is not present, then no automatic retry will be attempted.

The "connection-pool-options" field is optional, and if it is omitted from the specification then the default values will be used for all options.

Constructor Summary

Constructors

Constructor and Description
LDAPConnectionDetailsJSONSpecification(JSONObject connectionDetailsObject) Creates a new LDAP connection details object from the specification contained in the provided JSON object.

Method Summary

Modifier and Type	Method and Description
LDAPConnection	createConnection() Creates a new LDAP connection based on the JSON specification.
LDAPConnectionPool	createConnectionPool(int initialConnections, int maximumConnections) Creates a new LDAP connection pool based on the JSON specification.
LDAPConnection	createUnauthenticatedConnection() Creates a new LDAP connection based on the JSON specification.
LDAPConnectionPool	createUnauthenticatedConnectionPool(int initialConnections, int maximumConnections) Creates a new LDAP connection pool based on the JSON specification.
static LDAPConnectionDetailsJSONSpecification	fromFile(java.io.File file) Creates a new LDAP connection details object from the specification contained in the JSON object read from the indicated file.
static LDAPConnectionDetailsJSONSpecification	fromFile(java.lang.String path) Creates a new LDAP connection details object from the specification contained in the JSON object read from the indicated file.
static LDAPConnectionDetailsJSONSpecification	fromInputStream(java.io.InputStream inputStream) Creates a new LDAP connection details object from the specification contained in the JSON object read from the provided input stream.
static LDAPConnectionDetailsJSONSpecification	fromString(java.lang.String jsonString) Creates a new LDAP connection details object from the specification contained in the JSON object represented by the given string.
BindRequest	getBindRequest() Retrieves the bind request that may be used to authenticate connections created from the JSON specification.
ServerSet	getServerSet() Retrieves the server set that may be used to create new connections based on the JSON specification.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

LDAPConnectionDetailsJSONSpecification

public LDAPConnectionDetailsJSONSpecification(@NotNull
                                              JSONObject connectionDetailsObject)
                                       throws LDAPException

Creates a new LDAP connection details object from the specification contained in the provided JSON object.

Parameters:

connectionDetailsObject - The JSON object that contains information that may be used to create LDAP connections.

Throws:

LDAPException - If the provided JSON object does not contain a valid connection details specification.

Method Detail

fromString

@NotNull
public static LDAPConnectionDetailsJSONSpecification fromString(@NotNull
                                                                         java.lang.String jsonString)
                                                                  throws JSONException,
                                                                         LDAPException

Creates a new LDAP connection details object from the specification contained in the JSON object represented by the given string.

Parameters:

jsonString - The string representation of the JSON object that contains information that may be used to create LDAP connections.

Returns:

The LDAP connection details object parsed from the provided JSON object string.

Throws:

JSONException - If the provided string cannot be parsed as a valid JSON object.

LDAPException - If the parsed JSON object does not contain a valid connection details specification.

fromFile

@NotNull
public static LDAPConnectionDetailsJSONSpecification fromFile(@NotNull
                                                                       java.lang.String path)
                                                                throws java.io.IOException,
                                                                       JSONException,
                                                                       LDAPException

Creates a new LDAP connection details object from the specification contained in the JSON object read from the indicated file.

Parameters:

path - The path to a file containing a JSON object with information that may be used to create LDAP connections.

Returns:

The LDAP connection details object parsed from the information in the specified file.

Throws:

java.io.IOException - If a problem is encountered while reading from the specified file.

JSONException - If the contents of the specified file cannot be parsed as a valid JSON object.

LDAPException - If the parsed JSON object does not contain a valid connection details specification.

fromFile

@NotNull
public static LDAPConnectionDetailsJSONSpecification fromFile(@NotNull
                                                                       java.io.File file)
                                                                throws java.io.IOException,
                                                                       JSONException,
                                                                       LDAPException

Creates a new LDAP connection details object from the specification contained in the JSON object read from the indicated file.

Parameters:

file - The file containing a JSON object with information that may be used to create LDAP connections.

Returns:

The LDAP connection details object parsed from the information in the specified file.

Throws:

java.io.IOException - If a problem is encountered while reading from the specified file.

JSONException - If the contents of the specified file cannot be parsed as a valid JSON object.

LDAPException - If the parsed JSON object does not contain a valid connection details specification.

fromInputStream

@NotNull
public static LDAPConnectionDetailsJSONSpecification fromInputStream(@NotNull
                                                                              java.io.InputStream inputStream)
                                                                       throws java.io.IOException,
                                                                              JSONException,
                                                                              LDAPException

Creates a new LDAP connection details object from the specification contained in the JSON object read from the provided input stream. The entire contents of the stream must be exactly one JSON object. Because the input stream will be fully read, it will always be closed by this method.

Parameters:

inputStream - The input stream from which to read a JSON object with information that may be used to create LDAP connections. The entire contents of the stream must be exactly one JSON object. Because the input stream will be fully read, it will always be closed by this method.

Returns:

The LDAP connection details object parsed from the information read from the provided input stream.

Throws:

java.io.IOException - If a problem is encountered while reading from the provided input stream.

JSONException - If the contents of the specified file cannot be parsed as a valid JSON object.

LDAPException - If the parsed JSON object does not contain a valid connection details specification.

getServerSet

@NotNull
public ServerSet getServerSet()

Retrieves the server set that may be used to create new connections based on the JSON specification.

Returns:

The server set that may be used to create new connections based on the JSON specification.

getBindRequest

@Nullable
public BindRequest getBindRequest()

Retrieves the bind request that may be used to authenticate connections created from the JSON specification.

Returns:

The bind request that may be used to authenticate connections created from the JSON specification, or null if the connections should be unauthenticated.

createConnection

@NotNull
public LDAPConnection createConnection()
                                         throws LDAPException

Creates a new LDAP connection based on the JSON specification. The connection will be authenticated if appropriate.

Returns:

The LDAP connection that was created.

Throws:

LDAPException - If a problem is encountered while trying to establish or authenticate the connection.

createUnauthenticatedConnection

@NotNull
public LDAPConnection createUnauthenticatedConnection()
                                                        throws LDAPException

Creates a new LDAP connection based on the JSON specification. No authentication will be performed on the connection.

Returns:

The LDAP connection that was created.

Throws:

LDAPException - If a problem is encountered while trying to establish the connection.

createConnectionPool

@NotNull
public LDAPConnectionPool createConnectionPool(int initialConnections,
                                                        int maximumConnections)
                                                 throws LDAPException

Creates a new LDAP connection pool based on the JSON specification. The pooled connections will be authenticated if appropriate.

Parameters:

initialConnections - The number of connections that should be established at the time the pool is created.

maximumConnections - The maximum number of connections that should be available in the pool at any time.

Returns:

The LDAP connection pool that was created.

Throws:

LDAPException - If a problem is encountered while attempting to create the connection pool.

createUnauthenticatedConnectionPool

@NotNull
public LDAPConnectionPool createUnauthenticatedConnectionPool(int initialConnections,
                                                                       int maximumConnections)
                                                                throws LDAPException

Creates a new LDAP connection pool based on the JSON specification. No authentication will be used for connections that are part of the pool.

Parameters:

initialConnections - The number of connections that should be established at the time the pool is created.

maximumConnections - The maximum number of connections that should be available in the pool at any time.

Returns:

The LDAP connection pool that was created.

Throws:

LDAPException - If a problem is encountered while attempting to create the connection pool.