--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/src/java.naming/share/classes/javax/naming/package.html Tue Sep 12 19:03:39 2017 +0200
@@ -0,0 +1,143 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<html>
+<head>
+<!--
+Copyright (c) 1999, 2006, Oracle and/or its affiliates. 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. Oracle designates this
+particular file as subject to the "Classpath" exception as provided
+by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+or visit www.oracle.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™ (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.
+
+
+<h3>Context</h3>
+<p>
+This package defines the notion of a <em>context</em>, represented
+by the <code>Context</code> interface.
+A context consists of a set of name-to-object <em>bindings</em>.
+<code>Context</code> is the core interface for looking up, binding, unbinding,
+and renaming objects, and for creating and destroying subcontexts.
+<p>
+<code>lookup()</code> is the most commonly used operation.
+You supply <code>lookup()</code>
+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>
+
+<h3>Names</h3>
+<p>
+Every naming method in the <code>Context</code>
+interface has two
+overloads: one that accepts a
+<code>Name</code> argument and one that accepts a string name.
+<code>Name</code> is an interface that represents a generic
+name--an ordered sequence of zero of more components.
+For these methods, <code>Name</code> can be used to represent a
+<em>composite name</em> (<code>CompositeName</code>)
+so that you can name an object using a name which spans multiple namespaces.
+<p>
+The overloads that accept <code>Name</code>
+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.
+
+<h3>Bindings</h3>
+
+The <code>Binding</code> 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 <code>Binding</code> class is actually a subclass of
+<code>NameClassPair</code>, which consists
+simply of the object's name and the object's class name.
+The <code>NameClassPair</code> 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.
+
+<h3>References</h3>
+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 <code>Reference</code>
+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.
+
+
+<h3>The Initial Context</h3>
+
+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>,
+<code>InitialContext</code>,
+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.
+
+<h3>Exceptions</h3>
+
+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 <code>NamingException</code>.
+Programs interested in dealing with a particular exception
+can catch the corresponding subclass of the exception.
+Otherwise, programs should catch <code>NamingException</code>.
+
+
+<h2>Package Specification</h2>
+
+The JNDI API Specification and related documents can be found in the
+{@extLink jndi_overview JNDI documentation}.
+
+@since 1.3
+
+</body>
+</html>