The JNDI SPI provides the means by which developers can write different naming and directory service providers and make them available so that the corresponding services are accessible from applications that use the JNDI API. A service provider is a set of modules that together satisfy JNDI API requests. In addition, because JNDI allows the use of names that span multiple namespaces, one service provider implementation may need to interact with another in order to complete an operation. The SPI provides methods that allow different provider implementations to cooperate to complete client JNDI operations.
This document describes the components of the SPI and explains how developers can build service providers for JNDI. It is assumed that the reader is familiar with the contents of the JNDI API document.
All service provider developers should read the "Security Considerations" section of the JNDI API document. It contains important issues that all developers using JNDI, especially those writing service providers, should consider.
There are several types of
implementations that sit beneath the JNDI API. A service provider
contains at a minimum a context implementation. A context
implementation implements the Context interface or any
of its subinterfaces, such as DirContext,
EventContext, or LdapContext. The
complexity of the implementation depends primarily on the
complexity of the underlying service, and secondarily on the number
of JNDI features that the implementation supports. Chapter 2 describes the details of
building a context implementation.
A context implementation can be accessed in different ways. The most common way is to access it from the initial context. Chapter 3 describes two ways that a context implementation can be accessed from the initial context: via an initial context factory and a URL context factory.
The JNDI architecture defines components/implementations that can be used to augment the behavior of context implementations. This allows users and applications to customize the implementation. These components are supported through factories. JNDI defines three types of factories and provides SPI methods that make use of them. These factories are described in Chapter 4.
The JNDI SPI is contained in the
javax.naming.spi package. The following sections
provide an overview of the SPI. For more details on the SPI, see
the corresponding javadoc.
The information in this graphic is available in the API documentation.
The NamingManager class
contains static methods that perform provider-related operations.
For example, it contains methods to create instances of objects
using Reference, to obtain an instance of the initial
context using the java.naming.factory.initial
property, and to install ObjectFactoryBuilder and
InitialContextFactoryBuilder. The
DirectoryManager class provides similar static methods
for DirContext related operations.
InitialContextFactory is the
interface for creating an initial context instance. See Section 3.1 for more details.
InitialContextFactoryBuilder
is the interface for creating InitialContextFactory
instances. See Section 3.3 for
more details.
ObjectFactory is the
interface for supporting creation of objects using information
stored in the namespace. DirObjectFactory is a
subinterface of ObjectFactory for use by context
implementations that implement the DirContext
interface. See Section 4.1
for more details.
ObjectFactoryBuilder is the
interface for creating object factories. See Section 4.1.4 for more details.
StateFactory is the
interface for supporting converting objects into storable formats
supported by the naming/directory service.
DirStateFactory is a subinterface of
StateFactory for use by context implementations that
implement the DirContext interface.
DirStateFactory.Result is a class for holding a pair
of java.lang.Object and Attributes that
is returned by DirStateFactory.getStateToBind(). See
Section 4.2 for more
details.
The Resolver interface
defines a method for providers to implement that allows them to
participate in a federation for supporting extended interfaces to
Context. See "Resolving Through to Subinterfaces of
Context" on page 10 for more details.
ResolveResult is the return
value of calling Resolver.resolveToClass(). It
contains the object to which resolution succeeded, and the
remaining name yet to be resolved.
One of the basic tasks in building a
service provider is to define a class that implements the
Context interface or any of its subinterfaces. This
class is called a context implementation. The following
guidelines should be used for developing a context
implementation.
In general, any object passed as a
parameter to methods in the Context interface (or
subinterfaces) and
NamingManager/DirectoryManager utility
methods is owned by the caller. In many cases, the parameter
eventually reaches a context implementation. Because the caller
owns the object, the context implementation is prohibited from
modifying the object. Furthermore, the context implementation is
allowed to maintain a pointer to the object only for the duration
of the operation and not beyond. If a context implementation needs
to save the information contained in a parameter beyond the
duration of the operation, it should maintain its own copy.
For purposes of parameter ownership, an
operation on a context instance is not considered to have completed
while any referrals generated by that operation are still being
followed, or if the operation returns a
NamingEnumeration, while the enumeration is still in
use.
A context instance need not be reentrant. Two threads that need to access the same context instance concurrently should synchronize amongst themselves and provide the necessary locking.
However, different context instances must be safe for concurrent multithreaded access. That is, two threads each operating concurrently on their respective context instance should not need to synchronize their access. For example, even though two contexts might share the same resources (such as the same connection), it must be possible (and safe) for two separate threads to operate on each of those contexts without the threads having to do any explicit synchronization.
For purposes of concurrency control, an
operation on a context instance is not considered to have completed
while any referrals generated by that operation are still being
followed, or if the operation returns a
NamingEnumeration, while the enumeration is still in
use.
The context implementation defines
implementations for each of the methods in the Context
interface or subinterfaces that the implementation supports.
If a method is not supported, it should
throw OperationNotSupportedException.
For methods in the Context
interface or subinterfaces that accept a name argument (either as a
String or a Name), an empty name denotes
the current context. For example, if an empty name is supplied to
lookup(), that means to return a new instance of the
current context. If an empty name is supplied to
list(), that means to enumerate the names in the
current context. If an empty name is supplied to
getAttributes(), that means to retrieve the attributes
associated with this context.
Appendix A contains an example context implementation that implements a flat, in-memory namespace.
JNDI encourages providers to supply
implementations of the Context and its subinterfaces
that are natural and intuitive for the Java application programmer.
For example, when looking up a printer name in the namespace, it is
natural for the programmer to expect to get back a printer object
on which to operate.
Context ctx = new InitialContext(); Printer prt = (Printer)ctx.lookup(somePrinterName); prt.print(someStreamOfData);
Similarly, when storing an application's object into the underlying service, it is most portable and convenient if the application does not have to know about the underlying data representation.
However, what is bound in the underlying directory or naming services typically are not objects in the Java programming language but merely reference information which can be used to locate or access the actual object. This case is quite common, especially for Java applications accessing and sharing services in an existing installed base. The reference in effect acts as a "pointer" to the real object. In the printer example, what is actually bound might be information on how to access the printer (e.g., its protocol type, its server address). To enable this easy-to-use model for the application developer, the context implementation must do the transformation of the data to/from the underlying service into the appropriate objects in the Java programming language.
There are different ways to achieve this
goal. One context implementation might have access to all the
implementation classes of objects that a directory can return;
another context implementation might have a special class loader
for locating implementation classes for its objects. JNDI provides
the Reference class as a standard way of representing
references. Applications and context implementations are encouraged
to use this class, rather than invent separate mechanisms on their
own. However, this does not preclude context implementations from
using their own mechanisms for achieving the same goal.
JNDI provides utilities for context implementations to use when reading/storing objects in the Java programming language in a format-independent way to the underlying service. This section describes these utilities. These utilities interact with components called object and state factories that do the actual transformations. These factories are described in Chapter 4.
JNDI provides the following methods that context implementations should use to transform data read from the underlying service into objects in the Java programming language:
Object NamingManager.getObjectInstance(Object refInfo,
Name name,
Context nameCtx,
Hashtable env)
throws Exception;
Object DirectoryManager.getObjectInstance(Object refInfo,
Name name,
Context nameCtx,
Hashtable env,
Attributes attrs)
throws Exception;
refInfo is the data (representing the object) read
from the underlying service. name is the name of the
object while nameCtx is the context in which to
resolve name. The
name/nameCtx pair can be used to obtain
more information about the object than is available from
refInfo. env is the environment of the
context from which getObjectInstance() is being
invoked. attrs is the collection of attributes read
from the directory about the object, usually in the same request
that was used to get refInfo. It might not be the
complete collection of attributes if such was not requested.
The method in the
NamingManager class should be used by context
implementations that implement the Context interface,
while the method in the DirectoryManager class should
be used by context implementations that implement the
DirContext interface.
When constructing objects to be returned
for the following methods, the context implementation should call
getObjectInstance(), or its own mechanism for
generating objects from the bound information, if it wants this
feature to be enabled in their contexts. (String overloads not
shown.)
javax.naming.Context.lookup(Name name)
javax.naming.Context.lookupLink(Name name)
javax.naming.Binding.getObject()
javax.naming.directory.SearchResult.getObject()
For Binding and
SearchResult, the context implementation should either
pass an object that is the result of calling
getObjectInstance() or its equivalent to the
constructor, or override the default implementation of
Binding and SearchResult so that their
getObject() implementations call
getObjectInstance() or its equivalent before
returning.
Here is an example. Suppose printers are
represented in the namespace using References. To turn
a printer Reference into a live Printer
object, the context implementation would use the
NamingManager.getObjectInstance() method. In this way,
the underlying service need not know anything specific about
printers.
Object lookup(Name name) {
...
Reference ref = <some printer reference looked up from naming service>;
return NamingManager.getObjectInstance(ref, name, this, env);
}
In another example, suppose printers are
represented in the directory as a collection of attributes. To turn
a printer's directory entry into a live Printer
object, the context implementation would use
DirectoryManager.getObjectInstance().
Object lookup(Name name) {
...
Attributes attrs = <read attributes from directory>;
Reference ref = <construct reference from attributes>;
return DirectoryManager.getObjectInstance(ref, name, this,
env, attrs);
}
JNDI provides the following methods that context implementations should use to transform an object before storing it in the underlying service:
Object NamingManager.getStateToBind(
Object obj,
Name name,
Context nameCtx,
Hashtable env)
throws NamingException;
DirStateFactory.Result DirectoryManager.getStateToBind(
Object obj,
Name name,
Context nameCtx,
Hashtable env,
Attributes attrs)
throws NamingException;
obj is the object to be
stored in the underlying service. name is the name of
the object while nameCtx is the context in which to
resolve name. The
name/nameCtx pair can be used to obtain
more information about the object than is available from
obj. env is the environment of the
context from which getStateToBind() is being invoked.
attrs is the collection of attributes that is to be
bound with the object. DirStateFactory.Result is a
class that contains an object and a collection of attributes.
The method in the
NamingManager class should be used by context
implementations that implement the Context interface,
while the method in the DirectoryManager class should
be used by context implementations that implement the
DirContext interface.
Before storing an object supplied by the
application, the context implementation should call
getStateToBind(), or its own mechanism for generating
information to be bound, if it wants this feature to be enabled in
their contexts. (String overloads not shown.)
javax.naming.Context.bind(Name name, Object o) javax.naming.Context.rebind(Name name, Object o) javax.naming.DirContext.bind(Name name, Object o, Attributes attrs) javax.naming.DirContext.rebind(Name name, Object o, Attributes attrs)
Here's an example of how a
Context implementation supports
Context.bind:
// First do transformation
obj = NamingManager.getStateToBind(obj, name, ctx, env);
// Check for Referenceable
if (obj instanceof Referenceable) {
obj = ((Referenceable)obj).getReference();
}
if (obj instanceof Reference) {
// store as ref
} else if (obj instanceof Serializable) {
// serialize
} else {
...
}
Here's an example of how a
DirContext implementation supports
DirContext.bind:
// First do transformation
DirStateFactory.Result res = DirectoryManager.getStateToBind(
obj, name, ctx, env, inAttrs);
obj = res.getObject();
Attributes outAttrs = res.getAttributes();
// Check for Referenceable
if (obj instanceof Referenceable) {
obj = ((Referenceable)obj).getReference();
}
if (obj instanceof Reference) {
// store as ref and add outAttrs
} else if (obj instanceof Serializable) {
// serialize and add outAttrs
} else if (obj instanceof DirContext) {
// grab attributes and merge with outAttrs
} else {
...
}
As shown in these examples, a context
implementation might be able to store different types of objects
(Reference, Serializable, and
DirContext). If the context implementation cannot
store Referenceable objects directly and
getStateToBind() returns such an object, the context
implementation should subsequently call
Referenceable.getReference() and store the resulting
Reference instead.
If a context implementation can store different types of objects, it should follow this order for the following common types:
This order is recommended because it is most likely to capture the intent of the caller of thebind()/rebind() method. For example, a
Reference is Serializable, so if you
performed the Serializable check first, no
Reference objects would ever be stored in the
reference format (that is, they would all be serialized).
When a context is given a string name argument, the name represents a composite name that may span multiple namespaces, or it may have only a single compound name component (which in turn may be made up of one or several atomic names) that belongs to a single namespace. The context implementation must determine which part of the name is to be resolved/processed in its context and pass the rest onto the next context. This may be done syntactically by examining the name, or dynamically by resolving the name.
When a context is given a
Name argument, if it 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.
A context participates in a federation by
performing the resolution phase of all of the context operations.
The lookup() method must always be supported. Support
for other methods is optional, but if the context is to participate
in a federation, then the resolution implicit in all operations
must be supported.
Figure 1: Example of Resolving through Intermediate Contexts to Perform a bind().
For example, suppose a context does not
support the bind() operation. When that context is
being used as an intermediate context for bind(), it
must perform the resolution part of that operation to enable the
operation to continue to the next context. It should only throw
OperationNotSupportedException if it is being asked to
create a binding in its own context. Figure 1 shows an example of
how the bind() operation is passed through
intermediate contexts to be performed in the target context.
To invoke a DirContext
method (such as getAttributes()), the application
first obtains an initial DirContext, and then perform
the operation on the DirContext.
DirContext ctx = new InitialDirContext(); Attributes attrs = ctx.getAttributes(someName);From the context implementation's perspective, in order to retrieve the attributes,
getAttributes() might need to traverse
multiple naming systems. Some of these naming systems only support
the Context interface, not the DirContext
interface. These naming systems are being used as intermediaries
for resolving towards the target context. The target context must
support the DirContext interface. Figure 2 shows an
example of this.
Figure 2: Example of Resolving Through Intermediate non-DirContexts
In order for intermediate naming systems
to participate in the federation for extensions of
Context, they must implement the Resolver
interface. The Resolver interface is used by the JNDI
framework to resolve through intermediate contexts that do not
support a particular subinterface of Context. It
consists of two overloaded forms of the method
resolveToClass(). This method is used to partially
resolve a name, stopping at the first context that is an instance
of the required subinterface. By providing support for this method
and the resolution phase of all methods in the Context
interface, a context implementation can act as an intermediate
context for extensions (subinterfaces) of Context.
public interface Resolver {
public ResolveResult resolveToClass(Name name, Class contextType)
throws NamingException;
public ResolveResult resolveToClass(String name,
Class contextType)
throws NamingException;
}
The resolution of a (multicomponent) composite name proceeds from one naming system to the next, with the resolution of the components that span each naming system typically handled by a corresponding context implementation. From a context implementation's point of view, it passes the components for which it is not responsible to the (context implementation of the) next naming system.
There are several ways in which the
context implementation for the next naming system may be located.
It may be done explicitly through the use of a
junction, where a name in one naming system is bound to a
context (or a Reference to a context) in the next
naming system. For example, with the composite name
"cn=fs,ou=eng/lib/xyz.zip", the LDAP name "cn=fs,ou=eng" might
resolve to a file system context in which the name "lib/xyz.zip"
could then be resolved.
Alternately, the next naming system may
be located implicitly. For example, a context
implementation may choose the next naming system based upon
service-specific knowledge of the object that it has resolved. For
example, with the composite name "ldap.wiz.com/cn=fs,ou=eng", the
DNS name ldap.wiz.com might name a DNS entry. To get
the next naming system beyond DNS, the DNS context implementation
might construct a context using SRV resource records found in that
entry, which in this case, happens to name an LDAP context. When
the next naming system is located in this fashion, JNDI composite
name separator is used to denote the boundary from one naming
system to the next, and is referred to as the implicit next
naming system pointer.
However the next naming system is located, the context implementation must hand the next naming system the remaining portion of the composite name to resolve.
In performing an operation on a name that
spans multiple namespaces, a context in an intermediate naming
system needs to pass the operation onto the next naming system. The
context does this by first constructing a
CannotProceedException containing information
pinpointing how far it has proceeded. In so doing it sets the
resolved object, resolved name, remaining name, and environment
parts of the exception.2 (In the
case of the Context.rename() method, it also sets the
"resolved newname" part.)
It then obtains a continuation
context from JNDI by passing the
CannotProceedException to static method
NamingManager.getContinuationContext()
public class NamingManager {
public static Context getContinuationContext(
CannotProceedException e) throws NamingException;
...
}
The information in the exception is used
by getContinuationContext() to create the context
instance in which to continue the operation.
To obtain a continuation context for the
DirContext operations, use
Directory-Manager.getContinuationDirContext().
public class DirectoryManager {
public static getContinuationDirContext(
CannotProceedException e) throws NamingException;
...
}
Upon receiving the continuation context, the operation should be continued using the remainder of the name that has not been resolved.
For example, when attempting to continue
a bind() operation, the code in the context
implementation might look as follows:
public void bind(Name name, Object obj) throws NamingException {
...
try {
internal_bind(name, obj);
...
} catch (CannotProceedException e) {
Context cctx = NamingManager.getContinuationContext(e);
cctx.bind(e.getRemainingName(), obj);
}
}
In this example, bind()
depends on an internal method, internal_bind(), to
carry out the actual work of the bind and to throw a
CannotProceedException when it discovers that it is
going beyond this naming system. The exception is then passed to
getContinuationContext() in order to continue the
operation. If the operation cannot be continued, the continuation
context will throw the CannotProceedException to the
caller of the original bind() operation.
In some federation configurations, the result of resolution in one naming system does not indicate which is the next naming system. The only conclusion that the context implementation can draw is that resolution has terminated in the current naming system and should proceed to the next naming system.
For example, suppose the composite name "lib/xyz.zip/part1/abc" consists of two parts: "lib/xyz.zip", which names a file in ZIP format, and "part1/abc", which names an entry within the ZIP file. Although the resolution of "lib/xyz.zip" results in a file object, the desired result is a context in which to resolve names of ZIP entries. Similarly, another composite name could name an entry within a file in "tar" format, and the desired result of the resolution of the file component of the composite name would be a context in which to resolve tar entries.
In effect, any type of context might be federated beneath the file system namespace depending on the format of the files. Such relationships should be symmetric: it should be possible for the ZIP file context and other similar contexts to federate beneath other, non-file system namespaces. Furthermore, developers writing the file system context implementation and those writing the context implementations for the ZIP file context, the tar file context, or a context for some yet-to-be defined format, should be able to work independently.
To support this type of federation, JNDI
defines a special form of Reference called an nns
reference ("nns" stands for "next naming system"). This
Reference has an address with type nns.
The address contents is the resolved object (in the above example,
the ZIP file). Continuing with the file system example, the file
system context implementation might create the nns reference as
follows:
RefAddr addr = new RefAddr("nns") {
public Object getContent() {
return theFile;
}
};
Reference ref = new Reference("java.io.File", addr);
Next, the context implementation
constructs a CannotProceedException (as with the
junction case) by using the nns reference as the resolved object,
and a resolved name consisting of the resolved file name and an
empty component. The empty component is being used as an implicit
next naming system pointer and indicates that the resolution has
succeeded to the point of resolving the next naming system. (Notice
how the values of the resolved object and resolved name are
matched.) The context impementation then passes the
CannotProceedException to
getContinuationContext().
As with any resolved object in a
CannotProceedException,
getContinuationContext() searches for a context
implementation that accepts this nns reference. The ZIP file
context implementation, for instance, might accept an nns reference
and other information provided, such as the name of the file
(relative to a given context). If the context implementation
determines that the file is a ZIP file, it would then construct a
context for resolving names within that file.
Central to the JNDI SPI's framework for
federation is the CannotProceedException. A
Cannot-ProceedException contains information such as
the resolved name/object and remaining name, inherited from the
NamingException superclass. In addition, a
CannotProceedException also contains fields for the
"alt" name and "alt" name context. While the resolved name from
NamingException is the full composite name (relative
to the starting context of the operation), alt name is the resolved
name relative to the alt name context. That is, alt name might not
necessarily be the same as the resolved name. Alt name and alt name
context are used as arguments to
NamingManager/DirectoryManager.getObjectInstance().
They allow the factories that are called by this method to obtain
more information about the resolved object (for example, it could
be used to get a special attribute about the object). These
factories are described in Chapter
4.
While the emphasis of the JNDI SPI framework is on "looking forward" and trying to find the next naming system, some context implementations, once located, need to "look back" the resolution chain to obtain contextual information. For example, a particular context implementation that is federated off of a host naming system might be designed such that the only means by which it can find out host information is to ask its (possibly not immediate) superior naming system. To do that, it needs contextual information-information about how the resolution proceeded to its current point.
Summarizing earlier discussions on
federation, when performing an operation on a name that spans
multiple namespaces, the context implementation first constructs a
CannotProceed-Exception containing information
pinpointing how far it has proceeded. It then obtains a
continuation context from JNDI by calling
getContinuationContext(). To support the retrieval of
contextual information, getContinuationContext()
automatically adds the environment property
java.naming.spi.CannotProceedException, with the value
of the Cannot-ProceedException argument, to the
continuation context's environment. This property is inherited by
the continuation context and may be used by that context's
implementation to inspect the fields of the exception.
LDAP-style directory services support the
notion of referrals for redirecting a client's request to
another server. A referral differs from the federation continuation
mechanism described earlier in that a referral may be presented to
the JNDI client, who then decides whether to follow it, whereas a
CannotProceedException should be returned to the
client only when no further progress is possible. Another
difference is that an individual context implementation offers the
capability of continuing the operation using the referral (and
itself determines the mechanism for doing so). In a federation, the
mechanism of continuation is beyond the scope of individual context
implementations: individual context implementations benefit from
the common federation mechanism provided by the JNDI SPI
framework.
A context implementation that supports
referrals defines a subclass of ReferralException and
provides implementations for its abstract methods.
getReferralContext() returns a context at which to
carry on the operation, and getReferralInfo() returns
information on where the referral leads to, in a format appropriate
to the context implementation.
The environment property
java.naming.referral specifies how the context
implementation should treat referrals. If the context
implementation is asked to throw an exception when a referral is
encountered, or if the context implementation encounters problems
following a referral, it throws a ReferralException to
the application. To continue the operation, the application
re-invokes the method on the referral context using the same
arguments it supplied to the original method. The following code
sample shows how ReferralException may be used by an
application:3
while (true) {
try {
bindings = ctx.listBindings(name);
while (bindings.hasMore()) {
b = (Binding) bindings.next();
...
}
break;
} catch (ReferralException e) {
ctx = e.getReferralContext();
}
}
This convention of re-invoking the method using the original arguments is a simple one for applications to follow. This places the burden on the implementation of the ReferralException to supply enough information to the implementation of the referral context for the operation to be continued. Note that this will likely render some of the arguments passed to the re-invoked operation superfluous. The referral context implementation is free to ignore any redundant or unneeded information.
It is possible for an operation to return results in addition to a referral. For example, when searching a context, the server might return several results in addition to a few referrals as to where to obtain further results. These results and referrals might be interleaved at the protocol level. If referrals require user interaction (i.e., not followed automatically), the context implementation should return the results through the search enumeration first. When the results have been returned, the referral exception can then be thrown. This allows a simple programming model to be used when presenting the user with a clear relationship between a referral and its set of results.
JNDI defines the Attribute
interface for representing an attribute in a directory. An
attribute consists of an attribute identifier (a string) and a set
of attribute values, which can be any object in the Java
programming language. There are also methods defined in
Attribute for obtaining the attribute's definition and
syntax definition from the directory's schema.
public class Attribute {
public DirContext getAttributeDefinition() throws NamingException;
public DirContext getAttributeSyntaxDefinition()
throws NamingException;
...
}
The utility class,
BasicAttribute, does not provide useful
implementations for these methods. A directory context
implementation that has support for such schema information should
provide implementations of Attribute that implement
these two methods based on its schema mechanisms, perhaps by
subclassing BasicAttribute and overriding these two
methods. The context implementation should then return instances of
these subclasses when asked to return instances of
Attribute. The context implementation, when it
receives an Attribute instance that do not have
meaningful implementations of these two methods, should use
reasonable defaults to determine the attribute's definition and
syntax, using information such as the attribute values' class names
or conventions used for the attribute identifier.
The DirContext interface
contains schema-related methods:
public class DirContext {
...
public DirContext getSchema(Name name) throws NamingException;
public DirContext getSchema(String name) throws NamingException;
public DirContext getSchemaClassDefinition(Name name)
throws NamingException;
public DirContext getSchemaClassDefinition(String name)
throws NamingException;
}
getSchema() returns the
schema tree for the named object, while
getSchemaClassDefinition() returns a context
containing schema class definitions for the named object. Some
systems have just one global schema and, regardless of the value of
the name argument, will return the same schema tree.
Others support finer grained schema definitions, and may return
different schema trees depending on which context is being
examined.
A context implementation supports event
notification by providing implementation for the methods in the
EventContext/EventDirContext interfaces.
The event model advocated by these interfaces can be readily
supported using a multithreaded model. When an application uses
addNamingListener() to register a listener with a
context, the context records the requests and takes action to
collect information required to generate the events. When the
context eventually receives information to generate the events, it
fires the events to the listener. The thread that does the
registration is typically different from the thread that runs the
listener. The context implementation typically uses a thread that
it has created and manages to run the listener method. When one
event is dispatched to multiple listeners, the context
implementation may choose to (and is generally encouraged) to
execute the listener methods concurrently in separate threads.
The addNamingListener()
methods accept an instance of NamingListener. The
instance might implement one or more subinterfaces of
NamingListener. If the listener implements more than
one subinterface, the context implementation should try to conserve
resources required to satisfy the registration. For example, an
implementation might be able to submit a single request to the
server that captures all of the requests of the subinterfaces.
Where possible, the context
implementation should fire a NamingExceptionEvent to a
listener if the context will be unable to fire further events and
then automatically deregister the listener. For example, if the
connection to the server is broken subsequent to the registration
of the listener and no information will be available to fire
events, the context should fire a NamingExceptionEvent
to the listener.
Each instance of Context (or
its subinterfaces) can have associated with it an
environment which contains preferences expressed by the
application of how it would like to access the services offered by
the context. Examples of information found in an environment are
security-related information that specify the user's credentials
and desired level of security (none,
simple, strong), and configuration
information, such as the server to use. See Chapter 6 and Appendix
A of the JNDI API document for more details about
environment properties.
Environment properties are defined generically in order to ensure maximum portability. Individual service providers should map these generic properties to characteristics appropriate for their service. Properties that are not relevant to a provider should be recorded and silently ignored. The environment may also be used for storing service provider-specific properties or preferences, in which case their applicability across different providers is limited.
See Section 6.1 in the JNDI
API document for a description of how environment
properties are named. Service provider-specific properties should
have a prefix that reflects their uniqueness to the provider. A
common practice is to use the package name of the service provider
as the prefix. For example, since Sun's LDAP provider is primarily
contained in the package com.sun.jndi.ldap, properties
specific to Sun's LDAP provider have the prefix
"com.sun.jndi.ldap.".
When creating an initial context (either
using the constructors from InitialContext or its
subclasses), the application can supply an environment as a
parameter. The parameter is represented as a Hashtable
or any of its subclasses (e.g., Properties). The JNDI
class library augments the data from this parameter with data from
other sources (see Chapter 6 in the JNDI API
document) and passes this to the context implementation.
Like all other parameters, the
environment parameter received by a context implementation is owned
by the caller. The context implementation should make a copy of the
environment parameter it gets or otherwise take steps to ensure
that changes by the caller to the parameter would not affect what
the context implementation sees and vice versa. Note also that if
the environment parameter is a Properties instance,
enumeration and Hashtable.get() on the parameter only
examine the top-level properties (not any nested defaults). This is
the expected behavior. The context implementation is not expected
to retrieve or enumerate values in the Properties
instance's nested defaults.
The JNDI library is responsible for merging properties from different sources, such as the environment parameter to the initial context, resource files, and, where appropriate, system properties and applet parameters (see the JNDI API document, Chapter 6). The context implementation typically just reads the property it needs from the environment which it was supplied. There is seldom a need for a context implementation to consult other sources.
The environment is inherited from parent to child as the context methods proceed from one context to the next. The entire environment of a context instance is inherited by the child context instances, regardless of whether certain properties within the environment are ignored by a particular context.
A context implementation must pass on the
environment from one context instance to the next in order to
implement this "inheritance" trait of environments. Within one
context implementation it can do so by passing the environment as
an argument to the Context constructor, or to the
NamingManager/DirectoryManager.getObjectInstance()
method for creating Context instances.
Across context implementations in a
federation, this is supported by passing the environment as part of
the CannotProceedException parameter of
NamingManager.getContinuationContext()/DirectoryManager.getContinuationDirContext(),
which in turn will use this environment when creating an instance
of the context in which to continue the operation.
Inheritance can be implemented in any way as long as it preserves the semantics that each context has its own view of its environment. For example, a copy-on-write implementation could be used to defer copying of the environment until it is absolutely necessary.
The environment of a context can be
updated via the use of the addToEnvironment() and
removeFromEnvironment() methods in the Context
interface.
public interface Context {
...
public Object addToEnvironment(String propName, Object propVal)
throws NamingException;
public Object removeFromEnvironment(String propName)
throws NamingException;
}
These methods update the environment of
this instance of Context. An environment property that
is not relevant to the context implementation is silently ignored
but maintained as part of the environment. The updated environment
affects this instance of Context, and will be
inherited by any new child Context instances, but does
not affect any Context instances already in existence.
A lookup of the empty name on a Context will return a
new Context instance with an environment inherited as
with any other child.
See Section 6.6 in the JNDI API document for details.
Each service provider has an optional resource file that contains properties specific to that provider. The name of this resource is:
[prefix/]jndiprovider.propertieswhere prefix is the package name of the provider's context implementation(s), with each period (".") converted to a slash ("/"). For example, suppose a service provider defines a context implementation with class name
com.sun.jndi.ldap.LdapCtx. The provider resource for
this provider is named
com/sun/jndi/ldap/jndiprovider.properties.
The JNDI class library will consult this file when it needs to determine the value of a property, as described in Section 6.5.2 in the JNDI API document.
When the service provider needs to determine the value of a property, it will generally take that value directly from the environment. The service provider may define provider-specific properties to be placed in its own provider resource file. In that case it needs to read them from its property resource file and merge them in a way consistent with the algorithm described in Section 6.5.2 in the JNDI API document.
For a context implementation that uses a client/server protocol, there is not necessarily a one-to-one mapping between a context and a connection between the client and the server. JNDI is a high-level API that does not deal directly with connections. It is the job of the context implementation to do any necessary connection management. Hence, a single connection may be shared by multiple context instances, and a context implementation is free to use its own algorithms to conserve connection and network usage. Thus, when a method is invoked on the context instance, the context implementation might need to do some connection management in addition to performing the requested operation.
The Context.close() and
NamingEnumeration.close() methods can be used by
applications to provide hints to the context implementation as to
when to free connection-related resources. A context implementation
may choose to (and is generally encouraged to) take other measures
to garbage-collect and conserve its connection-related
resources.
Some environment properties affect a context's connection. For example, if the application changes the security-related properties, the context implementation might need to modify or create a new connection using those updated properties. If the connection was being shared by other contexts prior to the change, the connection change should not affect contexts whose properties have not been updated.
Since all naming methods are performed relative to a context, an application needs a starting context in order to invoke them. This starting context is referred to as the initial context. The bindings in the initial context are determined by policies set forth by the initial context implementation, perhaps using standard policies for naming global and enterprise-wide namespaces. For example, the initial context might contain a binding to the Internet DNS namespace, a binding to the enterprise-wide namespace, and a binding to a personal directory belonging to the user who is running the application.
An application obtains an initial context by making the following call:
Context ctx = new InitialContext();An alternate constructor allows an environment to be passed as an argument. This allows the application to pass in preferences or security information to be used in the construction of the initial context.
Hashtable env = new Hashtable();4 env.put(Context.SECURITY_PRINCIPAL, "jsmith"); env.put(Context.SECURITY_CREDENTIALS, "xxxxxxx"); Context ctx = new InitialContext(env);
Subsequent to getting an initial context,
the application can invoke Context methods.
Object obj = ctx.lookup("this/is/a/test");
The InitialContext class (and
subclasses) selects an implementation using a default algorithm
that can be overridden by installing an initial context factory
builder (described below).
The InitialDirContext is an
extension of InitialContext. It is used for performing
directory operations using the initial context. The
InitialLdapContext class is an extension of
InitialDirContext. It is used for performing special
LDAP v3 operations using the initial context. The algorithms and
policies described in this section also apply to
InitialDirContext and InitialLdapContext.
Places where DirContext/LdapContext is required
instead of Context have been noted.
An initial context factory is a
class that creates an instance of a context that has been
implemented following the guidelines outlined in Chapter 2. The factory is used by the
InitialContext class (or subclass) constructor.
Given an environment, the factory returns
an instance of Context (or its subinterfaces).
public interface InitialContextFactory {
public Context getInitialContext(Hashtable env)
throws NamingException;
}
Appendix A contains an example of an
InitialContextFactory.
Once the context instance has been
created, when a method is invoked on InitialContext by
using a non-URL name (see below), the method is forwarded and
invoked on that context instance.
JNDI selects the initial context
implementation to use by using the property
java.naming.factory.initial. This property contains
the fully-qualified class name of an initial context factory. The
class must implement the InitialContextFactory
interface and have a public constructor that does not take any
arguments. JNDI will load the initial context factory class and
then invoke getInitialContext() on it to obtain a
Context instance to be used as the initial
context.
An application that wants to use a
particular initial context must supply the
java.naming.factory.initial property in the
environment passed to the InitialContext (or subclass)
constructors, or via resource files, system properties, or applet
parameters.
When the property
java.naming.factory.initial is set to a
non-null value, the InitialContext (and
subclass) constructors will try to load and instantiate an initial
context factory, which will then create a context instance. If the
factory or context cannot be created, for example as a result of an
authentication problem, the initial context factory can throw an
exception to indicate this problem. Note however that it is up to
the context implementation when it verifies and indicates
to users of the initial context any environment property- or
connection- related problems. It can do so lazily-delaying until an
operation is performed on the context, or eagerly, at the time the
context is created.
If the property
java.naming.factory.initial is not set, no attempt
will be made to create an underlying context for the initial
context. The initial context is still useful, for instance, for
processing URL names, as described next.
If a URL5 string is passed to the initial
context, it will be resolved using the corresponding URL
context implementation. This feature is supported by the
InitialContext class (and subclasses) and is
independent of the setting of the
java.naming.factory.initial environment property.
This feature allows applications to use the initial context to reach any namespace for which a URL context implementation has been made available. For example, the following code lists an LDAP namespace from the initial context:
new
InitialContext().list("ldap://lserver/ou=eng,o=wiz,c=us");
A URL string has the following format:
For example, an LDAP URL string has the scheme id "ldap"; a file URL has the scheme id "file".
A URL context implementation is a class
that implements the Context interface (and possibly
some subinterfaces) and accepts name arguments that are URL strings
of the scheme that it supports. For example, an LDAP URL context
accepts "ldap" URL strings.
When a URL string name is passed to a URL
context, the context methods that accept String treat
the name as a URL with the syntax defined by the URL scheme. When a
Name object in which the first component is a URL
string name is passed to a URL context, the first component is
treated as a URL string, and the rest is used for federation (that
is, resolution of the first component will indicate which naming
system to use to resolve the rest). The Name instance
should be a CompositeName; otherwise, an
InvalidNameException should be thrown.
Name arguments that are not URL strings,
and URL strings with an inappropriate scheme id should be rejected
with an InvalidNameException.
A URL context factory is a class (actually a special type object factory (see Section 4.1)) that creates an instance of a URL context for URLs of one or more schemes.
When the InitialContext
class receives a URL string as a name argument, it will look for a
URL context factory by using the following algorithm. The
environment property java.naming.factory.url.pkgs
contains a colon-separated list of package prefixes. The factory's
class name is constructed by using the following rule:
package_prefix + "." +
scheme_id + "." +
scheme_idURLContextFactory
for each package prefix listed in the
property. The default package prefix com.sun.jndi.url
is appended to the end of the list.
For example, if the URL is
"ldap://somehost:389" and
java.naming.factory.url.pkgs contains
"com.widget:com.wiz.jndi", the
InitialContext class will attempt to locate the
corresponding factory class by loading the following classes until
one is successfully instantiated:
com.widget.ldap.ldapURLContextFactory com.wiz.jndi.ldap.ldapURLContextFactory com.sun.jndi.url.ldap.ldapURLContextFactoryThe factory class implements the
ObjectFactory
interface (see "URL Context
Factory" on page 31) and has a public constructor that
takes no arguments. The InitialContext class passes
the scheme id as the resolved object to the factory's
getObjectInstance() method, which in turn creates a
URL context for the URL scheme. The URL context will then be used
to carry out the originally intended Context or
DirContext operation on the URL supplied to
InitialContext.
There is no requirement that a service
provider supply a URL context factory and URL context
implementation. It only does so if it wants to allow URL string
names with its URL scheme to be accepted by the
InitialContext class. A service provider, for
instance, might just provide an initial context factory and a
context implementation that is accessed through that factory.
The policy of creating an initial context
factory using the java.naming.factory.initial
environment property and URL support is built into the
InitialContext class. There are two ways an
application can override some or all of this policy.
If an application does not want URL
strings to be treated specially, it can use the method
NamingManager.getInitialContext(), which creates a
context instance using the factory named in the
java.naming.factory.initial environment property.
This method is also useful if the
application needs to access interfaces implemented by the context
created by the initial context factory, but which are not one of
Context, DirContext, or
LdapContext. Here is a code fragment that gets a
context using NamingManager.getInitialContext() and
then casts it to a subclass:
FooContext ctx = (FooContext) NamingManager.getInitialContext(env); ... Object obj = ctx.lookup(name); ctx.fooMethod1(...);Note that installing an initial context factory builder (discussed next) affects the result of
NamingManager.getInitialContext().
An initial context factory builder is a class that creates instances of initial context factories.
An application can install an initial
context factory builder to define its own policy of how to locate
and construct initial context implementations. When a builder has
been installed, it is solely responsible for creating the initial
context factories. None of the default policies
(java.naming.factory.initial property or URL support)
normally used by JNDI are employed.
An implementation of an initial context
factory builder must implement the
InitialContext-FactoryBuilder interface. Its
createInitialContextFactory() method creates instances
of InitialContextFactory.
After a builder has been installed. the
application can get the initial context by either using the
InitialContext/InitialDirContext/InitialLdapContext
constructors, or by using
NamingManager.getInitialContext(). When one of the
constructors is used, its class is basically a wrapper around the
underlying context implementation returned by
NamingManager.getInitialContext().
When there is a need to provide an
initial context that supports an interface that extends from
Context, DirContext, or
LdapContext, the service provider should supply a
subclass of InitialContext (or
InitialDirContext/InitialLdapContext).
To add support for URLs in the same way
InitialContext and InitialDirContext do,
the subclass should use the protected methods available in
InitialContext as follows. This only makes sense for
interfaces that have methods that accept name argument.
For example, suppose
FooContext is a subinterface of
DirContext. Its initial context implementation would
define getURLOrDefaultInitFooCtx() methods (for both
Name and String parameters) that retrieve
the real initial context to use.
public class InitialFooContext extends InitialDirContext {
...
protected FooContext getURLOrDefaultInitFooCtx(Name name)
throws NamingException {
Context answer = getURLOrDefaultInitCtx(name);
if (!(answer instanceof FooContext)) {
throw new NoInitialContextException("Not a FooContext");
}
return (FooContext)answer;
}
// similar code for getURLOrDefaultInitFooCtx(String name)
}
When providing implementations for the new methods in the
FooContext interface that accept a name argument,
getURLOrDefaultInitFooCtx() is used in the following
way.
public Object FooMethod1(Name name, ...) throws NamingException {
return getURLOrDefaultInitFooCtx(name).FooMethod1(name, ...);
}
When providing implementations for the
new methods in the FooContext interface that do not
have a name argument, or for which URL support is not required, use
InitialContext.getDefaultInitCtx().
protected FooContext getDefaultInitFooCtx() throws NamingException {
Context answer = getDefaultInitCtx();
if (!(answer instanceof FooContext)) {
throw new NoInitialContextException("Not an FooContext");
}
return (FooContext)answer;
}
public Object FooMethod2(Args args) throws NamingException {
return getDefaultInitFooCtx().FooMethod2(args);
}
The implementation should provide
appropriate constructors for the class. The constructor should call
the appropriate constructor of the superclass. If the environment
needs to be modified or examined prior to the superclass's
constructor being called, it should use the protected constructor
that accepts a boolean flag to control the initialization of the
initial context, and then use the init() method to
initialize the context. Here is an example:
public InitialFooContext(Hashtable environment, Object otherArg)
throws NamingException {
super(true); // don't initialize yet
// Clone environment and adjust
Hashtable env = (environment == null) ? new Hashtable(11) :
(Hashtable)environment.clone();
...
init(env);
}
Client programs that use this new initial context would look as
follows.
import com.widget.jndi.InitialFooContext; ... FooContext ctx = new InitialFooContext(env); Object obj = ctx.lookup(name); ctx.FooMethod1(name, ...);
JNDI allows a context implementation to be customized-by the application, the application's deployer or user, or the service provider-in how it reads and stores objects in the naming/directory service. A similar facility is also available for narrowing LDAP v3 control classes.
You can think of these facilities as modules that plug into a context implementation.
JNDI provides a generic way of creating
objects (including instances of Context) using
information stored in the namespace. That information may be of
arbitrary type (java.lang.Object). For example, it may
be a Reference, or a URL, or any other data required
to create the object. Turning such information stored in the
namespace into an object is supported through the use of object
factories. An object factory is a class that implements the
ObjectFactory interface (or the
DirObjectFactory subinterface):
public interface ObjectFactory {
public Object getObjectInstance(Object refObj,
Name name,
Context nameCtx,
Hashtable env)
throws Exception;
}
public interface DirObjectFactory extends ObjectFactory {
public Object getObjectInstance(Object refObj,
Name name,
Context nameCtx,
Hashtable env,
Attributes attrs)
throws Exception;
}
Given some reference information (refObj) about an
object, optional information about the name of the object and where
it is bound, and optionally some additional environment information
(for example, some identity or authentication information about the
user creating the object), the factory attempts to create an object
represented by the reference information. For example, given
reference information about a printer, a printer object factory
might return an instance of Printer. In the case of an
object factory that is to be used with a DirContext
implementation, the factory is also given some attributes about the
object. If the factory requires more attributes or information, it
can obtain them directly from the naming/directory service by using
the name/nameCtx arguments.
If the factory cannot created an object
using the arguments supplied, it should return null.
For example, when a printer object factory is given data about a
disk drive, it should return null. The factory should
only thrown an exception if no other object factories should be
tried. Therefore, the factory should be careful about runtime
exceptions that might be thrown from its implementation. For
example, if a printer object factory is given data about a printer
but the data is malformed in some way, it should throw an
exception.
Object factories are used in several places in JNDI, basically to turn any reference information into an object. They are used in federation, URL processing in the initial context, and, as illustrated by the printer example, turning data into a form expected by the application.
A Reference contains methods
for returning the class name and location of the object factory.
The following methods are found in Reference.
public class Reference {
...
public String getClassName();
public String getFactoryClassName();
public String getFactoryClassLocation();
}
If the object read from the directory/naming service is an instance
of Reference or Referenceable, its
corresponding object factory can be located using information in
Reference. The getFactoryClassName()
method retrieves the name of the factory class that implements the
ObjectFactory interface. This factory must implement
the ObjectFactory interface and have a public
constructor that takes no arguments.
getFactoryClassLocation() retrieves the codebase of
the class implementation for the factory, which is a list of
space-separated URLs.
JNDI creates the object by invoking
getObjectInstance() on the ObjectFactory
instance, by using the Reference and environment as
arguments. The result is an instance of a class identified by
getClassName().
Note that all the classes necessary to instantiate the object returned to the application are made available using mechanisms provided by JNDI. The application doesn't have to install the classes locally.
Figure 3: Example Using Reference to Get Back an Object From the Namespace
Returning to the printer example, suppose
Printer is an interface for representing a printer and
the BSDPrinter class is an implementation of that
interface. BSDPrinter implements the
Referenceable interface and uses the
Reference class to store information on how to
construct instances of BSDPrinter and address
information for communicating with the print server. The
Reference contains the class name of the object
("Printer"), the class name of the printer object
factory ("PrinterFactory") and a URL for loading the
factory's class implementation. Using the factory class name and
implementation location, JNDI first loads the implementation of
PrinterFactory and creates an instance of
PrinterFactory. It then invokes
getObjectInstance() on the factory to create an
instance of Printer using the reference. For example,
one address in the reference may have an address of type
"bsd", and contains the print server's host name
("lobby-printserver"). The PrinterFactory
instance uses the address type ("bsd") to decide to
create a BSDPrinter instance and passes the address
contents ("lobby-printserver") to its constructor. The
resulting BSDPrinter object is returned as the result
of lookup().
From the context implementation's point
of view, all of this is done automatically by its invocation of
NamingManager/DirectoryManager.getObjectInstance().
When the application invokes
print() on the BSDPrinter instance
returned by lookup(), the data is sent to the print
server on the machine "lobby-printserver" for
printing. The application need not know the details of the
Reference stored in the namespace, the protocol used
to perform the job, or whether the BSDPrinter class
was defined locally or loaded over the network. The transformation
of the information stored in the underlying service into an object
that implements the Printer interface is done
transparently through the cooperation of the service provider
(which stores bindings of printer names to printer address
information), the printer service provider (which provides the
PrinterFactory and BSDPrinter classes),
and the JNDI SPI framework (which ties the two together to return
an object that the application can use directly).
A service provider for such an object must do the following:
BSDPrinter)
that implements Referenceable or is a subclass of
Reference. Reference and its reference addresses
for the object. ObjectFactory (e.g., PrinterFactory).
This class's getObjectInstance() method will create an
instance of the class from step 1 (e.g., BSDPrinter)
when given the Reference from step 2. If a Reference contains an
address of type "URL" but not the factory class name and location,
or if the reference is an array of strings containing URLs, JNDI
will use the URL context factory support described in Section 3.2 to locate the factory,
and then pass the URL string in the address to the factory's
getObjectInstance() method. See Section 4.1.6 for a description of
how JNDI expects a URL context factory implementation to
behave.
A service provider for such an object must do the following:
BSDPrinter). ObjectFactory. This class's
getObjectInstance() method will create an instance of
the class from step 1 (e.g., BSDPrinter) when given
the URL from step 2. In addition to extracting factory
information from References, or using URLs, JNDI also
looks for object factories specified in the
java.naming.factory.object property, which can be in
the environment or the provider resource file (see Section 2.9.5). The property contains
a colon-separated list of fully-qualified class names of object
factories. Each class must implement the ObjectFactory
interface and have a public constructor that takes no arguments.
For each class in the list, JNDI attempts to load and instantiate
the factory class, and to invoke the
ObjectFactory/DirObjectFactory.getObjectInstance()
method on it using the object and environment arguments supplied.
If the creation is successful, the resulting object is returned;
otherwise, JNDI uses the same procedure on the next class in the
list until the list is exhausted or a factory returns a
non-null result.
Figure 4: Example using java.naming.factory.object to Get Back an Object from the Namespace
For the printer example, instead of using
a Reference to represent a printer in the namespace,
some other information is stored. When that information is later
retrieved, the object factories specified
java.naming.factory.object are tried in turn to
attempt to turn that information into a Printer
instance.
A service provider for such an object must do the following:
BSDPrinter). Reference. It can be anything that
will be understood by its corresponding object factory (e.g., some
string containing the server name "printer type=bsd;
host=lobby-printserver"). ObjectFactory (e.g., PrinterFactory).
This class's getObjectInstance() method will create an
instance of the class from step 1 (e.g., BSDPrinter)
when given an instance of the class from step 2 (e.g.,
"printer type=bsd; host=lobby-printserver"). The service provider should automatically
convert between the actual object (e.g., BSDPrinter)
and the reference information (step 2, e.g., "printer
type=bsd; host=lobby-printserver") when binding or looking
up the object.
An application that wants to use a
particular factory for generating objects must include the
factory's class name in its java.naming.factory.object
environment property and make the factory's classes and object
classes available.
An object factory builder is a class that creates instances of object factories.
An application can install an object
factory builder to defining its own policy of how to locate and
construct object factory implementations. When a builder has been
installed, it is solely responsible for creating the object
factories. None of the default policies (Reference,
URL string, or java.naming.factory.object property)
normally used by JNDI are employed.
Figure 5: Example using an Object Factory Builder to Get Back an Object from the Namespece
A service provider for an object factory builder must do the following:
ObjectFactory. ObjectFactoryBuilder. This class's
createObjectFactory() method will use the constructors
for the ObjectFactory classes in step 1.An application that wants to use this factory builder must first install it.
NamingManager.setObjectFactoryBuilder(builder);
A context factory is an object
factory that creates instances of Context. The
implementation of these contexts for a particular naming or
directory service is referred to as a context
implementation. Context implementations are described in
Chapter 2. Like any other
object factory, a context factory can be obtained by using any of
the three mechanisms described above: from a
Reference, a URL scheme id, or listed in the
java.naming.factory.object property.
A URL context factory is a special kind
of context factory. It follows these rules when implementing
ObjectFactory.getObjectInstance().
refObj is null, create a context
for resolving URLs of the scheme associated with this factory. The
resulting context is not tied to a specific URL. For example,
invoking
getObjectInstance(null, null, null, env)
ldap://ldap.wiz.com/o=wiz,c=us" or
"ldap://ldap.umich.edu/", ...). refObj is a URL string, create the object
identified by the URL. For example, invoking
getObjectInstance("ldap://ldap.wiz.com/o=wiz,c=us", null, null, env);
o=wiz,c=us" on the LDAP server
ldap.wiz.com. If this happens to name a context, it
can then be used for resolving (relative) LDAP names (e.g.,
"cn=Jane Smith"). refObj is an array of URL strings, the
assumption is that the URLs are equivalent in terms of the context
to which they refer. Verification of whether the URLs are, or need
to be, equivalent is up to the context factory. The order of the
URLs in the array is not significant. The object returned by
getObjectInstance() is the same as that for the single
URL case-it is an object (perhaps a context) named by the URLs.
refObj is any other type, the behavior of
getObjectInstance() is determined by the
implementation.
URL context factories are used by the
InitialContext class when it is passed a URL to
resolve. URL context factories are also used for creating objects
in the Java programming language from URLs stored in the namespace
(see Section 4.1.2).
JNDI provides a mechanism to transform an
object into a form storable by the underlying context
implementation. That form may be any arbitrary type acceptable to
the underlying context implementation. For example, it may be a
Reference, a URL, a Serializable object,
or a set of attributes, or any other data acceptable by the
underlying context implementation. Turning an arbitrary object into
data that can be stored in the namespace is supported through the
use of state factories. A state factory is a class that
implements the StateFactory interface (or the
DirStateFactory subinterface):
public interface StateFactory {
public Object getStateToBind(Object obj,
Name name,
Context nameCtx,
Hashtable env)
throws NamingException;
}
public interface DirStateFactory {
public DirStateFactory.Result getStateToBind(Object obj,
Name name,
Context nameCtx,
Hashtable env,
Attributes attrs)
throws NamingException;
}
Given an object (obj), optional information about the
name of the object and where it is bound, and optionally some
additional environment information (for example, some identity or
authentication information about the user accessing the namespace),
the factory attempts to create an object suitable for binding.
Typically, the state factory is knowledgeable about the target
naming/directory service and/or context implementation, and knows
which data formats are acceptable. In the case of a state factory
that is to be used with a DirContext implementation,
the factory is also given some attributes that are to be stored
with the object. If the factory require more information about the
object, it can obtain them directly from the naming/directory
service by using the name/nameCtx
arguments. For example, a printer state factory for an LDAP
directory might return a set of attributes that represent the
printer.
If the factory cannot return any data
using the arguments supplied, it should return null.
For example, when a printer state factory is given a disk object,
it should return null. The factory should only thrown
an exception if no other state factories should be tried.
Therefore, the factory should be careful about exceptions that
might be thrown from its implementation. For example, if a printer
state factory is given a printer object but perhaps contradictory
attributes, it might throw an exception.
Ultimately, a factory's output formats are determined by the underlying naming/directory service. A context implementation for the CORBA Object Services (COS) naming service, for example, can only store CORBA object references into the service; a context implementation for LDAP can only store attributes, although there is a lot of flexibility in how to encode information within those attributes.
A service provider typically supplies a factory for each (common) type of input that it expects, and the application can augment that set with state factories of its own. For example, a service provider for COS naming might have a state factory for converting a Java Remote Method Invocation (RMI) object into a CORBA object reference. A user of that provider might add a state factory for converting a Microsoft COM object reference into a CORBA object reference.
JNDI looks for state factories specified
in the java.naming.factory.state property, which can
be in the environment or the provider resource file (see Section 2.9.5). The property contains
a colon-separated list of fully-qualified class names of state
factories. Each class must implement the StateFactory
interface and have a public constructor that takes no arguments.
For each class in the list, JNDI attempts to load and instantiate
the factory class, and to invoke the
StateFactory/DirStateFactory.getStateToBind() method
on it using the object, name, context, environment, and attributes
arguments supplied. If the factory produces a non-null
result, the result is returned; otherwise, JNDI uses the same
procedure on the next class in the list until the list is exhausted
or a factory returns a non-null result.
The LDAP v3 protocol allows response
controls to accompany any response sent by the server. The control
consists of an OID string identifier and a sequence of ASN.1 BER
encoded bytes. In the absence of any external information or
assistance, the context implementation can only return a plain
implementation of the Control interface that returns
the OID and bytes.
JNDI provides the following abstract class for dealing with response controls:
public abstract javax.naming.ldap.ControlFactory {
...
public static Control getControlInstance(Control ctl,
Context ctx,
Hashtable env)
throws NamingException;
public abstract Control getControlInstance(Control ctl)
throws NamingException;
}
When a context implementation receives a response control, it
invokes the static getControl-Instance() method to
find a control factory that can narrow the control to one that has
more user-friendly access methods. Such a control, for instance,
can decode the ASN.1 BER bytes and provide access methods that
return the information as Java types. If no such control factory
can be found, the original response control is returned. Here is an
example of a hypothetical Time-ResponseControl which
decodes the time of day.
public class TimeResponseControl implements Control {
long time;
// Constructor used by ControlFactory
public TimeResponseControl(String OID, byte[] berVal)
throws NamingException {
// check validity of OID
time = // extract time from berVal
};
// Type-safe and User-friendly method
public long getTime() {
return time;
}
// Low-level methods
public String getID() {
return TIME_OID;
}
public byte[] getEncodedValue() {
return // original berVal
}
...
}
A control factory may be responsible for one or more controls. If
the factory cannot return a control using the arguments supplied,
it should return null. Typically, this involves just
matching the control's OID against the list of OIDs supported by
the factory. The factory should only thrown an exception if no
other control factories should be tried. Therefore, the factory
should be careful about exceptions that might be thrown from its
implementation. For example, if a control factory is given a
control with an OID that it supports, but the byte array has an
encoding error, it should throw an exception.
Here is an example of a control factory:
public class VendorXControlFactory extends ControlFactory {
public VendorXControlFactory () {
}
public Control getControlInstance(Control orig)
throws NamingException {
if (isOneOfMyControls(orig.getID())) {
...
// determine which of ours it is and call its constructor
return new TimeResponseControl(orig.getID(),
orig.getEncodedValue());
}
return null; // not one of ours
}
}
JNDI looks for response control factories
specified in the java.naming.factory.control property,
which can be in the environment or the provider resource file (see
Section 2.9.5). The property
contains a colon-separated list of fully-qualified class names of
control factories. Each class must implement the
ControlFactory interface and have a public constructor
that takes no arguments. For each class in the list, JNDI attempts
to load and instantiate the factory class, and to invoke the
ControlFactory.getControlInstance() instance method on
it using the control, context, and environment arguments supplied.
If the factory produces a non-null result, the result
is returned; otherwise, JNDI uses the same procedure on the next
class in the list until the list is exhausted or a factory returns
a non-null result.
Any object passed as a parameter to a method in a factory is owned by the caller. Therefore, the factory is prohibited from maintaining a pointer to the object beyond the duration of the operation or modifying the object. If the factory needs to save the information contained in a parameter beyond the duration of the operation, it should maintain its own copy.
A factory instance should be reentrant. That is, it should be possible for multiple threads to invoke methods on a single instance of a factory concurrently.
CannotProceedException may well have been thrown by
one of the context's internal methods when it discovered that the
name being processed is beyond the scope of its naming system. The
process by which the exception is produced is dependent on the
implementation of the context. 3
Note that this is code in the application. In "Continuing an Operation in a
Federation", the code sample presented is code in the
context implementation. 4 You can also use a subclass of Hashtable (e.g.
Properties) for this. 5 The
mention of "URL" in this document refers to a URL string as defined
by RFC 1738 and its related RFCs. It is any string that conforms to
the syntax described therein, and may not always have corresponding
support in the java.net.URL class or Web browsers. The
URL string is either passed as the String name
parameter, or as the first component of the Name
parameter.
