Spec-Zone .ru
спецификации, руководства, описания, API
|
|
Spec-Zone .ru
спецификации, руководства, описания, API
|
Please send feedback to jndi@java.sun.com
Table of Contents
This document describes the features of the LDAP service provider. A major portion of the description is couched in terms of how the LDAP service provider behaves with respect to the descriptions in Guidelines for LDAP Service Providers. For examples and descriptions of how to use this provider, please see the .
The LDAP service provider implements the basic features for LDAP access. Additional functionality, such as support for a number of popular LDAP controls, and for storing and reading RMI and CORBA objects, can be added to the basic provider by installing a booster pack, available for download at the .
| Standard | Supported | Comments |
|---|---|---|
| LDAPv3 () | Yes | |
| LDAPv3 Attributes () | Yes | |
| LDAPv3 Distinguished Names () | Yes | |
| LDAP Search Filters () | Yes | |
| LDAP URL Format () | Yes | |
| LDAPv3 Schema () | Yes | |
| LDAPv2 () | Yes | |
| LDAP Authentication () | Yes | |
| Start TLS Extension () | Yes | |
| DIGEST-MD5 () | Yes | |
| Manage Referral Control () | Yes | |
| Paged Results Control () | Yes | |
| Sort Control () | Yes |
| Property | Supported | Comments |
|---|---|---|
| java.naming.batchsize | Yes | Default value is 1. |
| java.naming.factory.control | Yes | |
| java.naming.factory.initial | Yes | Specify com.sun.jndi.ldap.LdapCtxFactory to use the LDAP service provider as the initial context. |
| java.naming.factory.object | Yes | |
| java.naming.factory.state | Yes | |
| java.naming.language | No | Ignored by the provider. |
| java.naming.provider.url | Yes | On systems earlier than the Java 2 SDK, v 1.4.1, can contain only a single URL. On systems earlier than the Java 2 SDK, v 1.4.2, cannot contain LDAPS URLs. |
| java.naming.referral | Yes | |
| java.naming.security.authentication | Yes | simple, none, list of SASL mechanisms |
| java.naming.security.credentials | Yes | |
| java.naming.security.principal | Yes | |
| java.naming.security.protocol | Yes | ssl |
| Property | Supported | Comments |
|---|---|---|
| java.naming.ldap.attributes.binary | Yes | |
| java.naming.ldap.control.connect | Yes | |
| java.naming.ldap.deleteRDN | Yes | |
| java.naming.ldap.derefAliases | Yes | |
| java.naming.ldap.factory.socket | Yes | Default value is javax.net.ssl.SSLSocketFactory when the java.naming.security.protocol property is set to ssl. See the SSL Section for details. |
| java.naming.ldap.ref.separator | Yes | |
| java.naming.ldap.referral.limit | Yes | |
| java.naming.ldap.typesOnly | Yes | |
| java.naming.ldap.version | Yes |
| Property | Supported | Comments |
|---|---|---|
| java.naming.security.sasl.authorizationId | Yes | |
| java.naming.security.sasl.callback | Yes | |
| java.naming.security.sasl.realm | Yes | |
| javax.security.sasl.qop | Yes | |
| javax.security.sasl.strength | Yes | Cipher selected depends on the ciphers available from the |
| javax.security.sasl.maxbuffer | Yes | |
| javax.security.sasl.server.authentication | Yes | |
| javax.security.sasl.policy.forward | Yes | |
| javax.security.sasl.policy.credentials | Yes | |
| javax.security.sasl.policy.noplaintext | Yes | |
| javax.security.sasl.policy.noactive | Yes | |
| javax.security.sasl.policy.nodictionary | Yes | |
| javax.security.sasl.policy.noanonymous | Yes |
This property is used to specify that a pooled connection should be used when creating the initial context instance. If its value is "true", the provider will use a pooled connection if the parameters for creating a connection (referred to as the connection request) meet the criteria set forth by the connection pool configuration. If this property has not been set, or if it has been set to any other value, or if the connection request does not meet the criteria, the provider will not use a pooled connection. See the Connection Pooling section for more information on connection pooling.For example, the following code
env.put("com.sun.jndi.ldap.connect.pool", "true");directs the LDAP provider to use a pooled connection when creating an initial context.NOTE: On systems earlier than the Java 2 SDK, v 1.4.1, connection pooling is not supported and therefore, this property is ignored.
The value of this property is the string representation of an integer representing the connection timeout in milliseconds. If the LDAP provider cannot establish a connection within that period, it aborts the connection attempt. The integer should be greater than zero. An integer less than or equal to zero means to use the network protocol's (i.e., TCP's) timeout value.If this property is not specified, the default is to wait for the connection to be established or until the underlying network times out.
For example,
env.put("com.sun.jndi.ldap.connect.timeout", "500");causes the LDAP service provider to abort the connection attempt if a connection cannot be established in half a second.When connection pooling has been requested for a connection, this property also determines the maximum wait time for a connection when all connections in the pool are in use and the maximum pool size has been reached. If the value of this property is less than or equal to zero under such circumstances, the provider will wait indefinitely for a connection to become available; otherwise, the provider will abort the wait when the maximum wait time has been exceeded. See the Connection Pooling section for details.
NOTE: On systems earlier than the Java 2 SDK, v 1.4, this property is ignored because there is no support in the SDK for connection timeouts.
com.sun.jndi.ldap.read.timeout
The value of this property is the string representation of an integer representing the read timeout in milliseconds for LDAP operations. If the LDAP provider cannot get a LDAP response within that period, it aborts the read attempt. The integer should be greater than zero. An integer less than or equal to zero means no read timeout is specified which is equivalent to waiting for the response infinitely until it is received.If this property is not specified, the default is to wait for the response until it is received.
For example,
env.put("com.sun.jndi.ldap.read.timeout", "5000");causes the LDAP service provider to abort the read attempt if the server does not respond with a reply within 5 seconds.NOTE: On systems earlier than the Java SDK, v 6.0, this property is ignored because there is no support in the SDK for read timeouts.
The Netscape Directory Server 4.0 and earlier releases do not support schema entries that comply with RFC 2252. Specifically, contrary to RFC 2252, the Netscape server requires OIDs (such as those for SUP and SYNTAX) be delimited by single quotes and MUST/MAY lists be enclosed by parentheses. When you update the schema of the Netscape Directory Server 4.0, you need to use this property to get around these problems.The following values are defined for this property:
true
activate the workaround.
false
do not activate the workaround.If this property is not set then its default value is false.
For example,
activates the workaround.env.put("com.sun.jndi.ldap.netscape.schemaBugs", "true");NOTE 1: This property may only be passed to the initial context and becomes fixed for the provider. It is unaffected by the addToEnvironment or removeFromEnvironment methods.
NOTE 2: If you are using Netscape Directory Server 4.1, do not use this property. The 4.1 server has problems parsing object class definitions that contain MUST/MAY clauses without parentheses. If you are creating or modifying an object class definition that contains a single MUST/MAY item, work around the bug by adding a superfluous value (such as 'objectClass') to the MUST/MAY list.
The value of this property is a java.io.OutputStream object into which a hexadecimal dump of the incoming and outgoing LDAP ASN.1 BER packets is written.No default is defined for this property.
For example,
env.put("com.sun.jndi.ldap.trace.ber", System.out);directs the LDAP protocol trace to the standard output stream.NOTE: This property may only be passed to the initial context and becomes fixed for the provider. It is unaffected by the addToEnvironment or removeFromEnvironment methods.
| Distinguished Name format | Comments |
|---|---|
| String | Treat as composite name. Process the first component of the composite name as a distinguished name. Use rest of the components for federation. |
| Name | If instance of CompositeName, treat as composite name, which means process the first component of the composite name as a distinguished name and use the rest for federation. Otherwise, treat as parsed LDAP name, where each component of Name is a component of the LDAP name as defined in . |
| LDAP URL String | When passed to the initial context, the LDAP URL string is interpreted according to , and its distinguished name component interpreted according to . |
| LDAPS URL String | When passed to the initial context, the
LDAPS URL string is interpreted like an LDAP URL, except that an
SSL connection is used to communicate with the server.
NOTE: On systems earlier than the Java 2 SDK, v 1.4.2, the LDAP service provider does not recognize LDAPS URLs. |
The name parser returned by an invocation of getNameParser() returns a parser that, when given a string name, parses it into components in accordance with .
| Attribute value format | Supported | Comments |
|---|---|---|
| String values | Yes | |
| byte[] values | Yes |
Some LDAP servers support attribute subtyping, attribute name synonyms, and language codes for specifying language preferences for attribute values. In such cases, the attribute name returned by an LDAP server may be different from the one which was requested.
In LDAP, attribute names are case-insensitive. Therefore, when creating a collection of attributes to be passed as a parameter to JNDI operations, it is recommended to use a case-insensitive attributes class. For example,
Attributes attrs = new BasicAttributes(true); // ignoreCase=true
For all attribute values, regardless of whether they are String or byte[], you need to know the syntax and format of the attribute value. You can typically find this out by reading the schema document in which the attribute and its syntax is defined.
When attributes are supplied as arguments to JNDI calls then they must satisfy whatever schema is enforced at the LDAP directory. In particular, the objectClass attribute is normally required when creating a new LDAP entry (for example, when using Context.bind, Context.rebind or DirContext.createSubcontext).
It supports the following use of URLs:
| URL usage | Supported | Comments |
|---|---|---|
| LDAP and LDAPS URLs to configure the LDAP service provider. | Yes | |
| URLs passed as names to the InitialDirContext methods. | Yes | |
| URLs in LDAP referrals | Yes | The scope component of LDAP/LDAPS URLs is supported. The attributes, filter and extensions components are ignored. |
| URLs returned as names in list, listBindings, and search enumerations. | Yes | |
| URLs linking federated namespaces. | Yes |
NOTE: On systems earlier than the Java 2 SDK, v 1.4.2, the LDAP service provider does not recognize or return LDAPS URLs.
For example, given a URL of ldap:///dc=example,dc=com, the service provider will try to locate the DNS SRV records for _ldap._tcp.example.com. If the provider finds such records, it will then extract and use the hostnames and ports of the LDAP servers from the records. The order in which it uses these records follows the algorithm described in the Internet draft .
For locating the DNS SRV records of the LDAP service, the LDAP service provider uses the DNS service configured for the underlying platform (on Solaris or Linux, for example, the DNS client configuration is read from the /etc/resolv.conf file). If DNS has not been configured for the underlying platform, the LDAP service provider will use localhost and 53 as the hostname and port of the DNS server. If no DNS service is available, or if the DNS service does not have the LDAP service's SRV records, the LDAP service provider will use localhost as the hostname, and 389 as the port for a plain connection and 636 as the port for an SSL connection.
NOTE 1: On systems earlier than the Java 2 SDK, v 1.4.1, unspecified hostname and port always default to localhost and 389, respectively; no attempt is made to use DNS.
NOTE 2: On systems earlier than the Java 2 SDK, v 1.4.2, the default port is always 389 regardless of whether SSL is being used.
| Storable/Readable Objects | Supported | Comments |
|---|---|---|
| Reference objects | Yes | |
| Referenceable objects | Yes | |
| Serializable objects | Yes | |
| DirContext objects | Yes |
See the for examples.
| Schema Tree | Supported | Comments |
|---|---|---|
| AttributeDefinition | Yes | |
| ClassDefinition | Yes | |
| SyntaxDefinition | Yes | |
| MatchingRule | Yes | |
| ExtensionDefinition | No | |
| ControlDefinition | No | |
| SASLMechanism | No |
| Mapping for Context methods | Supported | Comments |
|---|---|---|
| addToEnvironment | Yes | |
| bind | Yes | |
| close | Yes | |
| composeName | Yes | |
| destroySubcontext | Yes | |
| getEnvironment | Yes | |
| getNameInNamespace | Yes | |
| getNameParser | Yes | |
| list | Yes | |
| listBindings | Yes | |
| lookup | Yes | Does not process LinkRef specially. |
| lookupLink | Yes | |
| rebind | Yes | |
| removeFromEnvironment | Yes | |
| rename | Yes | |
| unbind | Yes |
| Mapping for DirContext methods | Supported | Comments |
|---|---|---|
| bind | Yes | |
| createSubcontext | Yes | |
| destroySubcontext | Yes | |
| getAttributes | Yes | |
| getSchema | Yes | |
| getSchemaClassDefinition | Yes | |
| modifyAttributes | Yes | |
| rebind | Yes | |
| search | Yes |
| Mapping for LdapContext methods | Supported | Comments |
|---|---|---|
| extendedOperation | Yes | |
| getRequestControls | Yes | |
| getResponseControls | Yes | |
| newInstance | Yes | |
| reconnect | Yes | |
| setRequestControls | Yes |
| Mapping for EventDirContext methods | Supported | Comments |
|---|---|---|
| addNamingListener | Yes | |
| removeNamingListener | Yes | |
| targetMustExist | Yes |
| Federation Technique | Supported | Comments |
|---|---|---|
| Junction | Yes | Except when subordinate naming system is another LDAP system |
| Implicit Next Naming System Pointer | Yes |
The LDAP service provider treats composite names as strongly separated. That is, it processes the first component of the composite name as a distinguished name and the rest of the components as names in the next naming system(s). For example, here are examples that lists the root of the next naming system federated beyond an LDAP context and looks up a name using a multicomponent composite name:
// List the root of the nns,
// Note use of the trailing slash to indicate traversal into the nns
NamingEnumeration enum = ctx.list("cn=objects,ou=Sales/");
// A composite name lookup
Object obj = ctx.lookup("cn=objects,ou=Sales/some/x/y/z");
| Event | Supported | Comments |
|---|---|---|
| Namespace change notification | Yes | Uses the persistent search control* |
| Object change notification | Yes | Uses the persistent search control* |
| Unsolicited notification | Yes |
* The persistent search control is defined in the IETF Internet-Draft draft-ietf-ldapext-psearch-03.txt.
The LDAP service provider supports the following SASL mechanisms.
When SSL is being used and no port has been specified, 636 is used as the default port.
NOTE: On Java 2 SDK, v 1.4.1 and earlier systems, the default port is always 389, regardless of whether SSL is being used.
NOTE: Connection pooling is supported only on the Java 2 SDK, v 1.4.1 and later releases.
The LDAP service provider supports connection pooling by maintaining pools of previously used connections. Whenever the LDAP provider needs a connection (and the application has requested pooling), it gets a connection from the pool. If an existing connection is available, it will be used. If no existing connection is available, a new connection is created and used. When the provider is done with the connection, the connection is marked idle and can be reused.
An application requests connection pooling by adding the property, com.sun.jndi.ldap.connect.pool, to the environment properties passed to the initial context constructor. An application can decide whether to use pooling on a per-context basis by using environment properties with and without this property. This same mechanism is used to control whether pooled connections are used for referral handling and processing of LDAP/LDAPS URLs passed to the initial context. For example, when this property is present in the environment when the provider is processing a referral, the provider will use a pooled connection for the referral.
Here is sample code that requests that connection pooling be used for a new initial context and all contexts derived from it.
Hashtable env = new Hashtable();
env.put("com.sun.jndi.ldap.connect.pool", "true");
env.put(Context.PROVIDER_URL, url);
env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.ldap.LdapCtxFactory");
DirContext ctx = new InitialDirContext(env);
...
Only the addition of the single property, com.sun.jndi.ldap.connect.pool, is required; no other changes are required to the application.
The LDAP provider keeps track of whether a connection is being used through indications from the application. It assumes that an application that is maintaining an open context handle is using the connection. Therefore, in order for the LDAP provider to properly manage the pooled connections, the application must be diligent about invoking Context.close() on contexts that it no longer needs.
Bad connections are automatically detected and removed from the pool. The probability of a context ending up with a bad connection is the same regardless of whether connection pooling is used.
Connection pooling is configured by a number of System properties at runtime startup time. Note that these are System properties, not environment properties and that they affect all connection pooling requests.
Here is a summary of the system properties. They are described in more detail in the rest of this section.
| System Property Name | Description | Default |
|---|---|---|
| com.sun.jndi.ldap.connect.pool.authentication | A list of space-separated authentication types of connections that may be pooled. Valid types are "none", "simple", and "DIGEST-MD5". | "none simple" |
| com.sun.jndi.ldap.connect.pool.debug | A string that indicates the level of debug output to produce. Valid values are "fine" (trace connection creation and removal) and "all" (all debugging information). | |
| com.sun.jndi.ldap.connect.pool.initsize | The string representation of an integer that represents the number of connections per connection identity to create when initially creating a connection for the identity. | 1 |
| com.sun.jndi.ldap.connect.pool.maxsize | The string representation of an integer that represents the maximum number of connections per connection identity that can be maintained concurrently. | no maximum size |
| com.sun.jndi.ldap.connect.pool.prefsize | The string representation of an integer that represents the preferred number of connections per connection identity that should be maintained concurrently. | no preferred size |
| com.sun.jndi.ldap.connect.pool.protocol | A list of space-separated protocol types of connections that may be pooled. Valid types are "plain" and "ssl". | "plain" |
| com.sun.jndi.ldap.connect.pool.timeout | The string representation of an integer that represents the number of milliseconds that an idle connection may remain in the pool without being closed and removed from the pool. | no timeout |
Here is an example that sets the maximum pool size to 20, the preferred pool size to 10, and the idle timeout to 5 minutes for pooled connections.
# java -Dcom.sun.jndi.ldap.connect.pool.maxsize=20 \
-Dcom.sun.jndi.ldap.connect.pool.prefsize=10 \
-Dcom.sun.jndi.ldap.connect.pool.timeout=300000 \
YourProgram
To allow SSL connections to be pooled, include the string "ssl" in the com.sun.jndi.ldap.connect.pool.protocol System property. For example, to allow both plain and SSL connections to be pooled, set this System property to the string "plain ssl".
To allow DIGEST-MD5 connections to be pooled, include the string "DIGEST-MD5" in the com.sun.jndi.ldap.connect.pool.authentication System property. For example, to allow connections of anonymous, simple and DIGEST-MD5 authentication types to be pooled, set this System property to the string "none simple DIGEST-MD5".
A connection identity is the set of the parameters required to create a possibly authenticated LDAP connection. Its composition depends on the authentication type of the request, as shown in the following table.
| Authentication type | Connection identity contents |
|---|---|
| none |
|
| simple |
|
| DIGEST-MD5 |
|
public class CustomSocketFactory extends SocketFactory
implements Comparator<SocketFactory> {
:
:
public int compare(SocketFactory sf1, SocketFactory sf2) {
:
:
// do whatever comparison that's required
}
}
If the socket factory class does not implement Comparator interface, the connections from that socket factory class do not get pooled. This requirement for implementing the Comparator interface is to ensure that the LDAP Service Provider does the necessary checks when comparing connections from different socket factories whose implementation is not known to the provider.
The initial pool size is the number of connections per connection identity that the LDAP service provider creates when first creating the pool (which corresponds to when the application first requests a pooled connection for that connection identity). Authentication of each connection in the pool is performed on demand, as the connection gets used. By default, the initial pool size is 1 and can be changed by using the System property com.sun.jndi.ldap.connect.pool.initsize. It is typically used at application start-up time to prime the pool with a certain number of connections to a server.
The maximum pool size is the maximum number of connections per connection identity that can be maintained concurrently by the LDAP service provider. Both in-use and idle connections contribute to this number. When the pool size reaches this number, no new connection for the corresponding connection identity may be created until a connection in the pool has been removed (i.e., the physical connection is closed). When the pool size reaches the maximum and all of the connections in the pool are in use, the application's request for a connection from that pool is blocked until a connection in the pool either becomes idle or is removed. A maximum pool size of 0 means that there is no maximum size: A request for a pooled connection will use an existing pooled idle connection or a newly created pooled connection.
The preferred pool size is the preferred number of connections per connection identity that the LDAP service provider should maintain. Both in-use and idle connections contribute to this number. When an application requests the use of a pooled connection and the pool size is less than the preferred size, the LDAP provider will create and use a new pooled connection regardless of whether an idle connection is availble. When an application is finished with a pooled connection (by invoking Context.close() on all contexts that share the connection) and the pool size is greater than the preferred size, the LDAP provider will close and remove the pooled connection from the pool. A preferred pool size of 0 means that there is no preferred size: A request for a pooled connection will result in a newly created connection only if no idle ones are available.
Note that the maximum pool size overrides both the initial and preferred pool sizes. For example, setting the preferred pool size greater than the maximum pool size is effectively setting it to the maximum pool size.
If this property is omitted, the context will not use connection pooling.
If this property has not been specified, the LDAP provider will wait indefinitely for a pooled connection to become available, and to wait for the default TCP timeout to take effect when creating a new connection.
Note that this property is different from the System property com.sun.jndi.ldap.connect.pool.timeout, which is related to the removal of idle pooled connections.
permission java.net.SocketPermission "host[:port]", "connect";
For each host/port identified in the java.naming.factory.initial property and in URL string names supplied to context methods.
permission java.net.SocketPermission "host[:port]", "connect,accept";
For each host/port named in the URL strings in References and javaCodebase attributes stored with Serializable objects.If you are using SASL authentication and will be setting the SASL client factory programmatically, grant your application the following permission.
permission java.lang.RuntimePermission "setFactory"If you use the "GSSAPI" SASL mechanism, you need the following additional permissions.
permission javax.security.auth.AuthPermission "createLoginContext.appClassName"; permission javax.security.auth.AuthPermission "doAsPrivileged";
For the application class that's going to be logging in and invoking the doAsPrivileged method.
permission java.net.SocketPermission "host[:port]", "connect";
For the host/port of the Kerberos Key Distribution Center (KDC).
permission javax.security.auth.kerberos.ServicePermission "krbtgt/realm@realm", "initiate"; permission javax.security.auth.kerberos.ServicePermission "ldap/fully-qualified-hostname@realm", "initiate";
For the realm and host of the LDAP service and KDC.
| Java Technology |
Copyright © 1993, 2010, Oracle and/or its affiliates. All rights reserved. |