JNDI 1.2: Modifications to JNDI 1.1 Packages

The following changes were made to the JNDI 1.1 packages:

javax.naming:

Add NamingEnumeration.close() for cancelling or terminating enumerations.
Add ReferralException.getReferralContext(Hashtable env) and ReferralException.retryReferral() to allow creation and retry of referral context with different environment properties.
Clarify how context methods that accept Name argument should deal with CompositeName and CompoundName arguments.
Add Context.getNameInNamespace() to retrieve the full name of a context within its own namespace.
Add protected InitialContext constructor to allow lazy initialization.
Clarify definition of the class factory location of a Reference object.
Change output of NamingException.printStackTrace() so that it prints the stack trace of the root exception if it is non-null. This is consistent with the behavior of similar exceptions in JDK1.2.

javax.naming.directory:

Allow multivalued attributes to be ordered by adding the method Attribute.isOrdered(). If an attribute's values are ordered, then it can have multiple same values. The following methods are also added to support ordered values: get(int), remove(int), add(int, Object), set(int, Object).
Redefine semantics of DirContext.getSchemaClassDefinition() to be more useful.
Add BasicAttributes.equals() and BasicAttributes.hashCode().
Add protected InitialDirContext constructor to allow lazy initialization.

javax.naming.spi:

NamingManager.getObjectInstance() no longer treats URL strings specially. Instead, the URL should be wrapped inside a Reference.
Change ResolveResult to implement Serializable.
Add string constant NamingManager.CPE, which names a property now set when NamingManager.getContinuationContext() is called.
Add subinterfaces for ObjectFactory and StateFactory to better support service providers that implement the DirContext interface. Add methods in DirectoryManager to use these new interfaces.

Cancelling Enumerations

Problem: In JNDI 1.1, the search results are returned in a NamingEnumeration. Client applications need a way of cancelling large search requests. Leaving outstanding requests that the client is no longer interested in consumes resources both on the client and on the server.

Solution: Add a new method NamingEnumeration.close() that terminates the enumeration. When this method is invoked, the service provider is free to release resources associated with the enumeration and can notify the server to cancel the request as well, if that is appropriate. After this method has been invoked on an enumeration, the enumeration becomes invalid and subsequent invocation of any of its method will yield undefined results.

Referrals

Problem: In JNDI 1.1, there is no way to supply different environment properties (such as credentials) to referral contexts that need them. Also, if getReferralContext() fails, there is no way to retry using the referral.

Solution: Add a new method ReferralException.getReferralContext(Hashtable env). This is like the ReferralException.getReferralContext() method that takes no arguments. The only difference is that the existing method uses the environment properties associated with the context (that threw the exception), while the new method uses the supplied environment properties.

Add a new method ReferralException.retryReferral() to allow a referral to be retried.

Clarify Use of Names

Problem: In JNDI 1.1, the methods in Context and DirContext have overloaded forms that accept either a String name or a structured name (Name). There is documentation to the effect that both forms treat the name argument as composite names. Some clients might find it useful to allow compound names to be passed. For example, if it already has a parsed compound name, it should be able to use it directly.

Solution: Claify the documentation to say that if the structured name argument (Name) is an instance of CompositeName, then it will be treated as a composite name. Otherwise, it will be treated as a compound name that is implemented by the CompoundName class or some other compound name implementation.

Get Name in Namespace

Problem: All names in JNDI are relative, and there is no notion of a full (or fully-qualified) name. In the presence of federation, a service provider may not be able to determine the name of a context relative to the initial context. Indeed, there may be more than one initial context. Each individual service, however, most typically will have a notion of a full name within its own namespace. Several JNDI users have expressed the desire for a method that returns this name.

Solution: Add a new method Context.getNameInNamespace(). This method returns a string representation of the name of an object within its own namespace. This name is not a JNDI composite name, and should therefore not be passed directly to JNDI context methods.

Ordered Multivalued Attributes

Problem: In JNDI 1.1, the Attribute interface supports multivalued attributes. The values are unordered and cannot have duplicates. Some directories (such as Next's NetInfo) support multivalued attributes that are ordered, and in which there can be multiple occurrences of the same value within one attribute.

Solution: Add a method boolean Attribute.isOrdered() that allows the client application to determine whether the attribute he is dealing with is ordered. If the attribute is ordered, then the values returned from the getAll() method returns the values in order. The following methods are also added to support ordered values: get(int), remove(int), add(int, Object), set(int, Object). Similar changes are made to the BasicAttribute class to support this new feature.

Schema Class Definition

Problem: The JNDI 1.1 javadoc for DirContext.getSchemaClassDefinition() states that it returns the directory object's class definition in the schema. For example, it might return the schema object for the "Person" object class for a directory object that has "Person" as one of its object classes. However, this is not very useful because a directory object typically belongs to more than one object classes.

Solution: Modify the description so that the method returns a context containing all of the directory object's object class definitions. That way, you can get the object class you're interested in, or you can enumerate the context to see all of the object classes.

`BasicAttributes`

Problem: When using BasicAttributes objects, such as a key in a hash table, hashCode() and equals() have not been overridden so two such objects are only equal if they are the same object.

Solution: Add equals() and hashCode() methods such that two BasicAttributes objects are equal (and return the same hashCode) if they contain the same BasicAttribute objects.

URL Handling in `NamingManager`

Problem: In JNDI 1.1, NamingManager.getObjectInstance() and DirectoryManager.getObjectInstance() treat URLs specially. If the object argument is a URL string (or array of URL strings), these methods attempt to find a context factory using the URL's scheme id. This interferes with service providers that want to use the object factory mechanism but do not want URL strings treated specially.

Solution: The NamingManager.getObjectInstance() and DirectoryManager.getObjectInstance() methods no longer treat URL strings specially. Equivalent functionality is instead provided in the following way. When these methods are passed a Reference with no factory class name, and with StringRefAddr addresses with "URL" as the address type, the contents of each address is treated as a URL. A URL context factory based on the URL's scheme id is located, if possible, and used to resolve the URL.

`ResolveResult`

Problem: ResolveResult is returned by Resolver methods to indicate the result of resolution and the portion of the name that has not been resolved. Some service providers might want to serialize this result, perhaps for transmission to other Java virtual machines.

Solution: Have ResolveResult implement the Serializable interface. Note that a ResolveResult is only serializable if the resolved object is serializable.

Initial Context Constructors

Problem: When an InitialContext or InitialDirContext is constructed and the Context.PROVIDER_URL property is set, the connection to the service is made immediately. This is useful to clients since any exceptions encountered during the connection are reported as soon as possible. A subclass of one of these classes however, while still making the connection before its own constructor returns, may wish to delay it until after the construction of the superclass.

Solution: Add new constructors InitialContext(boolean lazy) and InitialDirContext(boolean lazy). When lazy is true, the connection is deferred.

Class Factory Location

Problem: The definition of the class factory location of a Reference object was not well specified.

Solution: Define the class factory location as a space-separated list of URLs representing the codebase used to load the factory. When the factory class (or any class upon which it depends) needs to be loaded, it is loaded from the codebase formed by the URLs.

`NamingManager.CPE`

Problem: Some developers of service providers that participate in a federation of naming systems have requested that there be a way for one context implementation to determine which context implementations came earlier in the federation.

Solution: The method NamingManager.getContinuationContext(CannotProceedException cpe) updates the environment associated with cpe by setting the value of the property NamingManager.CPE ("java.naming.spi.CannotProceedException") to cpe. This property is inherited by the continuation context, and may be used by that context's service provider to inspect the fields of the exception.

`DirObjectFactory` and `DirStateFactory`

Problem: When a service provider that implements the DirContext interface reads an object from the directory, it typically has also read some attributes that might be useful to object factories. For instance, the factory might use the attributes to determine whether to process the object or to process the object more efficiently without getting more attributes from the directory.

When a caller invokes DirContext.bind() and supplies attributes with the object to be bound, the service provider has no way of passing those attributes to the state factory, and the factory has no way of returning both an object and attributes to be bound.

Solution: The new method, DirectoryManager.getObjectInstance(), allows a service provider to pass attributes it has already read to object factories that implement the interface DirObjectFactory.

The new method, DirectoryManager.getStateToBind(), allows a service provider to pass attributes supplied by the caller to state factories that implement the new interface DirStateFactory. The provider can also obtain from the state factories the object and the attributes to be bound.

Please send comments to: jndi@java.sun.com

Java Software