diff -r 4ebc2e2fb97c -r 71c04702a3d5 src/java.naming/share/classes/javax/naming/package.html --- /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 @@ + + + + + + + +Provides the classes and interfaces for accessing naming services. + +

+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. + + +

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 +{@extLink jndi_overview JNDI documentation}. + +@since 1.3 + + +