Previous | Next | Trail Map | Tips for LDAP Users | Miscellaneous

LDAP URLs

RFC 2255 describes the syntactic format of LDAP v3 URLs. The format contains all the elements necessary to specify an LDAP search operation, with provisions for supporting future v3 extensions:
ldap://host:port/dn?attributes?scope?filter?extensions
Authentication information may be specified in the extensions portion of the URL. See the RFC for a complete description of the format.

URLs play a role in several places in the JNDI. This section describes how LDAP URLs can be used with the LDAP service provider.

As a Name to the Initial Context

If you pass an LDAP URL to the methods in InitialContext(in the API reference documentation) or InitialDirContext(in the API reference documentation) , the JNDI will look for a context implementation (called a URL context implementation) to process the LDAP URL. Here is an example that performs a search from the initial context, using an LDAP URL as the name argument.
// Create initial context
DirContext ctx = new InitialDirContext();

// Perform search using URL
NamingEnumeration answer = ctx.search(
     "ldap://localhost:389/ou=People,o=JNDITutorial", "(sn=Geisel)", null);
This example produced the following output:
>>>cn=Ted Geisel
{sn=sn: Geisel, 
 objectclass=objectclass: top, person, organizationalPerson, inetOrgPerson, 
 jpegphoto=jpegphoto: [B@1dacd78a, 
 mail=mail: Ted.Geisel@JNDITutorial.com, 
 facsimiletelephonenumber=facsimiletelephonenumber: +1 408 555 2329, 
 telephonenumber=telephonenumber: +1 408 555 5252, 
 cn=cn: Ted Geisel}

You might have noticed that you did not need to set up any environment properties to perform this search. This is because the JNDI automatically searches for the URL context implementation, and will only use the implementation specified by the environment properties (if any) if the URL context implementation is not found. For an LDAP URL, it looks for a class with the name ldapURLContextFactory from package locations specified by the system or environment property Context.URL_PKG_PREFIXES(in the API reference documentation) (java.naming.url.pkg). This property contains a list of package prefixes separated by colon characaters (':'). If no class with the right name is found in these packages, the package "com.sun.jndi.url" is searched.

With the exception of the DirContext.search()(in the API reference documentation) methods, when an LDAP URL is passed as a name to the initial context, the URL should not contain any query ('?') components. Otherwise, an InvalidNameException(in the API reference documentation)is thrown by the LDAP service provider. For the search() methods, the query components of the URL override any corresponding components supplied as arguments. For example, if an LDAP URL containing a scope component is supplied, then that scope overrides any scope setting that may be passed in a SearchControls(in the API reference documentation) argument.


Note: Version 1.0.2 and earlier releases of Sun's LDAP provider does not treat query components properly.

For Configuring Service Provider

To configure an LDAP service provider, you typically supply an LDAP URL in the Context.PROVIDER_URL(in the API reference documentation) (java.naming.provider.url) environment or system property. This is used by the LDAP service provider to configure its connection to the directory server. Only the host, port, and dn parts of the URL are relevant in this setting. Supplying other parts of the URL results in a ConfigurationException(in the API reference documentation) .

For Specifying Referrals

An LDAP referral contains a list of one or more URLs. To process an LDAP referral, the service provider needs to use the information in the these URLs to create connections to the LDAP servers to which they refer. When multiple LDAP URLs are present in a single referral they are treated as alternatives and each is followed until one succeeds. The complete URL (that is, including any query components) are used.

You set up referrals by creating "referral" entries in the directory that contain the "REF" attribute. The "REF" attribute contains one or more referral URLs (usually LDAP URLs). See the Referrals (in the Tips for LDAP Users trail) lesson for details on referrals.

As a Name in NamingEnumeration

When you perform a Context.list()(in the API reference documentation) , Context.listBindings()(in the API reference documentation) , or DirContext.search()(in the API reference documentation) , you get back a NamingEnumeration(in the API reference documentation) . Each item in this enumeration is an instance or subclass of NameClassPair(in the API reference documentation) . When the name of the item ( NameClassPair.getName()(in the API reference documentation) ) is not relative to the target context, the name is returned as a URL. You can use NameClassPair.isRelative()(in the API reference documentation) to check whether the name is relative. One of the main reasons why the name might not be relative is because a referral was followed, in which case, the name of the object is that in the referred namespace, not the one at which the operation was initiated.

As Argument to NamingManager.getObjectInstance()

When an LDAP namespace is federated underneath another namespace (for example, such as DNS), the information that is stored in the superior namespace might be an LDAP URL. In such a scenario, a lookup/list/search operation in the superior namespace would return an LDAP URL for the LDAP namespace. The service provider for the superior namespace would then pass the LDAP URL to NamingManager.getObjectInstance()(in the API reference documentation) to create an instance of an LDAP context. See the Beyond the Basics (in the Beyond the Basics trail) trail for details on federation.

Miscellaneous: End of Lesson

What's next? Now you can:


Previous | Next | Trail Map | Tips for LDAP Users | Miscellaneous