0N/A<!
DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
2362N/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 2362N/Apublished by the Free Software Foundation. Oracle designates this 0N/Aparticular file as subject to the "Classpath" exception as provided 2362N/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. 2365N/APlease contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 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>
0N/Aoverloads: one that accepts a
0N/A<
tt>Name</
tt> argument and one that accepts a string name.
0N/A<
tt>Name</
tt> is an interface that represents a generic
0N/Aname--an ordered sequence of zero of more components.
0N/AFor these methods, <
tt>Name</
tt> can be used to represent a
0N/A<
em>composite name</
em> (<
tt>CompositeName</
tt>)
0N/Aso that you can name an object using a name which spans multiple namespaces.
0N/AThe overloads that accept <
tt>Name</
tt>
0N/Aare useful for applications that need to manipulate names: composing
0N/Athem, comparing components, and so on.
0N/AThe overloads that accept string names are likely to be more useful
0N/Afor simple applications, such as those that simply read in a name
0N/Aand look up the corresponding object.
0N/AThe <
tt>Binding</
tt> class represents a name-to-object binding.
0N/AIt is a tuple containing the name of the bound object,
0N/Athe name of the object's class, and the object itself.
0N/AThe <
tt>Binding</
tt> class is actually a subclass of
0N/A<
tt>NameClassPair</
tt>, which consists
0N/Asimply of the object's name and the object's class name.
0N/AThe <
tt>NameClassPair</
tt> is useful when you only want
0N/Ainformation about the object's class and do not want to
0N/Apay the extra cost of getting the object.
0N/AObjects are stored in naming and directory services in different ways.
0N/AIf an object store supports storing Java objects,
0N/Ait might support storing an object in its serialized form.
0N/AHowever, some naming and directory services do not support the
0N/Astoring of Java objects. Furthermore, for some
0N/Aobjects in the directory, Java programs are but one group of applications
0N/Athat access them. In this case, a serialized Java object might
0N/Anot be the most appropriate representation.
0N/AJNDI defines a <
em>reference</
em>, represented by the <
tt>Reference</
tt>
0N/Aclass, which contains information on how to construct a copy of the object.
0N/AJNDI will attempt to turn references looked up from the directory
0N/Ainto the Java objects they represent, so that
0N/AJNDI clients have the illusion that what
0N/Ais stored in the directory are Java objects.
0N/A<
h4>The Initial Context</
h4>
0N/AIn JNDI, all naming and directory operations are performed relative
0N/Ato a context. There are no absolute roots.
0N/ATherefore JNDI defines an <
em>initial context</
em>,
0N/A<
tt>InitialContext</
tt>,
0N/Awhich provides a starting point for naming and directory operations.
0N/AOnce you have an initial context, you can use it to
0N/Alook up other contexts and objects.
0N/AJNDI defines a class hierarchy for exceptions that can be thrown in
0N/Athe course of performing naming and directory operations. The root of
0N/Athis class hierarchy is <
tt>NamingException</
tt>.
0N/APrograms interested in dealing with a particular exception
0N/Acan catch the corresponding subclass of the exception.
0N/AOtherwise, programs should catch <
tt>NamingException</
tt>.
0N/A<
h2>Package Specification</
h2>
0N/AThe JNDI API Specification and related documents can be found in the