Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.unboundid.util.json
Class LDAPConnectionDetailsJSONSpecification

java.lang.Object
  extended by 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: 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: 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: 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 use a trust store to determine whether to trust the certificate presented by the server, and 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",
       "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:
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: 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: 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: 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: For Example: 
   {
     "server-details":
     {
       "single-server":
       {
         "address":"ldap.example.com",
         "port":636
       }
     },
     "communication-security":
     {
       "security-type":"SSL",
       "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: For Example: 
   {
     "server-details":
     {
       "single-server":
       {
         "address":"ldap.example.com",
         "port":389
       }
     },
     "authentication-details":
     {
       "authentication-type":"GSSAPI",
       "authentication-id":"[email protected]",
       "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: 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:
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
LDAPConnectionDetailsJSONSpecification(JSONObject connectionDetailsObject)
          Creates a new LDAP connection details object from the specification contained in the provided JSON object.
 
Method Summary
 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(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

public static LDAPConnectionDetailsJSONSpecification fromString(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

public static LDAPConnectionDetailsJSONSpecification fromFile(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

public static LDAPConnectionDetailsJSONSpecification fromFile(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

public static LDAPConnectionDetailsJSONSpecification fromInputStream(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

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

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

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

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

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

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.
Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD