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 JNDI Tutorial.
The LDAP service provider implements the basic features for LDAP access. Additional functionality, such as support for a number of popular LDAP controls, for SASL authentication, 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 JNDI Web site.
Standard | Supported | Comments |
---|---|---|
LDAPv3 (RFC-2251) | Yes | |
LDAPv3 Attributes (RFC-2252) | Yes | |
LDAPv3 Distinguished Names (RFC-2253) | Yes | |
LDAP Search Filters (RFC-2254) | Yes | |
LDAP URL Format (RFC-2255) | Yes | |
LDAPv3 Schema (RFC-2256) | Yes | |
LDAPv2 (RFC-1777) | 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 | |
java.naming.referral | Yes | |
java.naming.security.authentication | Yes | simple, none |
java.naming.security.credentials | Yes | |
java.naming.security.principal | Yes | |
java.naming.security.protocol | Yes |
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 |
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 RFC-2253. |
LDAP URL String | When passed to the initial context, the LDAP URL string is interpreted according to RFC-2255, and its distinguished name component interpreted according to RFC-2253. |
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 RFC-2253.
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).
URL usage | Supported | Comments |
---|---|---|
LDAP URLs to configure the LDAP service provider. | Yes | |
URLs passed as names to the InitialDirContext methods. | Yes | The attributes, scope, filter and extensions components of LDAP URLs are ignored by the search methods. |
URLs in LDAP referrals | Yes | The scope component of LDAP 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 |
Storable/Readable Objects | Supported | Comments |
---|---|---|
Reference objects | Yes | |
Referenceable objects | Yes | |
Serializable objects | Yes | |
DirContext objects | Yes |
See the JNDI Tutorial for examples.
Schema Tree | Supported | Comments |
---|---|---|
AttributeDefinition | Yes | Attribute definitions may be added or deleted but not modified. |
ClassDefinition | Yes | Class definitions may be added or deleted but not modified. |
SyntaxDefinition | Yes | Syntax definitions may be added or deleted but not modified. |
MatchingRule | Yes | Matching rules may be added or deleted but not modified. |
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 | |
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 |
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.