diff -r 836adbf7a2cd -r 3317bb8137f4 jdk/src/java.naming/share/classes/javax/naming/package.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/src/java.naming/share/classes/javax/naming/package.html Sun Aug 17 15:54:13 2014 +0100
@@ -0,0 +1,143 @@
+
+
+
+
+
+
+
+Provides the classes and interfaces for accessing naming services.
+
+
+This package defines the naming operations of the Java Naming and
+Directory InterfaceTM (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.
+
+
+
Context
+
+This package defines the notion of a context, represented
+by the Context interface.
+A context consists of a set of name-to-object bindings.
+Context is the core interface for looking up, binding, unbinding,
+and renaming objects, and for creating and destroying subcontexts.
+
+lookup() is the most commonly used operation.
+You supply lookup()
+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:
+
+
+
+Printer printer = (Printer)ctx.lookup("treekiller");
+printer.print(report);
+
+
+
+Names
+
+Every naming method in the Context
+interface has two
+overloads: one that accepts a
+Name argument and one that accepts a string name.
+Name is an interface that represents a generic
+name--an ordered sequence of zero of more components.
+For these methods, Name can be used to represent a
+composite name (CompositeName)
+so that you can name an object using a name which spans multiple namespaces.
+
+The overloads that accept Name
+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.
+
+
Bindings
+
+The Binding 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 Binding class is actually a subclass of
+NameClassPair, which consists
+simply of the object's name and the object's class name.
+The NameClassPair 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.
+
+
References
+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 reference, represented by the Reference
+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.
+
+
+The Initial Context
+
+In JNDI, all naming and directory operations are performed relative
+to a context. There are no absolute roots.
+Therefore JNDI defines an initial context,
+InitialContext,
+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.
+
+Exceptions
+
+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 NamingException.
+Programs interested in dealing with a particular exception
+can catch the corresponding subclass of the exception.
+Otherwise, programs should catch NamingException.
+
+
+Package Specification
+
+The JNDI API Specification and related documents can be found in the
+JNDI documentation.
+
+@since 1.3
+
+
+