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

@@ -31,11 +31,11 @@
  * This interface represents a naming context, which
  * consists of a set of name-to-object bindings.
  * It contains methods for examining and updating these bindings.
  *
  * <h1>Names</h1>
- * Each name passed as an argument to a <tt>Context</tt> method is relative
+ * Each name passed as an argument to a {@code Context} method is relative
  * to that context.  The empty name is used to name the context itself.
  * A name parameter may never be null.
  * <p>
  * Most of the methods have overloaded versions with one taking a
  * <code>Name</code> parameter and one taking a <code>String</code>.

@@ -45,63 +45,63 @@
  * versions of the same methods behave the same.
  * In the method descriptions below, only one version is fully documented.
  * The second version instead has a link to the first:  the same
  * documentation applies to both.
  * <p>
- * For systems that support federation, <tt>String</tt> name arguments to
- * <tt>Context</tt> methods are composite names. Name arguments that are
- * instances of <tt>CompositeName</tt> are treated as composite names,
- * while <tt>Name</tt> arguments that are not instances of
- * <tt>CompositeName</tt> are treated as compound names (which might be
- * instances of <tt>CompoundName</tt> or other implementations of compound
- * names). This allows the results of <tt>NameParser.parse()</tt> to be used as
- * arguments to the <tt>Context</tt> methods.
+ * For systems that support federation, {@code String} name arguments to
+ * {@code Context} methods are composite names. Name arguments that are
+ * instances of {@code CompositeName} are treated as composite names,
+ * while {@code Name} arguments that are not instances of
+ * {@code CompositeName} are treated as compound names (which might be
+ * instances of {@code CompoundName} or other implementations of compound
+ * names). This allows the results of {@code NameParser.parse()} to be used as
+ * arguments to the {@code Context} methods.
  * Prior to JNDI 1.2, all name arguments were treated as composite names.
  *<p>
  * Furthermore, for systems that support federation, all names returned
- * in a <tt>NamingEnumeration</tt>
- * from <tt>list()</tt> and <tt>listBindings()</tt> are composite names
+ * in a {@code NamingEnumeration}
+ * from {@code list()} and {@code listBindings()} are composite names
  * represented as strings.
- * See <tt>CompositeName</tt> for the string syntax of names.
+ * See {@code CompositeName} for the string syntax of names.
  *<p>
  * For systems that do not support federation, the name arguments (in
- * either <tt>Name</tt> or <tt>String</tt> forms) and the names returned in
- * <tt>NamingEnumeration</tt> may be names in their own namespace rather than
+ * either {@code Name} or {@code String} forms) and the names returned in
+ * {@code NamingEnumeration} may be names in their own namespace rather than
  * names in a composite namespace, at the discretion of the service
  * provider.
  *
  *<h1>Exceptions</h1>
- * All the methods in this interface can throw a <tt>NamingException</tt> or
- * any of its subclasses. See <tt>NamingException</tt> and their subclasses
+ * All the methods in this interface can throw a {@code NamingException} or
+ * any of its subclasses. See {@code NamingException} and their subclasses
  * for details on each exception.
  *
  *<h1>Concurrent Access</h1>
  * A Context instance is not guaranteed to be synchronized against
  * concurrent access by multiple threads.  Threads that need to access
  * a single Context instance concurrently should synchronize amongst
  * themselves and provide the necessary locking.  Multiple threads
  * each manipulating a different Context instance need not
- * synchronize.  Note that the {@link #lookup(Name) <tt>lookup</tt>}
+ * synchronize.  Note that the {@link #lookup(Name) lookup}
  * method, when passed an empty name, will return a new Context instance
  * representing the same naming context.
  *<p>
  * For purposes of concurrency control,
- * a Context operation that returns a <tt>NamingEnumeration</tt> is
+ * a Context operation that returns a {@code NamingEnumeration} is
  * not considered to have completed while the enumeration is still in
  * use, or while any referrals generated by that operation are still
  * being followed.
  *
  *
  *<h1>Parameters</h1>
- * A <tt>Name</tt> parameter passed to any method of the
- * <tt>Context</tt> interface or one of its subinterfaces
+ * A {@code Name} parameter passed to any method of the
+ * {@code Context} interface or one of its subinterfaces
  * will not be modified by the service provider.
  * The service provider may keep a reference to it
  * for the duration of the operation, including any enumeration of the
  * method's results and the processing of any referrals generated.
  * The caller should not modify the object during this time.
- * A <tt>Name</tt> returned by any such method is owned by the caller.
+ * A {@code Name} returned by any such method is owned by the caller.
  * The caller may subsequently modify it; the service provider may not.
  *
  *
  *<h1>Environment Properties</h1>
  *<p>

@@ -109,11 +109,11 @@
  * and properties that define the environment in which naming and
  * directory services are accessed. For example, a context might
  * require specification of security credentials in order to access
  * the service. Another context might require that server configuration
  * information be supplied. These are referred to as the <em>environment</em>
- * of a context. The <tt>Context</tt> interface provides methods for
+ * of a context. The {@code Context} interface provides methods for
  * retrieving and updating this environment.
  *<p>
  * The environment is inherited from the parent context as
  * context methods proceed from one context to the next. Changes to
  * the environment of one context do not directly affect those

@@ -143,11 +143,11 @@
  * To simplify the task of setting up the environment
  * required by a JNDI application,
  * application components and service providers may be distributed
  * along with <em>resource files.</em>
  * A JNDI resource file is a file in the properties file format (see
- * {@link java.util.Properties#load <tt>java.util.Properties</tt>}),
+ * {@link java.util.Properties#load java.util.Properties}),
  * containing a list of key/value pairs.
  * The key is the name of the property (e.g. "java.naming.factory.object")
  * and the value is a string in the format defined
  * for that property.  Here is an example of a JNDI resource file:
  *

@@ -168,22 +168,22 @@
  * <h2>Provider Resource Files</h2>
  *
  * Each service provider has an optional resource that lists properties
  * specific to that provider.  The name of this resource is:
  * <blockquote>
- * [<em>prefix</em>/]<tt>jndiprovider.properties</tt>
+ * [<em>prefix</em>/]{@code jndiprovider.properties}
  * </blockquote>
  * where <em>prefix</em> is
  * the package name of the provider's context implementation(s),
  * with each period (".") converted to a slash ("/").
  *
  * For example, suppose a service provider defines a context
- * implementation with class name <tt>com.sun.jndi.ldap.LdapCtx</tt>.
+ * implementation with class name {@code com.sun.jndi.ldap.LdapCtx}.
  * The provider resource for this provider is named
- * <tt>com/sun/jndi/ldap/jndiprovider.properties</tt>.  If the class is
+ * {@code com/sun/jndi/ldap/jndiprovider.properties}.  If the class is
  * not in a package, the resource's name is simply
- * <tt>jndiprovider.properties</tt>.
+ * {@code jndiprovider.properties}.
  *
  * <p>
  * <a name=LISTPROPS></a>
  * Certain methods in the JNDI class library make use of the standard
  * JNDI properties that specify lists of JNDI factories:

@@ -202,15 +202,15 @@
  *
  * <h2>Application Resource Files</h2>
  *
  * When an application is deployed, it will generally have several
  * codebase directories and JARs in its classpath. JNDI locates (using
- * {@link ClassLoader#getResources <tt>ClassLoader.getResources()</tt>})
- * all <em>application resource files</em> named <tt>jndi.properties</tt>
+ * {@link ClassLoader#getResources ClassLoader.getResources()})
+ * all <em>application resource files</em> named {@code jndi.properties}
  * in the classpath.
  * In addition, if the Java installation directory contains a built-in
- * properties file, typically <tt>conf/jndi.properties</tt>,
+ * properties file, typically {@code conf/jndi.properties},
  * JNDI treats it as an additional application resource file.
  * All of the properties contained in these files are placed
  * into the environment of the initial context.  This environment
  * is then inherited by other contexts.
  *

@@ -218,11 +218,11 @@
  * For each property found in more than one application resource file,
  * JNDI uses the first value found or, in a few cases where it makes
  * sense to do so, it concatenates all of the values (details are given
  * below).
  * For example, if the "java.naming.factory.object" property is found in
- * three <tt>jndi.properties</tt> resource files, the
+ * three {@code jndi.properties} resource files, the
  * list of object factories is a concatenation of the property
  * values from all three files.
  * Using this scheme, each deployable component is responsible for
  * listing the factories that it exports.  JNDI automatically
  * collects and uses all of these export lists when searching for factory

@@ -232,21 +232,21 @@
  *
  * When JNDI constructs an initial context, the context's environment
  * is initialized with properties defined in the environment parameter
  * passed to the constructor, the system properties,
  * and the application resource files.  See
- * <a href=InitialContext.html#ENVIRONMENT><tt>InitialContext</tt></a>
+ * <a href=InitialContext.html#ENVIRONMENT>{@code InitialContext}</a>
  * for details.
  * This initial environment is then inherited by other context instances.
  *
  * <p>
  * When the JNDI class library needs to determine
  * the value of a property, it does so by merging
  * the values from the following two sources, in order:
  * <ol>
  * <li>The environment of the context being operated on.
- * <li>The provider resource file (<tt>jndiprovider.properties</tt>)
+ * <li>The provider resource file ({@code jndiprovider.properties})
  * for the context being operated on.
  * </ol>
  * For each property found in both of these two sources,
  * JNDI determines the property's value as follows.  If the property is
  * one of the standard JNDI properties that specify a list of JNDI

@@ -276,18 +276,18 @@
 
 public interface Context {
 
     /**
      * Retrieves the named object.
-     * If <tt>name</tt> is empty, returns a new instance of this context
+     * If {@code name} is empty, returns a new instance of this context
      * (which represents the same naming context as this context, but its
      * environment may be modified independently and it may be accessed
      * concurrently).
      *
      * @param name
      *          the name of the object to look up
-     * @return  the object bound to <tt>name</tt>
+     * @return  the object bound to {@code name}
      * @throws  NamingException if a naming exception is encountered
      *
      * @see #lookup(String)
      * @see #lookupLink(Name)
      */

@@ -296,11 +296,11 @@
     /**
      * Retrieves the named object.
      * See {@link #lookup(Name)} for details.
      * @param name
      *          the name of the object to look up
-     * @return  the object bound to <tt>name</tt>
+     * @return  the object bound to {@code name}
      * @throws  NamingException if a naming exception is encountered
      */
     public Object lookup(String name) throws NamingException;
 
     /**

@@ -342,11 +342,11 @@
     /**
      * Binds a name to an object, overwriting any existing binding.
      * All intermediate contexts and the target context (that named by all
      * but terminal atomic component of the name) must already exist.
      *
-     * <p> If the object is a <tt>DirContext</tt>, any existing attributes
+     * <p> If the object is a {@code DirContext}, any existing attributes
      * associated with the name are replaced with those of the object.
      * Otherwise, any existing attributes associated with the name remain
      * unchanged.
      *
      * @param name

@@ -386,11 +386,11 @@
      * atomic part of <code>name</code>.
      *
      * <p> This method is idempotent.
      * It succeeds even if the terminal atomic name
      * is not bound in the target context, but throws
-     * <tt>NameNotFoundException</tt>
+     * {@code NameNotFoundException}
      * if any of the intermediate contexts do not exist.
      *
      * <p> Any attributes associated with the name are removed.
      * Intermediate contexts are not changed.
      *

@@ -422,11 +422,11 @@
      *
      * @param oldName
      *          the name of the existing binding; may not be empty
      * @param newName
      *          the name of the new binding; may not be empty
-     * @throws  NameAlreadyBoundException if <tt>newName</tt> is already bound
+     * @throws  NameAlreadyBoundException if {@code newName} is already bound
      * @throws  NamingException if a naming exception is encountered
      *
      * @see #rename(String, String)
      * @see #bind(Name, Object)
      * @see #rebind(Name, Object)

@@ -440,11 +440,11 @@
      *
      * @param oldName
      *          the name of the existing binding; may not be empty
      * @param newName
      *          the name of the new binding; may not be empty
-     * @throws  NameAlreadyBoundException if <tt>newName</tt> is already bound
+     * @throws  NameAlreadyBoundException if {@code newName} is already bound
      * @throws  NamingException if a naming exception is encountered
      */
     public void rename(String oldName, String newName) throws NamingException;
 
     /**

@@ -457,11 +457,11 @@
      *
      * @param name
      *          the name of the context to list
      * @return  an enumeration of the names and class names of the
      *          bindings in this context.  Each element of the
-     *          enumeration is of type <tt>NameClassPair</tt>.
+     *          enumeration is of type {@code NameClassPair}.
      * @throws  NamingException if a naming exception is encountered
      *
      * @see #list(String)
      * @see #listBindings(Name)
      * @see NameClassPair

@@ -476,11 +476,11 @@
      *
      * @param name
      *          the name of the context to list
      * @return  an enumeration of the names and class names of the
      *          bindings in this context.  Each element of the
-     *          enumeration is of type <tt>NameClassPair</tt>.
+     *          enumeration is of type {@code NameClassPair}.
      * @throws  NamingException if a naming exception is encountered
      */
     public NamingEnumeration<NameClassPair> list(String name)
         throws NamingException;
 

@@ -494,11 +494,11 @@
      *
      * @param name
      *          the name of the context to list
      * @return  an enumeration of the bindings in this context.
      *          Each element of the enumeration is of type
-     *          <tt>Binding</tt>.
+     *          {@code Binding}.
      * @throws  NamingException if a naming exception is encountered
      *
      * @see #listBindings(String)
      * @see #list(Name)
      * @see Binding

@@ -513,11 +513,11 @@
      *
      * @param name
      *          the name of the context to list
      * @return  an enumeration of the bindings in this context.
      *          Each element of the enumeration is of type
-     *          <tt>Binding</tt>.
+     *          {@code Binding}.
      * @throws  NamingException if a naming exception is encountered
      */
     public NamingEnumeration<Binding> listBindings(String name)
         throws NamingException;
 

@@ -527,23 +527,23 @@
      * Intermediate contexts are not destroyed.
      *
      * <p> This method is idempotent.
      * It succeeds even if the terminal atomic name
      * is not bound in the target context, but throws
-     * <tt>NameNotFoundException</tt>
+     * {@code NameNotFoundException}
      * if any of the intermediate contexts do not exist.
      *
      * <p> In a federated naming system, a context from one naming system
      * may be bound to a name in another.  One can subsequently
      * look up and perform operations on the foreign context using a
      * composite name.  However, an attempt destroy the context using
      * this composite name will fail with
-     * <tt>NotContextException</tt>, because the foreign context is not
+     * {@code NotContextException}, because the foreign context is not
      * a "subcontext" of the context in which it is bound.
-     * Instead, use <tt>unbind()</tt> to remove the
+     * Instead, use {@code unbind()} to remove the
      * binding of the foreign context.  Destroying the foreign context
-     * requires that the <tt>destroySubcontext()</tt> be performed
+     * requires that the {@code destroySubcontext()} be performed
      * on a context from the foreign context's "native" naming system.
      *
      * @param name
      *          the name of the context to be destroyed; may not be empty
      * @throws  NameNotFoundException if an intermediate context does not exist

@@ -609,16 +609,16 @@
     public Context createSubcontext(String name) throws NamingException;
 
     /**
      * Retrieves the named object, following links except
      * for the terminal atomic component of the name.
-     * If the object bound to <tt>name</tt> is not a link,
+     * If the object bound to {@code name} is not a link,
      * returns the object itself.
      *
      * @param name
      *          the name of the object to look up
-     * @return  the object bound to <tt>name</tt>, not following the
+     * @return  the object bound to {@code name}, not following the
      *          terminal link (if any).
      * @throws  NamingException if a naming exception is encountered
      *
      * @see #lookupLink(String)
      */

@@ -629,11 +629,11 @@
      * for the terminal atomic component of the name.
      * See {@link #lookupLink(Name)} for details.
      *
      * @param name
      *          the name of the object to look up
-     * @return  the object bound to <tt>name</tt>, not following the
+     * @return  the object bound to {@code name}, not following the
      *          terminal link (if any)
      * @throws  NamingException if a naming exception is encountered
      */
     public Object lookupLink(String name) throws NamingException;
 

@@ -641,12 +641,12 @@
      * Retrieves the parser associated with the named context.
      * In a federation of namespaces, different naming systems will
      * parse names differently.  This method allows an application
      * to get a parser for parsing names into their atomic components
      * using the naming convention of a particular naming system.
-     * Within any single naming system, <tt>NameParser</tt> objects
-     * returned by this method must be equal (using the <tt>equals()</tt>
+     * Within any single naming system, {@code NameParser} objects
+     * returned by this method must be equal (using the {@code equals()}
      * test).
      *
      * @param name
      *          the name of the context from which to get the parser
      * @return  a name parser that can parse compound names into their atomic

@@ -763,11 +763,11 @@
      * See class description for more details on environment properties.
      *
      * <p> The caller should not make any changes to the object returned:
      * their effect on the context is undefined.
      * The environment of this context may be changed using
-     * <tt>addToEnvironment()</tt> and <tt>removeFromEnvironment()</tt>.
+     * {@code addToEnvironment()} and {@code removeFromEnvironment()}.
      *
      * @return  the environment of this context; never null
      * @throws  NamingException if a naming exception is encountered
      *
      * @see #addToEnvironment(String, Object)

@@ -796,11 +796,11 @@
      * a distinguished name, and a DNS record has a fully qualified name.
      * This method allows the client application to retrieve this name.
      * The string returned by this method is not a JNDI composite name
      * and should not be passed directly to context methods.
      * In naming systems for which the notion of full name does not
-     * make sense, <tt>OperationNotSupportedException</tt> is thrown.
+     * make sense, {@code OperationNotSupportedException} is thrown.
      *
      * @return  this context's name in its own namespace; never null
      * @throws  OperationNotSupportedException if the naming system does
      *          not have the notion of a full name
      * @throws  NamingException if a naming exception is encountered

@@ -819,11 +819,11 @@
      * of the factory class that will create an initial context.
      * This property may be specified in the environment parameter
      * passed to the initial context constructor,
      * a system property, or an application resource file.
      * If it is not specified in any of these sources,
-     * <tt>NoInitialContextException</tt> is thrown when an initial
+     * {@code NoInitialContextException} is thrown when an initial
      * context is required to complete an operation.
      *
      * <p> The value of this constant is "java.naming.factory.initial".
      *
      * @see InitialContext

@@ -880,11 +880,11 @@
      * of the property should be a colon-separated list of package
      * prefixes for the class name of the factory class that will create
      * a URL context factory.
      * This property may be specified in the environment, a system property,
      * or one or more resource files.
-     * The prefix <tt>com.sun.jndi.url</tt> is always appended to
+     * The prefix {@code com.sun.jndi.url} is always appended to
      * the possibly empty list of package prefixes.
      *
      * <p> The value of this constant is "java.naming.factory.url.pkgs".
      *
      * @see javax.naming.spi.NamingManager#getObjectInstance

@@ -918,11 +918,11 @@
      * JNDI URL context (for example, "dns://somehost/wiz.com").
      * This property may be specified in the environment, a system property,
      * or a resource file.
      * If it is not specified in any of these sources
      * and the program attempts to use a JNDI URL containing a DNS name,
-     * a <tt>ConfigurationException</tt> will be thrown.
+     * a {@code ConfigurationException} will be thrown.
      *
      * <p> The value of this constant is "java.naming.dns.url".
      *
      * @see #addToEnvironment(String, Object)
      * @see #removeFromEnvironment(String)

@@ -972,11 +972,11 @@
      * <dt>"follow"
      * <dd>follow referrals automatically
      * <dt>"ignore"
      * <dd>ignore referrals
      * <dt>"throw"
-     * <dd>throw <tt>ReferralException</tt> when a referral is encountered.
+     * <dd>throw {@code ReferralException} when a referral is encountered.
      * </dl>
      * If this property is not specified, the default is
      * determined by the provider.
      *
      * <p> The value of this constant is "java.naming.referral".