![]() ![]() ![]() ![]() |
Miscellaneous |
URLs play a role in several places in the JNDI, as described in the URLslesson. This section describes how they can be used with the LDAP service provider.
URL Formats
RFC 2255 describes the syntactic format of LDAP v3 URLs. The format contains all of the elements necessary to specify an LDAP "search" operation, with provisions for supporting future version 3 extensions:The default hostname is localhost; the default port is 389. The default root distinguished name is the empty string. Authentication information may be specified in the extensions portion of the URL. See the RFC for a complete description of the format.ldap://host:port/dn?attributes?scope?filter?extensionsIn addition to LDAP URLs, the LDAP provider also supports the non-standard but widely used LDAPS URLs. LDAPS URLs use SSL connections instead of plain (i.e., unprotected) connections. They have a syntax similar to LDAP URLs except the schemes are different and the default port for LDAPS URLs is 636 instead of 389.
Note that use of LDAPS URLs has client and server requirements, as detailed in the SSL and Custom Socketsldaps://host:port/dn?attributes?scope?filter?extensionssection.
The LDAP provider also supports a special interpretation of LDAP and LDAPs URLs when they are used to name an LDAP service. If the URL contains neither host nor port information but contains a non-empty distinguished name, the LDAP provider will use the distinguished name to automatically discover the LDAP service, as described in the Connections
lesson.
Note: LDAPS URLs are supported only in the Java 2 SDK, v1.4.2 and later releases. Automatic discovery of the LDAP service using the URL's distinguished name is supported in the Java 2 SDK, v1.4.1 and later releases.
URL as a Name to the Initial Context
If you pass an LDAP or LDAPS URL to the methods in InitialContextor InitialDirContext
, then the JNDI will look for a context implementation (called a URL context implementation) to process the URL.
Here is an example that performs a search from the initial context, using an LDAP URL as the name argument.
This example produces the following output.// Create the initial context DirContext ctx = new InitialDirContext(); // Perform the search by using the URL NamingEnumeration answer = ctx.search( "ldap://localhost:389/ou=People,o=JNDITutorial", "(sn=Geisel)", null);>>>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. If the URL context implementation is not found, it will use only the implementation specified by the environment properties (if any). For an LDAP URL, it looks for a class with the name ldapURLContextFactory from package locations specified by the environment property Context.URL_PKG_PREFIXES
("java.naming.factory.url.pkgs"). This property contains a list of package prefixes separated by colon characters (":"). If no class with the right name is found in these packages, then the package com.sun.jndi.url.ldap is searched. For an LDAPS URL, a class with the name ldapsURLContextFactory is sought using the same algorithm, with the default package being com.sun.jndi.url.ldaps.
Query Components in a URL
With the exception of the DirContext.search()
methods, when an LDAP or LDAPS URL is passed as a name to the initial context, the URL should not contain any query ('?') components. If it does, then an InvalidNameException
is thrown by the LDAP service provider.
For the search() methods, if a URL contains query components, then all other arguments (including the filter and SearchControls
) are ignored. The query components of the URL and its defaults are used instead. For example, if an LDAP URL containing a scope component is supplied, then that scope overrides any scope setting that is passed in an argument. If the URL contains other query components but not the scope, then the LDAP URL's default scope ("base object") is used.
Here is an example that performs a subtree search by using a filter of "(sn=Geisel)".
// Perform the search by using URL NamingEnumeration answer = ctx.search( "ldap://localhost:389/ou=People,o=JNDITutorial??sub?(sn=Geisel)", "" /* ignored*/, null /* ignored */);
Note: Version 1.2 of Sun's LDAP provider does not treat query components properly.
URL for Configuring Service Providers
To configure an LDAP service provider, you typically supply an LDAP or LDAPS URL in the Context.PROVIDER_URL("java.naming.provider.url") environment property. The LDAP service provider uses this URL 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
.
Instead of just one URL, you can also supply a space-separated list of URLs. In this case, the LDAP provider will attempt to use each URL in turn until it is able to create a successful connection. The LDAP provider will then set the Context.PROVIDER_URL property to the successful URL, so that the application can determine which URL is being used.
Here is an example of how to specify a list of URLs.
Hashtable env = new Hashtable(11); env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.ldap.LdapCtxFactory"); // Specify list of space-separated URLs env.put(Context.PROVIDER_URL, "ldap://notthere:389/o=JNDITutorial " + "ldap://localhost:389/o=JNDITutorial " + "ldap://remotehost/o=JNDITutorial " + "ldap://thirdhost:389/o=JNDITutorial"); // Create initial context DirContext ctx = new InitialDirContext(env); // See which server was used System.out.println(ctx.getEnvironment().get(Context.PROVIDER_URL)); // do something useful with ctx
Note: Multiple URLs are supported only in the Java 2 SDK, v1.4.1 and later releases.
URL for Specifying Referrals
An LDAP referral contains a list of one or more URLs. To process an LDAP referral, the service provider uses the information in these URLs to create connections to the LDAP servers to which they refer. Multiple LDAP or LDAPS URLs in a single referral are treated as alternatives, each followed until one succeeds. The complete URL (including any query components) is used.You set up referrals by creating referral entries in the directory that contain the "REF" attribute. This attribute contains one or more referral URLs (usually LDAP or LDAPS URLs). See the Referrals
lesson for details on referrals.
URL as a Name in NamingEnumeration
When you perform a Context.list(), Context.listBindings()
, or DirContext.search()
, you get back a NamingEnumeration
. Each item in this enumeration is an instance or subclass of NameClassPair
. When the name of the item ( NameClassPair.getName()
) is not relative to the target context, the name is returned as a URL. You can use NameClassPair.isRelative()
to check whether the name is relative. One of main reason 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 and not the one at which the operation was initiated. See the URLs
lesson for more details and an example.
An LDAP URL is returned if the context is communicating with the LDAP server by using a plain connection. An LDAPS URL is returned if the context is communicating by using an SSL connection. The latter can happen if the Context.SECURITY_PROTOCOL
property was used to specify the use of SSL, or if an LDAPS URL was used in any of the following scenarios to get the context instance: to configure the service provider, as a referral, as a name argument to the initial context, or as an argument to getObjectInstance(). See the SSL and Custom Sockets
section for more information on SSL.
URL as an Argument to getObjectInstance()
When an LDAP namespace is federated under another namespace (such as DNS), the information that is stored in the superior namespace might be an LDAP or LDAPS URL. In such a scenario, a lookup()/list()/search() method invocation in the superior namespace will return a Referencethat contains the LDAP or LDAPS URL for the LDAP namespace. The service provider for the superior namespace will then pass the Reference to NamingManager.getObjectInstance()
or DirectoryManager.getObjectInstance()
to create an instance of an LDAP context. See the Beyond the Basics
trail for details on federation.
Miscellaneous: End of Lesson
![]()
![]()
What's next? Now you can:
- Continue on to the next lesson in this trail for examples of how to perform various types of searches.
- Go to the Referrals
lesson for tips on handling referrals.
- Go to the Schema
lesson for tips on accessing the schema.
- Go to the Controls and Extensions
to learn about LDAP controls and extensions.
- Go to the Connections
lesson for information on how connections are managed.
- Go to the Frequently Asked Questions
lesson to read about questions that LDAP users have when using the JNDI.
![]() ![]() ![]() ![]() |
Miscellaneous |