| |
Package Name | Comment | javax.naming |
Provides the classes and interfaces for accessing naming services.
This package defines the naming operations of the Java Naming and
Directory InterfaceTM (JNDI).
JNDI provides naming and directory functionality to applications
written in the Java programming language. It is designed to be
independent of any specific naming or directory service
implementation. Thus a variety of services--new, emerging, and
already deployed ones--can be accessed in a common way.
Context
This package defines the notion of a context, represented
by the Context interface.
A context consists of a set of name-to-object bindings.
Context is the core interface for looking up, binding, unbinding,
and renaming objects, and for creating and destroying subcontexts.
lookup() is the most commonly used operation.
You supply lookup()
the name of the object you want
to look up, and it returns the object bound to that name.
For example, the following code fragment looks up
a printer and sends a document to the printer object
to be printed:
Printer printer = (Printer)ctx.lookup("treekiller");
printer.print(report);
Names
Every naming method in the Context
interface has two
overloads: one that accepts a
Name argument and one that accepts a string name.
Name is an interface that represents a generic
name--an ordered sequence of zero of more components.
For these methods, Name can be used to represent a
composite name (CompositeName)
so that you can name an object using a name which spans multiple namespaces.
The overloads that accept Name
are useful for applications that need to manipulate names: composing
them, comparing components, and so on.
The overloads that accept string names are likely to be more useful
for simple applications, such as those that simply read in a name
and look up the corresponding object.
Bindings
The Binding class represents a name-to-object binding.
It is a tuple containing the name of the bound object,
the name of the object's class, and the object itself.
The Binding class is actually a subclass of
NameClassPair, which consists
simply of the object's name and the object's class name.
The NameClassPair is useful when you only want
information about the object's class and do not want to
pay the extra cost of getting the object.
References
Objects are stored in naming and directory services in different ways.
If an object store supports storing Java objects,
it might support storing an object in its serialized form.
However, some naming and directory services do not support the
storing of Java objects. Furthermore, for some
objects in the directory, Java programs are but one group of applications
that access them. In this case, a serialized Java object might
not be the most appropriate representation.
JNDI defines a reference, represented by the Reference
class, which contains information on how to construct a copy of the object.
JNDI will attempt to turn references looked up from the directory
into the Java objects they represent, so that
JNDI clients have the illusion that what
is stored in the directory are Java objects.
The Initial Context
In JNDI, all naming and directory operations are performed relative
to a context. There are no absolute roots.
Therefore JNDI defines an initial context,
InitialContext,
which provides a starting point for naming and directory operations.
Once you have an initial context, you can use it to
look up other contexts and objects.
Exceptions
JNDI defines a class hierarchy for exceptions that can be thrown in
the course of performing naming and directory operations. The root of
this class hierarchy is NamingException.
Programs interested in dealing with a particular exception
can catch the corresponding subclass of the exception.
Otherwise, programs should catch NamingException.
Package Specification
The JNDI API Specification and related documents can be found in the
JNDI documentation.
@since 1.3
| javax.naming.directory |
Extends the javax.naming package to provide functionality
for accessing directory services.
This package defines the directory operations of the Java Naming and
Directory InterfaceTM (JNDI).
JNDI provides naming and directory functionality to applications
written in the Java programming language. It is designed to be
independent of any specific naming or directory service
implementation. Thus a variety of services--new, emerging, and
already deployed ones--can be accessed in a common way.
This package allows applications to retrieve and update attributes
associated with objects stored in a directory, and to search for
objects using specified attributes.
The Directory Context
The DirContext
interface represents a directory context.
It defines methods for examining and updating attributes associated with a
directory object, or directory entry as it is sometimes
called.
You use getAttributes() to retrieve the attributes
associated with a directory object (for which you supply the name).
Attributes are modified using modifyAttributes().
You can add, replace, or remove attributes and/or attribute values
using this operation.
DirContext also behaves as a naming context
by extending the Context interface in the javax.naming package.
This means that any directory object can also provide
a naming context.
For example, the directory object for a person might contain
the attributes of that person, and at the same time provide
a context for naming objects relative to that person
such as his printers and home directory.
Searches
DirContext contains methods for
performing content-based searching of the directory.
In the simplest and most common form of usage, the application
specifies a set of attributes--possibly with specific
values--to match, and submits this attribute set, to the
search() method.
There are other overloaded forms of search()
that support more sophisticated search filters.
Package Specification
The JNDI API Specification and related documents can be found in the
JNDI documentation.
@since 1.3
| javax.naming.event |
Provides support for event notification when accessing naming and
directory services.
This package defines the event notification operations of the Java Naming
and Directory InterfaceTM (JNDI).
JNDI provides naming and directory functionality to applications
written in the Java programming language. It is designed to be
independent of any specific naming or directory service
implementation. Thus a variety of services--new, emerging, and
already deployed ones--can be accessed in a common way.
Naming Events
This package defines a NamingEvent class to represent an event
that is generated by a naming/directory service.
It also defines subinterfaces of Context and DirContext,
called EventContext and EventDirContext,
through which applications can register their interest in events
fired by the context.
NamingEvent represents an event that occurs in a
naming or directory service. There are two categories of naming events:
- Those that affect the namespace (add/remove/rename an object)
- Those that affect the objects' contents.
Each category of events is handled by a corresponding listener:
NamespaceChangeListener, ObjectChangeListener.
An application, for example, can register its interest in changes to
objects in a context as follows:
EventContext src =
(EventContext)(new InitialContext()).lookup("o=wiz,c=us");
src.addNamingListener("ou=users", EventContext.ONELEVEL_SCOPE,
new ChangeHandler());
...
class ChangeHandler implements ObjectChangeListener {
public void objectChanged(NamingEvent evt) {
System.out.println(evt.getNewBinding());
}
public void namingExceptionThrown(NamingExceptionEvent evt) {
System.out.println(evt.getException());
}
}
Threading Issues
When an event is dispatched to a listener, the listener method (such
as objectChanged()) may be executed in a thread other than the
one in which the call to addNamingListener() was executed.
The choice of which thread to use is made by the service provider.
When an event is dispatched to multiple listeners, the service provider
may choose (and is generally encouraged) to execute the listener methods
concurrently in separate threads.
When a listener instance invokes NamingEvent.getEventContext(),
it must take into account the possibility that other threads will be
working with that context concurrently. Likewise, when a listener is
registered via addNamingListener(), the registering thread
must take into account the likely possibility that the service provider
will later invoke the listeners in newly-created threads. As Context
instances are not guaranteed to be thread-safe in general, all context
operations must be synchronized as needed.
Exception Handling
When a listener registers for events with a context, the context might
need to do some internal processing in order to collect information
required to generate the events. The context, for example, might need
to make a request to the server to register interest in changes
on the server that will eventually be translated into events.
If an exception occurs that prevents information about the events from
being collected, the listener will never be notified of the events.
When such an exception occurs, a NamingExceptionEvent is
fired to notify the listener. The listener's
namingExceptionThrown() method is invoked, as shown in the
sample code above,
and the listener is automatically deregistered.
Package Specification
The JNDI API Specification and related documents can be found in the
JNDI documentation.
@since 1.3
| javax.naming.ldap |
Provides support for LDAPv3 extended operations and controls.
This package extends the directory operations of the Java Naming and
Directory InterfaceTM (JNDI).
JNDI provides naming and directory functionality to applications
written in the Java programming language. It is designed to be
independent of any specific naming or directory service
implementation. Thus a variety of services--new, emerging, and
already deployed ones--can be accessed in a common way.
This package is for applications and service providers that deal with
LDAPv3 extended operations and controls, as defined by
RFC 2251.
The core interface in this package is LdapContext, which defines
methods on a context for performing extended operations and handling
controls.
Extended Operations
This package defines the interface ExtendedRequest
to represent the argument to an extended operation,
and the interface ExtendedResponse to represent the result
of the extended operation.
An extended response is always paired with an extended request
but not necessarily vice versa. That is, you can have an extended request
that has no corresponding extended response.
An application typically does not deal directly with these interfaces.
Instead, it deals with classes that implement these
interfaces.
The application gets these classes either as part of a
repertoire of extended operations standardized through the IETF, or
from directory vendors for vendor-specific extended operations.
The request classes should have constructors that accept
arguments in a type-safe and user-friendly manner, while the
response classes should have access methods for getting the data
of the response in a type-safe and user-friendly manner.
Internally, the request/response classes deal with encoding and decoding
BER values.
For example, suppose an LDAP server supports a "get time" extended operation.
It would supply classes such as
GetTimeRequest and GetTimeResponse,
so that applications can use this feature.
An application would use these classes as follows:
GetTimeResponse resp =
(GetTimeResponse) ectx.extendedOperation(new GetTimeRequest());
long time = resp.getTime();
The GetTimeRequest and GetTimeResponse classes might
be defined as follows:
public class GetTimeRequest implements ExtendedRequest {
// User-friendly constructor
public GetTimeRequest() {
};
// Methods used by service providers
public String getID() {
return GETTIME_REQ_OID;
}
public byte[] getEncodedValue() {
return null; // no value needed for get time request
}
public ExtendedResponse createExtendedResponse(
String id, byte[] berValue, int offset, int length) throws NamingException {
return new GetTimeResponse(id, berValue, offset, length);
}
}
public class GetTimeResponse() implements ExtendedResponse {
long time;
// called by GetTimeRequest.createExtendedResponse()
public GetTimeResponse(String id, byte[] berValue, int offset, int length)
throws NamingException {
// check validity of id
long time = ... // decode berValue to get time
}
// Type-safe and User-friendly methods
public java.util.Date getDate() { return new java.util.Date(time); }
public long getTime() { return time; }
// Low level methods
public byte[] getEncodedValue() {
return // berValue saved;
}
public String getID() {
return GETTIME_RESP_OID;
}
}
Controls
This package defines the interface Control to represent an LDAPv3
control. It can be a control that is sent to an LDAP server
(request control) or a control returned by an LDAP server
(response control). Unlike extended requests and responses,
there is not necessarily any pairing between request controls and
response controls. You can send request controls and expect no
response controls back, or receive response controls without sending
any request controls.
An application typically does not deal directly with this interface.
Instead, it deals with classes that implement this interface.
The application gets control classes either as part of a repertoire of
controls standardized through the IETF, or from directory vendors for
vendor-specific controls. The request control classes should have
constructors that accept arguments in a type-safe and user-friendly
manner, while the response control classes should have access methods
for getting the data of the response in a type-safe and user-friendly
manner. Internally, the request/response control classes deal with
encoding and decoding BER values.
For example, suppose an LDAP server supports a "signed results"
request control, which when sent with a request, asks the
server to digitally sign the results of an operation.
It would supply a class SignedResultsControl so that applications
can use this feature.
An application would use this class as follows:
Control[] reqCtls = new Control[] {new SignedResultsControl(Control.CRITICAL)};
ectx.setRequestControls(reqCtls);
NamingEnumeration enum = ectx.search(...);
The SignedResultsControl class might be defined as follows:
public class SignedResultsControl implements Control {
// User-friendly constructor
public SignedResultsControl(boolean criticality) {
// assemble the components of the request control
};
// Methods used by service providers
public String getID() {
return // control's object identifier
}
public byte[] getEncodedValue() {
return // ASN.1 BER encoded control value
}
...
}
When a service provider receives response controls, it uses
the ControlFactory class to produce specific classes
that implement the Control interface.
An LDAP server can send back response controls with an LDAP operation
and also with enumeration results, such as those returned
by a list or search operation.
The LdapContext provides a method (getResponseControls())
for getting the response controls sent with an LDAP operation,
while the HasControls interface is used to retrieve
response controls associated with enumeration results.
For example, suppose an LDAP server sends back a "change ID" control in response
to a successful modification. It would supply a class ChangeIDControl
so that the application can use this feature.
An application would perform an update, and then try to get the change ID.
// Perform update
Context ctx = ectx.createSubsubcontext("cn=newobj");
// Get response controls
Control[] respCtls = ectx.getResponseControls();
if (respCtls != null) {
// Find the one we want
for (int i = 0; i < respCtls; i++) {
if(respCtls[i] instanceof ChangeIDControl) {
ChangeIDControl cctl = (ChangeIDControl)respCtls[i];
System.out.println(cctl.getChangeID());
}
}
}
The vendor might supply the following ChangeIDControl and
VendorXControlFactory classes. The VendorXControlFactory
will be used by the service provider when the provider receives response
controls from the LDAP server.
public class ChangeIDControl implements Control {
long id;
// Constructor used by ControlFactory
public ChangeIDControl(String OID, byte[] berVal) throws NamingException {
// check validity of OID
id = // extract change ID from berVal
};
// Type-safe and User-friendly method
public long getChangeID() {
return id;
}
// Low-level methods
public String getID() {
return CHANGEID_OID;
}
public byte[] getEncodedValue() {
return // original berVal
}
...
}
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 ChangeIDControl(orig.getID(), orig.getEncodedValue()));
}
return null; // not one of ours
}
}
Package Specification
The JNDI API Specification and related documents can be found in the
JNDI documentation.
@since 1.3
| javax.naming.spi |
Provides the means for dynamically plugging in support for accessing
naming and directory services through the javax.naming
and related packages.
This package defines the service provider interface (SPI) of the Java Naming
and Directory InterfaceTM (JNDI).
JNDI provides naming and directory functionality to applications
written in the Java programming language. It is designed to be
independent of any specific naming or directory service
implementation. Thus a variety of services--new, emerging, and
already deployed ones--can be accessed in a common way.
The JNDI SPI provides the means for creating JNDI service providers,
through which JNDI applications access different naming and
directory services.
Plug-in Architecture
The service provider package allows different implementations to be plugged in
dynamically.
These different implementations include those for the
initial context,
and implementations for contexts that can be reached
from the initial context.
Java Object Support
The service provider package provides support
for implementors of the
javax.naming.Context.lookup()
method and related methods to return Java objects that are natural
and intuitive for the Java programmer.
For example, when looking up a printer name from the directory,
it is natural for you to expect to get
back a printer object on which to operate.
Multiple Naming Systems (Federation)
JNDI operations allow applications to supply names that span multiple
naming systems. So in the process of completing
an operation, one service provider might need to interact
with another service provider, for example, to pass on
the operation to be continued in the next naming system.
The service provider package provides support for
different providers to cooperate to complete JNDI operations.
Package Specification
The JNDI SPI Specification and related documents can be found in the
JNDI documentation.
@since 1.3
|
|