| J. Duke | 319a3b9 | 2007-12-01 00:00:00 +0000 | [diff] [blame^] | 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> |
| 2 | <html> |
| 3 | <head> |
| 4 | <!-- |
| 5 | Copyright 1999-2006 Sun Microsystems, Inc. All Rights Reserved. |
| 6 | DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| 7 | |
| 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. Sun designates this |
| 11 | particular file as subject to the "Classpath" exception as provided |
| 12 | by Sun in the LICENSE file that accompanied this code. |
| 13 | |
| 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). |
| 19 | |
| 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. |
| 23 | |
| 24 | Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, |
| 25 | CA 95054 USA or visit www.sun.com if you need additional information or |
| 26 | have any questions. |
| 27 | --> |
| 28 | </head> |
| 29 | <body bgcolor="white"> |
| 30 | |
| 31 | Provides the classes and interfaces for accessing naming services. |
| 32 | |
| 33 | <p> |
| 34 | This package defines the naming operations of the Java Naming and |
| 35 | Directory Interface<font size=-2><sup>TM</sup></font> (JNDI). |
| 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. |
| 41 | |
| 42 | |
| 43 | <h4>Context</h4> |
| 44 | <p> |
| 45 | This package defines the notion of a <em>context</em>, represented |
| 46 | by the <tt>Context</tt> interface. |
| 47 | A context consists of a set of name-to-object <em>bindings</em>. |
| 48 | <tt>Context</tt> is the core interface for looking up, binding, unbinding, |
| 49 | and renaming objects, and for creating and destroying subcontexts. |
| 50 | <p> |
| 51 | <tt>lookup()</tt> is the most commonly used operation. |
| 52 | You supply <tt>lookup()</tt> |
| 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: |
| 58 | |
| 59 | <blockquote> |
| 60 | <pre> |
| 61 | Printer printer = (Printer)ctx.lookup("treekiller"); |
| 62 | printer.print(report); |
| 63 | </pre> |
| 64 | </blockquote> |
| 65 | |
| 66 | <h4>Names</h4> |
| 67 | <p> |
| 68 | Every naming method in the <tt>Context</tt> |
| 69 | interface has two |
| 70 | overloads: one that accepts a |
| 71 | <tt>Name</tt> argument and one that accepts a string name. |
| 72 | <tt>Name</tt> is an interface that represents a generic |
| 73 | name--an ordered sequence of zero of more components. |
| 74 | For these methods, <tt>Name</tt> can be used to represent a |
| 75 | <em>composite name</em> (<tt>CompositeName</tt>) |
| 76 | so that you can name an object using a name which spans multiple namespaces. |
| 77 | <p> |
| 78 | The overloads that accept <tt>Name</tt> |
| 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. |
| 84 | <p> |
| 85 | |
| 86 | <h4>Bindings</h4> |
| 87 | |
| 88 | The <tt>Binding</tt> class represents a name-to-object binding. |
| 89 | It is a tuple containing the name of the bound object, |
| 90 | the name of the object's class, and the object itself. |
| 91 | <p> |
| 92 | The <tt>Binding</tt> class is actually a subclass of |
| 93 | <tt>NameClassPair</tt>, which consists |
| 94 | simply of the object's name and the object's class name. |
| 95 | The <tt>NameClassPair</tt> is useful when you only want |
| 96 | information about the object's class and do not want to |
| 97 | pay the extra cost of getting the object. |
| 98 | |
| 99 | <h4>References</h4> |
| 100 | Objects are stored in naming and directory services in different ways. |
| 101 | If an object store supports storing Java objects, |
| 102 | it might support storing an object in its serialized form. |
| 103 | However, some naming and directory services do not support the |
| 104 | storing of Java objects. Furthermore, for some |
| 105 | objects in the directory, Java programs are but one group of applications |
| 106 | that access them. In this case, a serialized Java object might |
| 107 | not be the most appropriate representation. |
| 108 | JNDI defines a <em>reference</em>, represented by the <tt>Reference</tt> |
| 109 | class, which contains information on how to construct a copy of the object. |
| 110 | JNDI will attempt to turn references looked up from the directory |
| 111 | into the Java objects they represent, so that |
| 112 | JNDI clients have the illusion that what |
| 113 | is stored in the directory are Java objects. |
| 114 | |
| 115 | |
| 116 | <h4>The Initial Context</h4> |
| 117 | |
| 118 | In JNDI, all naming and directory operations are performed relative |
| 119 | to a context. There are no absolute roots. |
| 120 | Therefore JNDI defines an <em>initial context</em>, |
| 121 | <tt>InitialContext</tt>, |
| 122 | which provides a starting point for naming and directory operations. |
| 123 | Once you have an initial context, you can use it to |
| 124 | look up other contexts and objects. |
| 125 | |
| 126 | <h4>Exceptions</h4> |
| 127 | |
| 128 | JNDI defines a class hierarchy for exceptions that can be thrown in |
| 129 | the course of performing naming and directory operations. The root of |
| 130 | this class hierarchy is <tt>NamingException</tt>. |
| 131 | Programs interested in dealing with a particular exception |
| 132 | can catch the corresponding subclass of the exception. |
| 133 | Otherwise, programs should catch <tt>NamingException</tt>. |
| 134 | |
| 135 | |
| 136 | <h2>Package Specification</h2> |
| 137 | |
| 138 | The JNDI API Specification and related documents can be found in the |
| 139 | <a href="../../../technotes/guides/jndi/index.html">JNDI documentation</a>. |
| 140 | |
| 141 | @since 1.3 |
| 142 | |
| 143 | </body> |
| 144 | </html> |