0N/A<!
DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
0N/ACopyright (c) 1999, 2006, Oracle and/or its affiliates. All rights reserved. 0N/ADO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/AThis code is free software; you can redistribute it and/or modify it 0N/Aunder the terms of the GNU General Public License version 2 only, as 0N/Apublished by the Free Software Foundation. Oracle designates this 0N/Aparticular file as subject to the "Classpath" exception as provided 0N/Aby Oracle in the LICENSE file that accompanied this code. 0N/AThis code is distributed in the hope that it will be useful, but WITHOUT 0N/AANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/AFITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/Aversion 2 for more details (a copy is included in the LICENSE file that 0N/Aaccompanied this code). 0N/AYou should have received a copy of the GNU General Public License version 0N/A2 along with this work; if not, write to the Free Software Foundation, 0N/AInc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 0N/APlease contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, 0N/ACA 95054 USA or visit www.sun.com if you need additional information or 0N/A<
body bgcolor="white">
0N/AProvides the classes and interfaces for accessing naming services.
0N/AThis package defines the naming operations of the Java Naming and
0N/ADirectory Interface<
font size=-
2><
sup>TM</
sup></
font> (JNDI).
0N/AJNDI provides naming and directory functionality to applications
0N/Awritten in the Java programming language. It is designed to be
0N/Aindependent of any specific naming or directory service
0N/Aimplementation. Thus a variety of services--new, emerging, and
0N/Aalready deployed ones--can be accessed in a common way.
0N/AThis package defines the notion of a <
em>context</
em>, represented
0N/Aby the <
tt>Context</
tt> interface.
0N/AA context consists of a set of name-to-object <
em>bindings</
em>.
0N/A<
tt>Context</
tt> is the core interface for looking up, binding, unbinding,
0N/Aand renaming objects, and for creating and destroying subcontexts.
0N/A<
tt>lookup()</
tt> is the most commonly used operation.
0N/AYou supply <
tt>lookup()</
tt>
0N/Athe name of the object you want
0N/Ato look up, and it returns the object bound to that name.
0N/AFor example, the following code fragment looks up
0N/Aa printer and sends a document to the printer object
0N/AEvery naming method in the <
tt>Context</
tt>
overloads: one that accepts a
<
tt>Name</
tt> argument and one that accepts a string name.
<
tt>Name</
tt> is an interface that represents a generic
name--an ordered sequence of zero of more components.
For these methods, <
tt>Name</
tt> can be used to represent a
<
em>composite name</
em> (<
tt>CompositeName</
tt>)
so that you can name an object using a name which spans multiple namespaces.
The overloads that accept <
tt>Name</
tt>
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.
The <
tt>Binding</
tt> 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 <
tt>Binding</
tt> class is actually a subclass of
<
tt>NameClassPair</
tt>, which consists
simply of the object's name and the object's class name.
The <
tt>NameClassPair</
tt> 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.
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 <
em>reference</
em>, represented by the <
tt>Reference</
tt>
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.
<
h4>The Initial Context</
h4>
In JNDI, all naming and directory operations are performed relative
to a context. There are no absolute roots.
Therefore JNDI defines an <
em>initial context</
em>,
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.
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 <
tt>NamingException</
tt>.
Programs interested in dealing with a particular exception
can catch the corresponding subclass of the exception.
Otherwise, programs should catch <
tt>NamingException</
tt>.
<
h2>Package Specification</
h2>
The JNDI API Specification and related documents can be found in the