2 <html>
   3 <head>
   4 <!--
   5 Copyright (c) 1999, 2019, Oracle and/or its affiliates. All rights reserved.
   8 This code is free software; you can redistribute it and/or modify it
   9 under the terms of the GNU General Public License version 2 only, as
  10 published by the Free Software Foundation.  Oracle designates this
  11 particular file as subject to the "Classpath" exception as provided
  12 by Oracle in the LICENSE file that accompanied this code.
  14 This code is distributed in the hope that it will be useful, but WITHOUT
  15 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  16 FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  17 version 2 for more details (a copy is included in the LICENSE file that
  18 accompanied this code).
  20 You should have received a copy of the GNU General Public License version
  21 2 along with this work; if not, write to the Free Software Foundation,
  22 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  24 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  25 or visit www.oracle.com if you need additional information or have any
  26 questions.
  27 -->
  28 </head>
  29 <body bgcolor="white">
  31 Provides the classes and interfaces for accessing naming services.
  33 <p>
  34 This package defines the naming operations of the Java Naming and
  35 Directory Interface&trade; (JNDI). &nbsp;
  36 JNDI provides naming and directory functionality to applications
  37 written in the Java programming language.  It is designed to be
  38 independent of any specific naming or directory service
  39 implementation.  Thus a variety of services--new, emerging, and
  40 already deployed ones--can be accessed in a common way.
  43 <h2>Context</h2>
  44 <p>
  45 This package defines the notion of a <em>context</em>, represented
  46 by the <code>Context</code> interface.
  47 A context consists of a set of name-to-object <em>bindings</em>.
  48 <code>Context</code> is the core interface for looking up, binding, unbinding,
  49 and renaming objects, and for creating and destroying subcontexts.
  50 <p>
  51 <code>lookup()</code> is the most commonly used operation.
  52 You supply <code>lookup()</code>
  53 the name of the object you want
  54 to look up, and it returns the object bound to that name.
  55 For example, the following code fragment looks up 
  56 a printer and sends a document to the printer object
  57 to be printed:
  59 <blockquote>
  60 <pre>
  61 Printer printer = (Printer)ctx.lookup("treekiller");
  62 printer.print(report);
  63 </pre>
  64 </blockquote>
  66 <h2>Names</h2>
  67 <p>
  68 Every naming method in the <code>Context</code>
  69 interface has two
  70 overloads: one that accepts a 
  71 <code>Name</code> argument and one that accepts a string name.
  72 <code>Name</code> is an interface that represents a generic 
  73 name--an ordered sequence of zero of more components.
  74 For these methods, <code>Name</code> can be used to represent a
  75 <em>composite name</em> (<code>CompositeName</code>)
  76 so that you can name an object using a name which spans multiple namespaces.
  77 <p>
  78 The overloads that accept <code>Name</code>
  79 are useful for applications that need to manipulate names: composing
  80 them, comparing components, and so on.
  81 The overloads that accept string names are likely to be more useful
  82 for simple applications, such as those that simply read in a name
  83 and look up the corresponding object.
  85 <h2>Bindings</h2>
  87 The <code>Binding</code> class represents a name-to-object binding.
  88 It is a tuple containing the name of the bound object,
  89 the name of the object's class, and the object itself.
  90 <p>
  91 The <code>Binding</code> class is actually a subclass of
  92 <code>NameClassPair</code>, which consists
  93 simply of the object's name and the object's class name.
  94 The <code>NameClassPair</code> is useful when you only want
  95 information about the object's class and do not want to
  96 pay the extra cost of getting the object.
  98 <h2>References</h2>
  99 Objects are stored in naming and directory services in different ways.
 100 If an object store supports storing Java objects, 
 101 it might support storing an object in its serialized form.
 102 However, some naming and directory services do not support the
 103 storing of Java objects. Furthermore, for some
 104 objects in the directory, Java programs are but one group of applications 
 105 that access them. In this case, a serialized Java object might
 106 not be the most appropriate representation.
 107 JNDI defines a <em>reference</em>, represented by the <code>Reference</code>
 108 class, which contains information on how to construct a copy of the object.
 109 JNDI will attempt to turn references looked up from the directory
 110 into the Java objects they represent, so that
 111 JNDI clients have the illusion that what
 112 is stored in the directory are Java objects. 
 115 <h2>The Initial Context</h2>
 117 In JNDI, all naming and directory operations are performed relative
 118 to a context. There are no absolute roots.
 119 Therefore JNDI defines an <em>initial context</em>, 
 120 <code>InitialContext</code>,
 121 which provides a starting point for naming and directory operations.
 122 Once you have an initial context, you can use it to
 123 look up other contexts and objects.
 125 <h2>Exceptions</h2>
 127 JNDI defines a class hierarchy for exceptions that can be thrown in
 128 the course of performing naming and directory operations.  The root of
 129 this class hierarchy is <code>NamingException</code>.
 130 Programs interested in dealing with a particular exception
 131 can catch the corresponding subclass of the exception.
 132 Otherwise, programs should catch <code>NamingException</code>.
 135 <h2>Package Specification</h2>
 137 The JNDI API Specification and related documents can be found in the
 138 {@extLink jndi_overview JNDI documentation}.
 140 @since 1.3
 142 </body>
 143 </html>