--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/src/share/classes/javax/naming/package.html Sat Dec 01 00:00:00 2007 +0000
@@ -0,0 +1,144 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<html>
+<head>
+<!--
+Copyright 1999-2006 Sun Microsystems, Inc. All Rights Reserved.
+DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+
+This code is free software; you can redistribute it and/or modify it
+under the terms of the GNU General Public License version 2 only, as
+published by the Free Software Foundation. Sun designates this
+particular file as subject to the "Classpath" exception as provided
+by Sun in the LICENSE file that accompanied this code.
+
+This code is distributed in the hope that it will be useful, but WITHOUT
+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+version 2 for more details (a copy is included in the LICENSE file that
+accompanied this code).
+
+You should have received a copy of the GNU General Public License version
+2 along with this work; if not, write to the Free Software Foundation,
+Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+
+Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
+CA 95054 USA or visit www.sun.com if you need additional information or
+have any questions.
+-->
+</head>
+<body bgcolor="white">
+
+Provides the classes and interfaces for accessing naming services.
+
+<p>
+This package defines the naming operations of the Java Naming and
+Directory Interface<font size=-2><sup>TM</sup></font> (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.
+
+
+<h4>Context</h4>
+<p>
+This package defines the notion of a <em>context</em>, represented
+by the <tt>Context</tt> interface.
+A context consists of a set of name-to-object <em>bindings</em>.
+<tt>Context</tt> is the core interface for looking up, binding, unbinding,
+and renaming objects, and for creating and destroying subcontexts.
+<p>
+<tt>lookup()</tt> is the most commonly used operation.
+You supply <tt>lookup()</tt>
+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:
+
+<blockquote>
+<pre>
+Printer printer = (Printer)ctx.lookup("treekiller");
+printer.print(report);
+</pre>
+</blockquote>
+
+<h4>Names</h4>
+<p>
+Every naming method in the <tt>Context</tt>
+interface has two
+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.
+<p>
+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.
+<p>
+
+<h4>Bindings</h4>
+
+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.
+<p>
+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.
+
+<h4>References</h4>
+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>,
+<tt>InitialContext</tt>,
+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.
+
+<h4>Exceptions</h4>
+
+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
+<a href="../../../technotes/guides/jndi/index.html">JNDI documentation</a>.
+
+@since 1.3
+
+</body>
+</html>