< prev index next >

src/java.naming/share/classes/javax/naming/Context.java

Print this page 





   1 /*
   2  * Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.naming;
  27 
  28 import java.util.Hashtable;
  29 
  30 /**
  31  * This interface represents a naming context, which
  32  * consists of a set of name-to-object bindings.
  33  * It contains methods for examining and updating these bindings.
  34  *
  35  * <h1>Names</h1>
  36  * Each name passed as an argument to a {@code Context} method is relative
  37  * to that context.  The empty name is used to name the context itself.
  38  * A name parameter may never be null.
  39  * <p>
  40  * Most of the methods have overloaded versions with one taking a
  41  * <code>Name</code> parameter and one taking a <code>String</code>.
  42  * These overloaded versions are equivalent in that if
  43  * the <code>Name</code> and <code>String</code> parameters are just
  44  * different representations of the same name, then the overloaded
  45  * versions of the same methods behave the same.
  46  * In the method descriptions below, only one version is fully documented.
  47  * The second version instead has a link to the first:  the same
  48  * documentation applies to both.
  49  * <p>
  50  * For systems that support federation, {@code String} name arguments to
  51  * {@code Context} methods are composite names. Name arguments that are
  52  * instances of {@code CompositeName} are treated as composite names,
  53  * while {@code Name} arguments that are not instances of
  54  * {@code CompositeName} are treated as compound names (which might be
  55  * instances of {@code CompoundName} or other implementations of compound
  56  * names). This allows the results of {@code NameParser.parse()} to be used as
  57  * arguments to the {@code Context} methods.
  58  * Prior to JNDI 1.2, all name arguments were treated as composite names.
  59  *<p>
  60  * Furthermore, for systems that support federation, all names returned
  61  * in a {@code NamingEnumeration}
  62  * from {@code list()} and {@code listBindings()} are composite names
  63  * represented as strings.
  64  * See {@code CompositeName} for the string syntax of names.
  65  *<p>
  66  * For systems that do not support federation, the name arguments (in
  67  * either {@code Name} or {@code String} forms) and the names returned in
  68  * {@code NamingEnumeration} may be names in their own namespace rather than
  69  * names in a composite namespace, at the discretion of the service
  70  * provider.
  71  *
  72  *<h1>Exceptions</h1>
  73  * All the methods in this interface can throw a {@code NamingException} or
  74  * any of its subclasses. See {@code NamingException} and their subclasses
  75  * for details on each exception.
  76  *
  77  *<h1>Concurrent Access</h1>
  78  * A Context instance is not guaranteed to be synchronized against
  79  * concurrent access by multiple threads.  Threads that need to access
  80  * a single Context instance concurrently should synchronize amongst
  81  * themselves and provide the necessary locking.  Multiple threads
  82  * each manipulating a different Context instance need not
  83  * synchronize.  Note that the {@link #lookup(Name) lookup}
  84  * method, when passed an empty name, will return a new Context instance
  85  * representing the same naming context.
  86  *<p>
  87  * For purposes of concurrency control,
  88  * a Context operation that returns a {@code NamingEnumeration} is
  89  * not considered to have completed while the enumeration is still in
  90  * use, or while any referrals generated by that operation are still
  91  * being followed.
  92  *
  93  *
  94  *<h1>Parameters</h1>
  95  * A {@code Name} parameter passed to any method of the
  96  * {@code Context} interface or one of its subinterfaces
  97  * will not be modified by the service provider.
  98  * The service provider may keep a reference to it
  99  * for the duration of the operation, including any enumeration of the
 100  * method's results and the processing of any referrals generated.
 101  * The caller should not modify the object during this time.
 102  * A {@code Name} returned by any such method is owned by the caller.
 103  * The caller may subsequently modify it; the service provider may not.
 104  *
 105  *
 106  *<h1>Environment Properties</h1>
 107  *<p>
 108  * JNDI applications need a way to communicate various preferences
 109  * and properties that define the environment in which naming and
 110  * directory services are accessed. For example, a context might
 111  * require specification of security credentials in order to access
 112  * the service. Another context might require that server configuration
 113  * information be supplied. These are referred to as the <em>environment</em>
 114  * of a context. The {@code Context} interface provides methods for
 115  * retrieving and updating this environment.
 116  *<p>
 117  * The environment is inherited from the parent context as
 118  * context methods proceed from one context to the next. Changes to
 119  * the environment of one context do not directly affect those
 120  * of other contexts.
 121  *<p>
 122  * It is implementation-dependent when environment properties are used
 123  * and/or verified for validity.  For example, some of the
 124  * security-related properties are used by service providers to "log in"
 125  * to the directory.  This login process might occur at the time the
 126  * context is created, or the first time a method is invoked on the
 127  * context.  When, and whether this occurs at all, is
 128  * implementation-dependent.  When environment properties are added or
 129  * removed from the context, verifying the validity of the changes is again
 130  * implementation-dependent. For example, verification of some properties
 131  * might occur at the time the change is made, or at the time the next
 132  * operation is performed on the context, or not at all.
 133  *<p>
 134  * Any object with a reference to a context may examine that context's
 135  * environment.  Sensitive information such as clear-text
 136  * passwords should not be stored there unless the implementation is
 137  * known to protect it.
 138  *
 139  *<p>
 140  *<a id=RESOURCEFILES></a>
 141  *<h1>Resource Files</h1>
 142  *<p>
 143  * To simplify the task of setting up the environment
 144  * required by a JNDI application,
 145  * application components and service providers may be distributed
 146  * along with <em>resource files.</em>
 147  * A JNDI resource file is a file in the properties file format (see
 148  * {@link java.util.Properties#load java.util.Properties}),
 149  * containing a list of key/value pairs.
 150  * The key is the name of the property (e.g. "java.naming.factory.object")
 151  * and the value is a string in the format defined
 152  * for that property.  Here is an example of a JNDI resource file:
 153  *
 154  * <blockquote>{@code
 155  * java.naming.factory.object=com.sun.jndi.ldap.AttrsToCorba:com.wiz.from.Person
 156  * java.naming.factory.state=com.sun.jndi.ldap.CorbaToAttrs:com.wiz.from.Person
 157  * java.naming.factory.control=com.sun.jndi.ldap.ResponseControlFactory
 158  * }</blockquote>
 159  *
 160  * The JNDI class library reads the resource files and makes the property
 161  * values freely available.  Thus JNDI resource files should be considered
 162  * to be "world readable", and sensitive information such as clear-text
 163  * passwords should not be stored there.
 164  *<p>
 165  * There are two kinds of JNDI resource files:
 166  * <em>provider</em> and <em>application</em>.
 167  *
 168  * <h2>Provider Resource Files</h2>
 169  *
 170  * Each service provider has an optional resource that lists properties
 171  * specific to that provider.  The name of this resource is:
 172  * <blockquote>
 173  * [<em>prefix</em>/]{@code jndiprovider.properties}
 174  * </blockquote>
 175  * where <em>prefix</em> is
 176  * the package name of the provider's context implementation(s),
 177  * with each period (".") converted to a slash ("/").
 178  *
 179  * For example, suppose a service provider defines a context
 180  * implementation with class name {@code com.sun.jndi.ldap.LdapCtx}.
 181  * The provider resource for this provider is named
 182  * {@code com/sun/jndi/ldap/jndiprovider.properties}.  If the class is
 183  * not in a package, the resource's name is simply
 184  * {@code jndiprovider.properties}.
 185  *
 186  * <p>
 187  * <a id=LISTPROPS></a>
 188  * Certain methods in the JNDI class library make use of the standard
 189  * JNDI properties that specify lists of JNDI factories:
 190  * <ul>
 191  * <li>java.naming.factory.object
 192  * <li>java.naming.factory.state
 193  * <li>java.naming.factory.control
 194  * <li>java.naming.factory.url.pkgs
 195  * </ul>
 196  * The JNDI library will consult the provider resource file
 197  * when determining the values of these properties.
 198  * Properties other than these may be set in the provider
 199  * resource file at the discretion of the service provider.
 200  * The service provider's documentation should clearly state which
 201  * properties are allowed; other properties in the file will be ignored.
 202  *
 203  * <h2>Application Resource Files</h2>
 204  *
 205  * When an application is deployed, it will generally have several
 206  * codebase directories and JARs in its classpath. JNDI locates (using
 207  * {@link ClassLoader#getResources ClassLoader.getResources()})
 208  * all <em>application resource files</em> named {@code jndi.properties}
 209  * in the classpath.
 210  * In addition, if the Java installation directory contains a built-in
 211  * properties file, typically {@code conf/jndi.properties},
 212  * JNDI treats it as an additional application resource file.
 213  * All of the properties contained in these files are placed
 214  * into the environment of the initial context.  This environment
 215  * is then inherited by other contexts.
 216  *
 217  * <p>
 218  * For each property found in more than one application resource file,
 219  * JNDI uses the first value found or, in a few cases where it makes
 220  * sense to do so, it concatenates all of the values (details are given
 221  * below).
 222  * For example, if the "java.naming.factory.object" property is found in
 223  * three {@code jndi.properties} resource files, the
 224  * list of object factories is a concatenation of the property
 225  * values from all three files.
 226  * Using this scheme, each deployable component is responsible for
 227  * listing the factories that it exports.  JNDI automatically
 228  * collects and uses all of these export lists when searching for factory
 229  * classes.
 230  *
 231  * <h2>Search Algorithm for Properties</h2>
 232  *
 233  * When JNDI constructs an initial context, the context's environment
 234  * is initialized with properties defined in the environment parameter
 235  * passed to the constructor, the system properties,
 236  * and the application resource files.  See
 237  * <a href=InitialContext.html#ENVIRONMENT>{@code InitialContext}</a>
 238  * for details.
 239  * This initial environment is then inherited by other context instances.
 240  *
 241  * <p>
 242  * When the JNDI class library needs to determine
 243  * the value of a property, it does so by merging
 244  * the values from the following two sources, in order:
 245  * <ol>
 246  * <li>The environment of the context being operated on.
 247  * <li>The provider resource file ({@code jndiprovider.properties})
 248  * for the context being operated on.
 249  * </ol>
 250  * For each property found in both of these two sources,
 251  * JNDI determines the property's value as follows.  If the property is




   1 /*
   2  * Copyright (c) 1999, 2019, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.naming;
  27 
  28 import java.util.Hashtable;
  29 
  30 /**
  31  * This interface represents a naming context, which
  32  * consists of a set of name-to-object bindings.
  33  * It contains methods for examining and updating these bindings.
  34  *
  35  * <h2>Names</h2>
  36  * Each name passed as an argument to a {@code Context} method is relative
  37  * to that context.  The empty name is used to name the context itself.
  38  * A name parameter may never be null.
  39  * <p>
  40  * Most of the methods have overloaded versions with one taking a
  41  * <code>Name</code> parameter and one taking a <code>String</code>.
  42  * These overloaded versions are equivalent in that if
  43  * the <code>Name</code> and <code>String</code> parameters are just
  44  * different representations of the same name, then the overloaded
  45  * versions of the same methods behave the same.
  46  * In the method descriptions below, only one version is fully documented.
  47  * The second version instead has a link to the first:  the same
  48  * documentation applies to both.
  49  * <p>
  50  * For systems that support federation, {@code String} name arguments to
  51  * {@code Context} methods are composite names. Name arguments that are
  52  * instances of {@code CompositeName} are treated as composite names,
  53  * while {@code Name} arguments that are not instances of
  54  * {@code CompositeName} are treated as compound names (which might be
  55  * instances of {@code CompoundName} or other implementations of compound
  56  * names). This allows the results of {@code NameParser.parse()} to be used as
  57  * arguments to the {@code Context} methods.
  58  * Prior to JNDI 1.2, all name arguments were treated as composite names.
  59  *<p>
  60  * Furthermore, for systems that support federation, all names returned
  61  * in a {@code NamingEnumeration}
  62  * from {@code list()} and {@code listBindings()} are composite names
  63  * represented as strings.
  64  * See {@code CompositeName} for the string syntax of names.
  65  *<p>
  66  * For systems that do not support federation, the name arguments (in
  67  * either {@code Name} or {@code String} forms) and the names returned in
  68  * {@code NamingEnumeration} may be names in their own namespace rather than
  69  * names in a composite namespace, at the discretion of the service
  70  * provider.
  71  *
  72  *<h2>Exceptions</h2>
  73  * All the methods in this interface can throw a {@code NamingException} or
  74  * any of its subclasses. See {@code NamingException} and their subclasses
  75  * for details on each exception.
  76  *
  77  *<h2>Concurrent Access</h2>
  78  * A Context instance is not guaranteed to be synchronized against
  79  * concurrent access by multiple threads.  Threads that need to access
  80  * a single Context instance concurrently should synchronize amongst
  81  * themselves and provide the necessary locking.  Multiple threads
  82  * each manipulating a different Context instance need not
  83  * synchronize.  Note that the {@link #lookup(Name) lookup}
  84  * method, when passed an empty name, will return a new Context instance
  85  * representing the same naming context.
  86  *<p>
  87  * For purposes of concurrency control,
  88  * a Context operation that returns a {@code NamingEnumeration} is
  89  * not considered to have completed while the enumeration is still in
  90  * use, or while any referrals generated by that operation are still
  91  * being followed.
  92  *
  93  *
  94  *<h2>Parameters</h2>
  95  * A {@code Name} parameter passed to any method of the
  96  * {@code Context} interface or one of its subinterfaces
  97  * will not be modified by the service provider.
  98  * The service provider may keep a reference to it
  99  * for the duration of the operation, including any enumeration of the
 100  * method's results and the processing of any referrals generated.
 101  * The caller should not modify the object during this time.
 102  * A {@code Name} returned by any such method is owned by the caller.
 103  * The caller may subsequently modify it; the service provider may not.
 104  *
 105  *
 106  *<h2>Environment Properties</h2>
 107  *<p>
 108  * JNDI applications need a way to communicate various preferences
 109  * and properties that define the environment in which naming and
 110  * directory services are accessed. For example, a context might
 111  * require specification of security credentials in order to access
 112  * the service. Another context might require that server configuration
 113  * information be supplied. These are referred to as the <em>environment</em>
 114  * of a context. The {@code Context} interface provides methods for
 115  * retrieving and updating this environment.
 116  *<p>
 117  * The environment is inherited from the parent context as
 118  * context methods proceed from one context to the next. Changes to
 119  * the environment of one context do not directly affect those
 120  * of other contexts.
 121  *<p>
 122  * It is implementation-dependent when environment properties are used
 123  * and/or verified for validity.  For example, some of the
 124  * security-related properties are used by service providers to "log in"
 125  * to the directory.  This login process might occur at the time the
 126  * context is created, or the first time a method is invoked on the
 127  * context.  When, and whether this occurs at all, is
 128  * implementation-dependent.  When environment properties are added or
 129  * removed from the context, verifying the validity of the changes is again
 130  * implementation-dependent. For example, verification of some properties
 131  * might occur at the time the change is made, or at the time the next
 132  * operation is performed on the context, or not at all.
 133  *<p>
 134  * Any object with a reference to a context may examine that context's
 135  * environment.  Sensitive information such as clear-text
 136  * passwords should not be stored there unless the implementation is
 137  * known to protect it.
 138  *
 139  *<p>
 140  *<a id=RESOURCEFILES></a>
 141  *<h2>Resource Files</h2>
 142  *<p>
 143  * To simplify the task of setting up the environment
 144  * required by a JNDI application,
 145  * application components and service providers may be distributed
 146  * along with <em>resource files.</em>
 147  * A JNDI resource file is a file in the properties file format (see
 148  * {@link java.util.Properties#load java.util.Properties}),
 149  * containing a list of key/value pairs.
 150  * The key is the name of the property (e.g. "java.naming.factory.object")
 151  * and the value is a string in the format defined
 152  * for that property.  Here is an example of a JNDI resource file:
 153  *
 154  * <blockquote>{@code
 155  * java.naming.factory.object=com.sun.jndi.ldap.AttrsToCorba:com.wiz.from.Person
 156  * java.naming.factory.state=com.sun.jndi.ldap.CorbaToAttrs:com.wiz.from.Person
 157  * java.naming.factory.control=com.sun.jndi.ldap.ResponseControlFactory
 158  * }</blockquote>
 159  *
 160  * The JNDI class library reads the resource files and makes the property
 161  * values freely available.  Thus JNDI resource files should be considered
 162  * to be "world readable", and sensitive information such as clear-text
 163  * passwords should not be stored there.
 164  *<p>
 165  * There are two kinds of JNDI resource files:
 166  * <em>provider</em> and <em>application</em>.
 167  *
 168  * <h3>Provider Resource Files</h3>
 169  *
 170  * Each service provider has an optional resource that lists properties
 171  * specific to that provider.  The name of this resource is:
 172  * <blockquote>
 173  * [<em>prefix</em>/]{@code jndiprovider.properties}
 174  * </blockquote>
 175  * where <em>prefix</em> is
 176  * the package name of the provider's context implementation(s),
 177  * with each period (".") converted to a slash ("/").
 178  *
 179  * For example, suppose a service provider defines a context
 180  * implementation with class name {@code com.sun.jndi.ldap.LdapCtx}.
 181  * The provider resource for this provider is named
 182  * {@code com/sun/jndi/ldap/jndiprovider.properties}.  If the class is
 183  * not in a package, the resource's name is simply
 184  * {@code jndiprovider.properties}.
 185  *
 186  * <p>
 187  * <a id=LISTPROPS></a>
 188  * Certain methods in the JNDI class library make use of the standard
 189  * JNDI properties that specify lists of JNDI factories:
 190  * <ul>
 191  * <li>java.naming.factory.object
 192  * <li>java.naming.factory.state
 193  * <li>java.naming.factory.control
 194  * <li>java.naming.factory.url.pkgs
 195  * </ul>
 196  * The JNDI library will consult the provider resource file
 197  * when determining the values of these properties.
 198  * Properties other than these may be set in the provider
 199  * resource file at the discretion of the service provider.
 200  * The service provider's documentation should clearly state which
 201  * properties are allowed; other properties in the file will be ignored.
 202  *
 203  * <h3>Application Resource Files</h3>
 204  *
 205  * When an application is deployed, it will generally have several
 206  * codebase directories and JARs in its classpath. JNDI locates (using
 207  * {@link ClassLoader#getResources ClassLoader.getResources()})
 208  * all <em>application resource files</em> named {@code jndi.properties}
 209  * in the classpath.
 210  * In addition, if the Java installation directory contains a built-in
 211  * properties file, typically {@code conf/jndi.properties},
 212  * JNDI treats it as an additional application resource file.
 213  * All of the properties contained in these files are placed
 214  * into the environment of the initial context.  This environment
 215  * is then inherited by other contexts.
 216  *
 217  * <p>
 218  * For each property found in more than one application resource file,
 219  * JNDI uses the first value found or, in a few cases where it makes
 220  * sense to do so, it concatenates all of the values (details are given
 221  * below).
 222  * For example, if the "java.naming.factory.object" property is found in
 223  * three {@code jndi.properties} resource files, the
 224  * list of object factories is a concatenation of the property
 225  * values from all three files.
 226  * Using this scheme, each deployable component is responsible for
 227  * listing the factories that it exports.  JNDI automatically
 228  * collects and uses all of these export lists when searching for factory
 229  * classes.
 230  *
 231  * <h3>Search Algorithm for Properties</h3>
 232  *
 233  * When JNDI constructs an initial context, the context's environment
 234  * is initialized with properties defined in the environment parameter
 235  * passed to the constructor, the system properties,
 236  * and the application resource files.  See
 237  * <a href=InitialContext.html#ENVIRONMENT>{@code InitialContext}</a>
 238  * for details.
 239  * This initial environment is then inherited by other context instances.
 240  *
 241  * <p>
 242  * When the JNDI class library needs to determine
 243  * the value of a property, it does so by merging
 244  * the values from the following two sources, in order:
 245  * <ol>
 246  * <li>The environment of the context being operated on.
 247  * <li>The provider resource file ({@code jndiprovider.properties})
 248  * for the context being operated on.
 249  * </ol>
 250  * For each property found in both of these two sources,
 251  * JNDI determines the property's value as follows.  If the property is







< prev index next >