stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

8132877: docs: replace <tt> tags (obsolete in html5) for javax.naming

Browse Source 
Reviewed-by: lancea, dfuchs
This commit is contained in:
Alexander Stepanov 2015-08-05 13:40:18 +03:00
parent ddb63861a3
commit ff767bf9f9
58 changed files with 931 additions and 931 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
jdk/src/java.naming/share/classes/com/sun/naming/internal/ResourceManager.java
View File

@ -137,7 +137,7 @@ public final class ResourceManager {
* context (never null). This is based on the environment
* parameter, the system properties, and all application resource files.
*
* <p> This method will modify <tt>env</tt> and save
* <p> This method will modify {@code env} and save
* a reference to it. The caller may no longer modify it.
*
* @param env environment passed to initial context constructor.
@ -195,7 +195,7 @@ public final class ResourceManager {
* may in turn contain values that come from system properties,
* or application resource files.
*
* If <tt>concat</tt> is true and both the environment and the provider
* If {@code concat} is true and both the environment and the provider
* resource file contain the property, the two values are concatenated
* (with a ':' separator).
*

26
jdk/src/java.naming/share/classes/javax/naming/Binding.java
View File

@ -49,7 +49,7 @@ public class Binding extends NameClassPair {
/**
* Contains this binding's object.
* It is initialized by the constructor and can be updated using
* <tt>setObject</tt>.
* {@code setObject}.
* @serial
* @see #getObject
* @see #setObject
@ -59,9 +59,9 @@ public class Binding extends NameClassPair {
/**
* Constructs an instance of a Binding given its name and object.
*<p>
* <tt>getClassName()</tt> will return
* the class name of <tt>obj</tt> (or null if <tt>obj</tt> is null)
* unless the class name has been explicitly set using <tt>setClassName()</tt>
* {@code getClassName()} will return
* the class name of {@code obj} (or null if {@code obj} is null)
* unless the class name has been explicitly set using {@code setClassName()}
*
* @param name The non-null name of the object. It is relative
* to the <em>target context</em> (which is
@ -78,9 +78,9 @@ public class Binding extends NameClassPair {
* Constructs an instance of a Binding given its name, object, and whether
* the name is relative.
*<p>
* <tt>getClassName()</tt> will return the class name of <tt>obj</tt>
* (or null if <tt>obj</tt> is null) unless the class name has been
* explicitly set using <tt>setClassName()</tt>
* {@code getClassName()} will return the class name of {@code obj}
* (or null if {@code obj} is null) unless the class name has been
* explicitly set using {@code setClassName()}
*
* @param name The non-null string name of the object.
* @param obj The possibly null object bound to name.
@ -104,9 +104,9 @@ public class Binding extends NameClassPair {
* to the <em>target context</em> (which is
* named by the first parameter of the <code>listBindings()</code> method)
* @param className The possibly null class name of the object
* bound to <tt>name</tt>. If null, the class name of <tt>obj</tt> is
* returned by <tt>getClassName()</tt>. If <tt>obj</tt> is also
* null, <tt>getClassName()</tt> will return null.
* bound to {@code name}. If null, the class name of {@code obj} is
* returned by {@code getClassName()}. If {@code obj} is also
* null, {@code getClassName()} will return null.
* @param obj The possibly null object bound to name.
* @see NameClassPair#setClassName
*/
@ -121,9 +121,9 @@ public class Binding extends NameClassPair {
*
* @param name The non-null string name of the object.
* @param className The possibly null class name of the object
* bound to <tt>name</tt>. If null, the class name of <tt>obj</tt> is
* returned by <tt>getClassName()</tt>. If <tt>obj</tt> is also
* null, <tt>getClassName()</tt> will return null.
* bound to {@code name}. If null, the class name of {@code obj} is
* returned by {@code getClassName()}. If {@code obj} is also
* null, {@code getClassName()} will return null.
* @param obj The possibly null object bound to name.
* @param isRelative true if <code>name</code> is a name relative
* to the target context (which is named by

40
jdk/src/java.naming/share/classes/javax/naming/CannotProceedException.java
View File

@ -93,9 +93,9 @@ public class CannotProceedException extends NamingException {
/**
* Contains the name of the resolved object, relative
* to the context <code>altNameCtx</code>. It is a composite name.
* to the context {@code altNameCtx}. It is a composite name.
* If null, then no name is specified.
* See the <code>javax.naming.spi.ObjectFactory.getObjectInstance</code>
* See the {@code javax.naming.spi.ObjectFactory.getObjectInstance}
* method for details on how this is used.
* <p>
* This field is initialized to null.
@ -112,9 +112,9 @@ public class CannotProceedException extends NamingException {
/**
* Contains the context relative to which
* <code>altName</code> is specified. If null, then the default initial
* {@code altName} is specified. If null, then the default initial
* context is implied.
* See the <code>javax.naming.spi.ObjectFactory.getObjectInstance</code>
* See the {@code javax.naming.spi.ObjectFactory.getObjectInstance}
* method for details on how this is used.
* <p>
* This field is initialized to null.
@ -189,16 +189,16 @@ public class CannotProceedException extends NamingException {
/**
* Sets the "remaining new name" field of this exception.
* This is the value returned by <code>getRemainingNewName()</code>.
* This is the value returned by {@code getRemainingNewName()}.
*<p>
* <tt>newName</tt> is a composite name. If the intent is to set
* {@code newName} is a composite name. If the intent is to set
* this field using a compound name or string, you must
* "stringify" the compound name, and create a composite
* name with a single component using the string. You can then
* invoke this method using the resulting composite name.
*<p>
* A copy of <code>newName</code> is made and stored.
* Subsequent changes to <code>name</code> does not
* A copy of {@code newName} is made and stored.
* Subsequent changes to {@code name} does not
* affect the copy in this NamingException and vice versa.
*
* @param newName The possibly null name to set the "remaining new name" to.
@ -214,13 +214,13 @@ public class CannotProceedException extends NamingException {
}
/**
* Retrieves the <code>altName</code> field of this exception.
* Retrieves the {@code altName} field of this exception.
* This is the name of the resolved object, relative to the context
* <code>altNameCtx</code>. It will be used during a subsequent call to the
* <code>javax.naming.spi.ObjectFactory.getObjectInstance</code> method.
* {@code altNameCtx}. It will be used during a subsequent call to the
* {@code javax.naming.spi.ObjectFactory.getObjectInstance} method.
*
* @return The name of the resolved object, relative to
* <code>altNameCtx</code>.
* {@code altNameCtx}.
* It is a composite name. If null, then no name is specified.
*
* @see #setAltName
@ -232,10 +232,10 @@ public class CannotProceedException extends NamingException {
}
/**
* Sets the <code>altName</code> field of this exception.
* Sets the {@code altName} field of this exception.
*
* @param altName The name of the resolved object, relative to
* <code>altNameCtx</code>.
* {@code altNameCtx}.
* It is a composite name.
* If null, then no name is specified.
*
@ -247,12 +247,12 @@ public class CannotProceedException extends NamingException {
}
/**
* Retrieves the <code>altNameCtx</code> field of this exception.
* This is the context relative to which <code>altName</code> is named.
* Retrieves the {@code altNameCtx} field of this exception.
* This is the context relative to which {@code altName} is named.
* It will be used during a subsequent call to the
* <code>javax.naming.spi.ObjectFactory.getObjectInstance</code> method.
* {@code javax.naming.spi.ObjectFactory.getObjectInstance} method.
*
* @return The context relative to which <code>altName</code> is named.
* @return The context relative to which {@code altName} is named.
* If null, then the default initial context is implied.
*
* @see #setAltNameCtx
@ -264,10 +264,10 @@ public class CannotProceedException extends NamingException {
}
/**
* Sets the <code>altNameCtx</code> field of this exception.
* Sets the {@code altNameCtx} field of this exception.
*
* @param altNameCtx
* The context relative to which <code>altName</code>
* The context relative to which {@code altName}
* is named. If null, then the default initial context
* is implied.
*

12
jdk/src/java.naming/share/classes/javax/naming/CompositeName.java
View File

@ -76,7 +76,7 @@ import java.util.Properties;
*<h1>Composite Name Examples</h1>
*This table shows examples of some composite names. Each row shows
*the string form of a composite name and its corresponding structural form
*(<tt>CompositeName</tt>).
*({@code CompositeName}).
*
<table border="1" cellpadding=3 summary="examples showing string form of composite name and its corresponding structural form (CompositeName)">
@ -140,7 +140,7 @@ import java.util.Properties;
*<h1>Composition Examples</h1>
* Here are some composition examples. The right column shows composing
* string composite names while the left column shows composing the
* corresponding <tt>CompositeName</tt>s. Notice that composing the
* corresponding {@code CompositeName}s. Notice that composing the
* string forms of two composite names simply involves concatenating
* their string forms together.
@ -190,9 +190,9 @@ import java.util.Properties;
</table>
*
*<h1>Multithreaded Access</h1>
* A <tt>CompositeName</tt> instance is not synchronized against concurrent
* A {@code CompositeName} instance is not synchronized against concurrent
* multithreaded access. Multiple threads trying to access and modify a
* <tt>CompositeName</tt> should lock the object.
* {@code CompositeName} should lock the object.
*
* @author Rosanna Lee
* @author Scott Seligman
@ -557,8 +557,8 @@ public class CompositeName implements Name {
/**
* Overridden to avoid implementation dependency.
* @serialData The number of components (an <tt>int</tt>) followed by
* the individual components (each a <tt>String</tt>).
* @serialData The number of components (an {@code int}) followed by
* the individual components (each a {@code String}).
*/
private void writeObject(java.io.ObjectOutputStream s)
throws java.io.IOException {

12
jdk/src/java.naming/share/classes/javax/naming/CompoundName.java
View File

@ -137,9 +137,9 @@ import java.util.Properties;
* of the original compound name.
*
*<h1>Multithreaded Access</h1>
* A <tt>CompoundName</tt> instance is not synchronized against concurrent
* A {@code CompoundName} instance is not synchronized against concurrent
* multithreaded access. Multiple threads trying to access and modify a
* <tt>CompoundName</tt> should lock the object.
* {@code CompoundName} should lock the object.
*
* @author Rosanna Lee
* @author Scott Seligman
@ -194,7 +194,7 @@ public class CompoundName implements Name {
* this compound name. See class description for
* contents of properties.
* @exception InvalidNameException If 'n' violates the syntax specified
* by <code>syntax</code>.
* by {@code syntax}.
*/
public CompoundName(String n, Properties syntax) throws InvalidNameException {
if (syntax == null) {
@ -549,9 +549,9 @@ public class CompoundName implements Name {
/**
* Overridden to avoid implementation dependency.
* @serialData The syntax <tt>Properties</tt>, followed by
* the number of components (an <tt>int</tt>), and the individual
* components (each a <tt>String</tt>).
* @serialData The syntax {@code Properties}, followed by
* the number of components (an {@code int}), and the individual
* components (each a {@code String}).
*/
private void writeObject(java.io.ObjectOutputStream s)
throws java.io.IOException {

118
jdk/src/java.naming/share/classes/javax/naming/Context.java
View File

@ -33,7 +33,7 @@ import java.util.Hashtable;
* 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>
@ -47,31 +47,31 @@ import java.util.Hashtable;
* 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>
@ -80,26 +80,26 @@ import java.util.Hashtable;
* 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.
*
*
@ -111,7 +111,7 @@ import java.util.Hashtable;
* 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
@ -145,7 +145,7 @@ import java.util.Hashtable;
* 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
@ -170,18 +170,18 @@ import java.util.Hashtable;
* 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>
@ -204,11 +204,11 @@ import java.util.Hashtable;
*
* 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
@ -220,7 +220,7 @@ import java.util.Hashtable;
* 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
@ -234,7 +234,7 @@ import java.util.Hashtable;
* 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.
*
@ -244,7 +244,7 @@ import java.util.Hashtable;
* 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,
@ -278,14 +278,14 @@ 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)
@ -298,7 +298,7 @@ public interface Context {
* 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;
@ -344,7 +344,7 @@ public interface Context {
* 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.
@ -388,7 +388,7 @@ public interface Context {
* <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.
@ -424,7 +424,7 @@ public interface Context {
* 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)
@ -442,7 +442,7 @@ public interface Context {
* 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;
@ -459,7 +459,7 @@ public interface Context {
* 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)
@ -478,7 +478,7 @@ public interface Context {
* 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)
@ -496,7 +496,7 @@ public interface Context {
* 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)
@ -515,7 +515,7 @@ public interface Context {
* 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)
@ -529,7 +529,7 @@ public interface Context {
* <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
@ -537,11 +537,11 @@ public interface Context {
* 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
@ -611,12 +611,12 @@ public interface Context {
/**
* 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
*
@ -631,7 +631,7 @@ public interface Context {
*
* @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
*/
@ -643,8 +643,8 @@ public interface Context {
* 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
@ -765,7 +765,7 @@ public interface Context {
* <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
@ -798,7 +798,7 @@ public interface Context {
* 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
@ -821,7 +821,7 @@ public interface Context {
* 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".
@ -882,7 +882,7 @@ public interface Context {
* 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".
@ -920,7 +920,7 @@ public interface Context {
* 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".
*
@ -974,7 +974,7 @@ public interface Context {
* <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.

40
jdk/src/java.naming/share/classes/javax/naming/InitialContext.java
View File

@ -49,13 +49,13 @@ import com.sun.naming.internal.ResourceManager;
* The first occurrence of the property from the constructor's
* environment parameter and system properties.
* <li>
* The application resource files (<tt>jndi.properties</tt>).
* The application resource files ({@code jndi.properties}).
* </ol>
* For each property found in both of these two sources, or in
* more than one application resource file, the property's value
* is determined as follows. If the property is
* one of the standard JNDI properties that specify a list of JNDI
* factories (see <a href=Context.html#LISTPROPS><tt>Context</tt></a>),
* factories (see <a href=Context.html#LISTPROPS>{@code Context}</a>),
* all of the values are
* concatenated into a single colon-separated list. For other
* properties, only the first value found is used.
@ -68,23 +68,23 @@ import com.sun.naming.internal.ResourceManager;
* An exception to this policy is made when resolving URL strings, as described
* below.
*<p>
* When a URL string (a <tt>String</tt> of the form
* When a URL string (a {@code String} of the form
* <em>scheme_id:rest_of_name</em>) is passed as a name parameter to
* any method, a URL context factory for handling that scheme is
* located and used to resolve the URL. If no such factory is found,
* the initial context specified by
* <tt>"java.naming.factory.initial"</tt> is used. Similarly, when a
* <tt>CompositeName</tt> object whose first component is a URL string is
* {@code "java.naming.factory.initial"} is used. Similarly, when a
* {@code CompositeName} object whose first component is a URL string is
* passed as a name parameter to any method, a URL context factory is
* located and used to resolve the first name component.
* See {@link NamingManager#getURLContext
* <tt>NamingManager.getURLContext()</tt>} for a description of how URL
* NamingManager.getURLContext()} for a description of how URL
* context factories are located.
*<p>
* This default policy of locating the initial context and URL context
* factories may be overridden
* by calling
* <tt>NamingManager.setInitialContextFactoryBuilder()</tt>.
* {@code NamingManager.setInitialContextFactoryBuilder()}.
*<p>
* NoInitialContextException is thrown when an initial context cannot
* be instantiated. This exception can be thrown during any interaction
@ -125,7 +125,7 @@ public class InitialContext implements Context {
/**
* The environment associated with this InitialContext.
* It is initialized to null and is updated by the constructor
* that accepts an environment or by the <tt>init()</tt> method.
* that accepts an environment or by the {@code init()} method.
* @see #addToEnvironment
* @see #removeFromEnvironment
* @see #getEnvironment
@ -152,14 +152,14 @@ public class InitialContext implements Context {
* Constructs an initial context with the option of not
* initializing it. This may be used by a constructor in
* a subclass when the value of the environment parameter
* is not yet known at the time the <tt>InitialContext</tt>
* is not yet known at the time the {@code InitialContext}
* constructor is called. The subclass's constructor will
* call this constructor, compute the value of the environment,
* and then call <tt>init()</tt> before returning.
* and then call {@code init()} before returning.
*
* @param lazy
* true means do not initialize the initial context; false
* is equivalent to calling <tt>new InitialContext()</tt>
* is equivalent to calling {@code new InitialContext()}
* @throws NamingException if a naming exception is encountered
*
* @see #init(Hashtable)
@ -174,7 +174,7 @@ public class InitialContext implements Context {
/**
* Constructs an initial context.
* No environment properties are supplied.
* Equivalent to <tt>new InitialContext(null)</tt>.
* Equivalent to {@code new InitialContext(null)}.
*
* @throws NamingException if a naming exception is encountered
*
@ -188,10 +188,10 @@ public class InitialContext implements Context {
* Constructs an initial context using the supplied environment.
* Environment properties are discussed in the class description.
*
* <p> This constructor will not modify <tt>environment</tt>
* <p> This constructor will not modify {@code environment}
* or save a reference to it, but may save a clone.
* Caller should not modify mutable keys and values in
* <tt>environment</tt> after it has been passed to the constructor.
* {@code environment} after it has been passed to the constructor.
*
* @param environment
* environment used to create the initial context.
@ -212,7 +212,7 @@ public class InitialContext implements Context {
* Initializes the initial context using the supplied environment.
* Environment properties are discussed in the class description.
*
* <p> This method will modify <tt>environment</tt> and save
* <p> This method will modify {@code environment} and save
* a reference to it. The caller may no longer modify it.
*
* @param environment
@ -245,7 +245,7 @@ public class InitialContext implements Context {
* InitialContext ic = new InitialContext();
* Object obj = ic.lookup();
* </code>
* <p> If <tt>name</tt> is empty, returns a new instance of this context
* <p> 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).
@ -253,7 +253,7 @@ public class InitialContext implements Context {
* @param <T> the type of the returned object
* @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 #doLookup(String)
@ -272,7 +272,7 @@ public class InitialContext implements Context {
* @param <T> the type of the returned object
* @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
* @since 1.6
*/
@ -506,7 +506,7 @@ public class InitialContext implements Context {
* this context.
* Since an initial context may never be named relative
* to any context other than itself, the value of the
* <tt>prefix</tt> parameter must be an empty name (<tt>""</tt>).
* {@code prefix} parameter must be an empty name ({@code ""}).
*/
public String composeName(String name, String prefix)
throws NamingException {
@ -518,7 +518,7 @@ public class InitialContext implements Context {
* this context.
* Since an initial context may never be named relative
* to any context other than itself, the value of the
* <tt>prefix</tt> parameter must be an empty name.
* {@code prefix} parameter must be an empty name.
*/
public Name composeName(Name name, Name prefix)
throws NamingException

4
jdk/src/java.naming/share/classes/javax/naming/LinkException.java
View File

@ -204,7 +204,7 @@ public class LinkException extends NamingException {
/**
* Sets the resolved link name field of this exception.
*<p>
* <tt>name</tt> is a composite name. If the intent is to set
* {@code name} is a composite name. If the intent is to set
* this field using a compound name or string, you must
* "stringify" the compound name, and create a composite
* name with a single component using the string. You can then
@ -230,7 +230,7 @@ public class LinkException extends NamingException {
/**
* Sets the remaining link name field of this exception.
*<p>
* <tt>name</tt> is a composite name. If the intent is to set
* {@code name} is a composite name. If the intent is to set
* this field using a compound name or string, you must
* "stringify" the compound name, and create a composite
* name with a single component using the string. You can then

30
jdk/src/java.naming/share/classes/javax/naming/Name.java
View File

@ -28,12 +28,12 @@ package javax.naming;
import java.util.Enumeration;
/**
* The <tt>Name</tt> interface represents a generic name -- an ordered
* The {@code Name} interface represents a generic name -- an ordered
* sequence of components. It can be a composite name (names that
* span multiple namespaces), or a compound name (names that are
* used within individual hierarchical naming systems).
*
* <p> There can be different implementations of <tt>Name</tt>; for example,
* <p> There can be different implementations of {@code Name}; for example,
* composite names, URLs, or namespace-specific compound names.
*
* <p> The components of a name are numbered. The indexes of a name
@ -46,7 +46,7 @@ import java.util.Enumeration;
* value for a parameter that is a name or a name component.
* Likewise, methods that return a name or name component never return null.
*
* <p> An instance of a <tt>Name</tt> may not be synchronized against
* <p> An instance of a {@code Name} may not be synchronized against
* concurrent multithreaded access if that access is not read-only.
*
* @author Rosanna Lee
@ -82,7 +82,7 @@ public interface Name
* Returns a negative integer, zero, or a positive integer as this
* name is less than, equal to, or greater than the given name.
*
* <p> As with <tt>Object.equals()</tt>, the notion of ordering for names
* <p> As with {@code Object.equals()}, the notion of ordering for names
* depends on the class that implements this interface.
* For example, the ordering may be
* based on lexicographical ordering of the name components.
@ -93,7 +93,7 @@ public interface Name
* @param obj the non-null object to compare against.
* @return a negative integer, zero, or a positive integer as this name
* is less than, equal to, or greater than the given name
* @throws ClassCastException if obj is not a <tt>Name</tt> of a
* @throws ClassCastException if obj is not a {@code Name} of a
* type that may be compared with this name
*
* @see Comparable#compareTo(Object)
@ -170,23 +170,23 @@ public interface Name
/**
* Determines whether this name starts with a specified prefix.
* A name <tt>n</tt> is a prefix if it is equal to
* <tt>getPrefix(n.size())</tt>.
* A name {@code n} is a prefix if it is equal to
* {@code getPrefix(n.size())}.
*
* @param n
* the name to check
* @return true if <tt>n</tt> is a prefix of this name, false otherwise
* @return true if {@code n} is a prefix of this name, false otherwise
*/
public boolean startsWith(Name n);
/**
* Determines whether this name ends with a specified suffix.
* A name <tt>n</tt> is a suffix if it is equal to
* <tt>getSuffix(size()-n.size())</tt>.
* A name {@code n} is a suffix if it is equal to
* {@code getSuffix(size()-n.size())}.
*
* @param n
* the name to check
* @return true if <tt>n</tt> is a suffix of this name, false otherwise
* @return true if {@code n} is a suffix of this name, false otherwise
*/
public boolean endsWith(Name n);
@ -197,7 +197,7 @@ public interface Name
* the components to add
* @return the updated name (not a new one)
*
* @throws InvalidNameException if <tt>suffix</tt> is not a valid name,
* @throws InvalidNameException if {@code suffix} is not a valid name,
* or if the addition of the components would violate the syntax
* rules of this name
*/
@ -219,7 +219,7 @@ public interface Name
*
* @throws ArrayIndexOutOfBoundsException
* if posn is outside the specified range
* @throws InvalidNameException if <tt>n</tt> is not a valid name,
* @throws InvalidNameException if {@code n} is not a valid name,
* or if the addition of the components would violate the syntax
* rules of this name
*/
@ -232,7 +232,7 @@ public interface Name
* the component to add
* @return the updated name (not a new one)
*
* @throws InvalidNameException if adding <tt>comp</tt> would violate
* @throws InvalidNameException if adding {@code comp} would violate
* the syntax rules of this name
*/
public Name add(String comp) throws InvalidNameException;
@ -252,7 +252,7 @@ public interface Name
*
* @throws ArrayIndexOutOfBoundsException
* if posn is outside the specified range
* @throws InvalidNameException if adding <tt>comp</tt> would violate
* @throws InvalidNameException if adding {@code comp} would violate
* the syntax rules of this name
*/
public Name add(int posn, String comp) throws InvalidNameException;

26
jdk/src/java.naming/share/classes/javax/naming/NameClassPair.java
View File

@ -60,7 +60,7 @@ public class NameClassPair implements java.io.Serializable {
/**
* Contains the name of this NameClassPair.
* It is initialized by the constructor and can be updated using
* <tt>setName()</tt>.
* {@code setName()}.
* @serial
* @see #getName
* @see #setName
@ -70,7 +70,7 @@ public class NameClassPair implements java.io.Serializable {
/**
*Contains the class name contained in this NameClassPair.
* It is initialized by the constructor and can be updated using
* <tt>setClassName()</tt>.
* {@code setClassName()}.
* @serial
* @see #getClassName
* @see #setClassName
@ -80,7 +80,7 @@ public class NameClassPair implements java.io.Serializable {
/**
* Contains the full name of this NameClassPair within its
* own namespace.
* It is initialized using <tt>setNameInNamespace()</tt>
* It is initialized using {@code setNameInNamespace()}
* @serial
* @see #getNameInNamespace
* @see #setNameInNamespace
@ -89,10 +89,10 @@ public class NameClassPair implements java.io.Serializable {
/**
* Records whether the name of this <tt>NameClassPair</tt>
* Records whether the name of this {@code NameClassPair}
* is relative to the target context.
* It is initialized by the constructor and can be updated using
* <tt>setRelative()</tt>.
* {@code setRelative()}.
* @serial
* @see #isRelative
* @see #setRelative
@ -148,7 +148,7 @@ public class NameClassPair implements java.io.Serializable {
* Retrieves the class name of the object bound to the name of this binding.
* If a reference or some other indirect information is bound,
* retrieves the class name of the eventual object that
* will be returned by <tt>Binding.getObject()</tt>.
* will be returned by {@code Binding.getObject()}.
*
* @return The possibly null class name of object bound.
* It is null if the object bound is null.
@ -162,10 +162,10 @@ public class NameClassPair implements java.io.Serializable {
/**
* Retrieves the name of this binding.
* If <tt>isRelative()</tt> is true, this name is relative to the
* If {@code isRelative()} is true, this name is relative to the
* target context (which is named by the first parameter of the
* <tt>list()</tt>).
* If <tt>isRelative()</tt> is false, this name is a URL string.
* {@code list()}).
* If {@code isRelative()} is false, this name is a URL string.
*
* @return The non-null name of this binding.
* @see #isRelative
@ -190,7 +190,7 @@ public class NameClassPair implements java.io.Serializable {
* Sets the class name of this binding.
*
* @param name the possibly null string to use as the class name.
* If null, <tt>Binding.getClassName()</tt> will return
* If null, {@code Binding.getClassName()} will return
* the actual class name of the object in the binding.
* The class name will be null if the object bound is null.
* @see #getClassName
@ -236,7 +236,7 @@ public class NameClassPair implements java.io.Serializable {
* <p>
*
* In naming systems for which the notion of full name does not
* apply to this binding an <tt>UnsupportedOperationException</tt>
* apply to this binding an {@code UnsupportedOperationException}
* is thrown.
* This exception is also thrown when a service provider written before
* the introduction of the method is in use.
@ -261,11 +261,11 @@ public class NameClassPair implements java.io.Serializable {
/**
* Sets the full name of this binding.
* This method must be called to set the full name whenever a
* <tt>NameClassPair</tt> is created and a full name is
* {@code NameClassPair} is created and a full name is
* applicable to this binding.
* <p>
* Setting the full name to null, or not setting it at all, will
* cause <tt>getNameInNamespace()</tt> to throw an exception.
* cause {@code getNameInNamespace()} to throw an exception.
*
* @param fullName The full name to use.
* @since 1.5

10
jdk/src/java.naming/share/classes/javax/naming/NamingEnumeration.java
View File

@ -85,7 +85,7 @@ public interface NamingEnumeration<T> extends Enumeration<T> {
* retrieving the next element to be caught and handled
* by the application.
* <p>
* Note that <tt>next()</tt> can also throw the runtime exception
* Note that {@code next()} can also throw the runtime exception
* NoSuchElementException to indicate that the caller is
* attempting to enumerate beyond the end of the enumeration.
* This is different from a NamingException, which indicates
@ -128,16 +128,16 @@ public interface NamingEnumeration<T> extends Enumeration<T> {
* its methods will yield undefined results.
* This method is intended for aborting an enumeration to free up resources.
* If an enumeration proceeds to the end--that is, until
* <tt>hasMoreElements()</tt> or <tt>hasMore()</tt> returns <tt>false</tt>--
* {@code hasMoreElements()} or {@code hasMore()} returns {@code false}--
* resources will be freed up automatically and there is no need to
* explicitly call <tt>close()</tt>.
* explicitly call {@code close()}.
*<p>
* This method indicates to the service provider that it is free
* to release resources associated with the enumeration, and can
* notify servers to cancel any outstanding requests. The <tt>close()</tt>
* notify servers to cancel any outstanding requests. The {@code close()}
* method is a hint to implementations for managing their resources.
* Implementations are encouraged to use appropriate algorithms to
* manage their resources when client omits the <tt>close()</tt> calls.
* manage their resources when client omits the {@code close()} calls.
*
* @exception NamingException If a naming exception is encountered
* while closing the enumeration.

28
jdk/src/java.naming/share/classes/javax/naming/NamingException.java
View File

@ -194,14 +194,14 @@ public class NamingException extends Exception {
/**
* Sets the resolved name field of this exception.
*<p>
* <tt>name</tt> is a composite name. If the intent is to set
* {@code name} is a composite name. If the intent is to set
* this field using a compound name or string, you must
* "stringify" the compound name, and create a composite
* name with a single component using the string. You can then
* invoke this method using the resulting composite name.
*<p>
* A copy of <code>name</code> is made and stored.
* Subsequent changes to <code>name</code> do not
* A copy of {@code name} is made and stored.
* Subsequent changes to {@code name} do not
* affect the copy in this NamingException and vice versa.
*
* @param name The possibly null name to set resolved name to.
@ -218,14 +218,14 @@ public class NamingException extends Exception {
/**
* Sets the remaining name field of this exception.
*<p>
* <tt>name</tt> is a composite name. If the intent is to set
* {@code name} is a composite name. If the intent is to set
* this field using a compound name or string, you must
* "stringify" the compound name, and create a composite
* name with a single component using the string. You can then
* invoke this method using the resulting composite name.
*<p>
* A copy of <code>name</code> is made and stored.
* Subsequent changes to <code>name</code> do not
* A copy of {@code name} is made and stored.
* Subsequent changes to {@code name} do not
* affect the copy in this NamingException and vice versa.
* @param name The possibly null name to set remaining name to.
* If null, it sets the remaining name field to null.
@ -275,11 +275,11 @@ public class NamingException extends Exception {
* Add components from 'name' as the last components in
* remaining name.
*<p>
* <tt>name</tt> is a composite name. If the intent is to append
* {@code name} is a composite name. If the intent is to append
* a compound name, you should "stringify" the compound name
* then invoke the overloaded form that accepts a String parameter.
*<p>
* Subsequent changes to <code>name</code> do not
* Subsequent changes to {@code name} do not
* affect the remaining name field in this NamingException and vice versa.
* @param name The possibly null name containing ordered components to add.
* If name is null, this method does not do anything.
@ -326,7 +326,7 @@ public class NamingException extends Exception {
/**
* Records the root cause of this NamingException.
* If <tt>e</tt> is <tt>this</tt>, this method does not do anything.
* If {@code e} is {@code this}, this method does not do anything.
*<p>
* This method predates the general-purpose exception chaining facility.
* The {@link #initCause(Throwable)} method is now the preferred means
@ -348,10 +348,10 @@ public class NamingException extends Exception {
/**
* Returns the cause of this exception. The cause is the
* throwable that caused this naming exception to be thrown.
* Returns <code>null</code> if the cause is nonexistent or
* Returns {@code null} if the cause is nonexistent or
* unknown.
*
* @return the cause of this exception, or <code>null</code> if the
* @return the cause of this exception, or {@code null} if the
* cause is nonexistent or unknown.
* @see #initCause(Throwable)
* @since 1.4
@ -368,10 +368,10 @@ public class NamingException extends Exception {
* This method may be called at most once.
*
* @param cause the cause, which is saved for later retrieval by
* the {@link #getCause()} method. A <tt>null</tt> value
* the {@link #getCause()} method. A {@code null} value
* indicates that the cause is nonexistent or unknown.
* @return a reference to this <code>NamingException</code> instance.
* @throws IllegalArgumentException if <code>cause</code> is this
* @return a reference to this {@code NamingException} instance.
* @throws IllegalArgumentException if {@code cause} is this
* exception. (A throwable cannot be its own cause.)
* @throws IllegalStateException if this method has already
* been called on this exception.

2
jdk/src/java.naming/share/classes/javax/naming/Reference.java
View File

@ -250,7 +250,7 @@ public class Reference implements Cloneable, java.io.Serializable {
* its effects on this enumeration are undefined.
*
* @return An non-null enumeration of the addresses
* (<tt>RefAddr</tt>) in this reference.
* ({@code RefAddr}) in this reference.
* If this reference has zero addresses, an enumeration with
* zero elements is returned.
*/

24
jdk/src/java.naming/share/classes/javax/naming/ReferralException.java
View File

@ -33,12 +33,12 @@ import java.util.Hashtable;
* such as that returned by LDAP v3 servers.
* <p>
* A service provider provides
* a subclass of <tt>ReferralException</tt> by providing implementations
* for <tt>getReferralInfo()</tt> and <tt>getReferralContext()</tt> (and appropriate
* a subclass of {@code ReferralException} by providing implementations
* for {@code getReferralInfo()} and {@code getReferralContext()} (and appropriate
* constructors and/or corresponding "set" methods).
* <p>
* The following code sample shows how <tt>ReferralException</tt> can be used.
* <blockquote>{@code
* The following code sample shows how {@code ReferralException} can be used.
* <blockquote><pre>{@code
* while (true) {
* try {
* bindings = ctx.listBindings(name);
@ -51,12 +51,12 @@ import java.util.Hashtable;
* ctx = e.getReferralContext();
* }
* }
* }</blockquote>
* }</pre></blockquote>
*<p>
* <tt>ReferralException</tt> is an abstract class. Concrete implementations
* {@code ReferralException} is an abstract class. Concrete implementations
* determine its synchronization and serialization properties.
*<p>
* An environment parameter passed to the <tt>getReferralContext()</tt>
* An environment parameter passed to the {@code getReferralContext()}
* method is owned by the caller.
* The service provider will not modify the object or keep a reference to it,
* but may keep a reference to a clone of it.
@ -114,7 +114,7 @@ public abstract class ReferralException extends NamingException {
*
* @return The non-null context at which to continue the method.
* @exception NamingException If a naming exception was encountered.
* Call either <tt>retryReferral()</tt> or <tt>skipReferral()</tt>
* Call either {@code retryReferral()} or {@code skipReferral()}
* to continue processing referrals.
*/
public abstract Context getReferralContext() throws NamingException;
@ -127,7 +127,7 @@ public abstract class ReferralException extends NamingException {
* enumeration, the referral exception should provide a context
* at which to continue the operation.
*<p>
* The referral context is created using <tt>env</tt> as its environment
* The referral context is created using {@code env} as its environment
* properties.
* This method should be used instead of the no-arg overloaded form
* when the caller needs to use different environment properties for
@ -143,7 +143,7 @@ public abstract class ReferralException extends NamingException {
*
* @return The non-null context at which to continue the method.
* @exception NamingException If a naming exception was encountered.
* Call either <tt>retryReferral()</tt> or <tt>skipReferral()</tt>
* Call either {@code retryReferral()} or {@code skipReferral()}
* to continue processing referrals.
*/
public abstract Context
@ -153,7 +153,7 @@ public abstract class ReferralException extends NamingException {
/**
* Discards the referral about to be processed.
* A call to this method should be followed by a call to
* <code>getReferralContext</code> to allow the processing of
* {@code getReferralContext} to allow the processing of
* other referrals to continue.
* The following code fragment shows a typical usage pattern.
* <blockquote><pre>
@ -174,7 +174,7 @@ public abstract class ReferralException extends NamingException {
/**
* Retries the referral currently being processed.
* A call to this method should be followed by a call to
* <code>getReferralContext</code> to allow the current
* {@code getReferralContext} to allow the current
* referral to be retried.
* The following code fragment shows a typical usage pattern.
* <blockquote><pre>

72
jdk/src/java.naming/share/classes/javax/naming/directory/Attribute.java
View File

@ -37,34 +37,34 @@ import javax.naming.OperationNotSupportedException;
* This interface represents an attribute associated with a named object.
*<p>
* In a directory, named objects can have associated with them
* attributes. The <tt>Attribute</tt> interface represents an attribute associated
* attributes. The {@code Attribute} interface represents an attribute associated
* with a named object. An attribute contains 0 or more, possibly null, values.
* The attribute values can be ordered or unordered (see <tt>isOrdered()</tt>).
* The attribute values can be ordered or unordered (see {@code isOrdered()}).
* If the values are unordered, no duplicates are allowed.
* If the values are ordered, duplicates are allowed.
*<p>
* The content and representation of an attribute and its values is defined by
* the attribute's <em>schema</em>. The schema contains information
* about the attribute's syntax and other properties about the attribute.
* See <tt>getAttributeDefinition()</tt> and
* <tt>getAttributeSyntaxDefinition()</tt>
* See {@code getAttributeDefinition()} and
* {@code getAttributeSyntaxDefinition()}
* for details regarding how to get schema information about an attribute
* if the underlying directory service supports schemas.
*<p>
* Equality of two attributes is determined by the implementation class.
* A simple implementation can use <tt>Object.equals()</tt> to determine equality
* A simple implementation can use {@code Object.equals()} to determine equality
* of attribute values, while a more sophisticated implementation might
* make use of schema information to determine equality.
* Similarly, one implementation might provide a static storage
* structure which simply returns the values passed to its
* constructor, while another implementation might define <tt>get()</tt> and
* <tt>getAll()</tt>.
* constructor, while another implementation might define {@code get()} and
* {@code getAll()}.
* to get the values dynamically from the directory.
*<p>
* Note that updates to <tt>Attribute</tt> (such as adding or removing a
* Note that updates to {@code Attribute} (such as adding or removing a
* value) do not affect the corresponding representation of the attribute
* in the directory. Updates to the directory can only be effected
* using operations in the <tt>DirContext</tt> interface.
* using operations in the {@code DirContext} interface.
*
* @author Rosanna Lee
* @author Scott Seligman
@ -129,7 +129,7 @@ public interface Attribute extends Cloneable, java.io.Serializable {
/**
* Determines whether a value is in the attribute.
* Equality is determined by the implementation, which may use
* <tt>Object.equals()</tt> or schema information to determine equality.
* {@code Object.equals()} or schema information to determine equality.
*
* @param attrVal The possibly null value to check. If null, check
* whether the attribute has an attribute value whose value is null.
@ -141,12 +141,12 @@ public interface Attribute extends Cloneable, java.io.Serializable {
/**
* Adds a new value to the attribute.
* If the attribute values are unordered and
* <tt>attrVal</tt> is already in the attribute, this method does nothing.
* If the attribute values are ordered, <tt>attrVal</tt> is added to the end of
* {@code attrVal} is already in the attribute, this method does nothing.
* If the attribute values are ordered, {@code attrVal} is added to the end of
* the list of attribute values.
*<p>
* Equality is determined by the implementation, which may use
* <tt>Object.equals()</tt> or schema information to determine equality.
* {@code Object.equals()} or schema information to determine equality.
*
* @param attrVal The new possibly null value to add. If null, null
* is added as an attribute value.
@ -156,15 +156,15 @@ public interface Attribute extends Cloneable, java.io.Serializable {
/**
* Removes a specified value from the attribute.
* If <tt>attrval</tt> is not in the attribute, this method does nothing.
* If {@code attrval} is not in the attribute, this method does nothing.
* If the attribute values are ordered, the first occurrence of
* <tt>attrVal</tt> is removed and attribute values at indices greater
* {@code attrVal} is removed and attribute values at indices greater
* than the removed
* value are shifted up towards the head of the list (and their indices
* decremented by one).
*<p>
* Equality is determined by the implementation, which may use
* <tt>Object.equals()</tt> or schema information to determine equality.
* {@code Object.equals()} or schema information to determine equality.
*
* @param attrval The possibly null value to remove from this attribute.
* If null, remove the attribute value that is null.
@ -260,66 +260,66 @@ public interface Attribute extends Cloneable, java.io.Serializable {
/**
* Retrieves the attribute value from the ordered list of attribute values.
* This method returns the value at the <tt>ix</tt> index of the list of
* This method returns the value at the {@code ix} index of the list of
* attribute values.
* If the attribute values are unordered,
* this method returns the value that happens to be at that index.
* @param ix The index of the value in the ordered list of attribute values.
* {@code 0 <= ix < size()}.
* @return The possibly null attribute value at index <tt>ix</tt>;
* @return The possibly null attribute value at index {@code ix};
* null if the attribute value is null.
* @exception NamingException If a naming exception was encountered while
* retrieving the value.
* @exception IndexOutOfBoundsException If <tt>ix</tt> is outside the specified range.
* @exception IndexOutOfBoundsException If {@code ix} is outside the specified range.
*/
Object get(int ix) throws NamingException;
/**
* Removes an attribute value from the ordered list of attribute values.
* This method removes the value at the <tt>ix</tt> index of the list of
* This method removes the value at the {@code ix} index of the list of
* attribute values.
* If the attribute values are unordered,
* this method removes the value that happens to be at that index.
* Values located at indices greater than <tt>ix</tt> are shifted up towards
* Values located at indices greater than {@code ix} are shifted up towards
* the front of the list (and their indices decremented by one).
*
* @param ix The index of the value to remove.
* {@code 0 <= ix < size()}.
* @return The possibly null attribute value at index <tt>ix</tt> that was removed;
* @return The possibly null attribute value at index {@code ix} that was removed;
* null if the attribute value is null.
* @exception IndexOutOfBoundsException If <tt>ix</tt> is outside the specified range.
* @exception IndexOutOfBoundsException If {@code ix} is outside the specified range.
*/
Object remove(int ix);
/**
* Adds an attribute value to the ordered list of attribute values.
* This method adds <tt>attrVal</tt> to the list of attribute values at
* index <tt>ix</tt>.
* Values located at indices at or greater than <tt>ix</tt> are
* This method adds {@code attrVal} to the list of attribute values at
* index {@code ix}.
* Values located at indices at or greater than {@code ix} are
* shifted down towards the end of the list (and their indices incremented
* by one).
* If the attribute values are unordered and already have <tt>attrVal</tt>,
* <tt>IllegalStateException</tt> is thrown.
* If the attribute values are unordered and already have {@code attrVal},
* {@code IllegalStateException} is thrown.
*
* @param ix The index in the ordered list of attribute values to add the new value.
* {@code 0 <= ix <= size()}.
* @param attrVal The possibly null attribute value to add; if null, null is
* the value added.
* @exception IndexOutOfBoundsException If <tt>ix</tt> is outside the specified range.
* @exception IndexOutOfBoundsException If {@code ix} is outside the specified range.
* @exception IllegalStateException If the attribute values are unordered and
* <tt>attrVal</tt> is one of those values.
* {@code attrVal} is one of those values.
*/
void add(int ix, Object attrVal);
/**
* Sets an attribute value in the ordered list of attribute values.
* This method sets the value at the <tt>ix</tt> index of the list of
* attribute values to be <tt>attrVal</tt>. The old value is removed.
* This method sets the value at the {@code ix} index of the list of
* attribute values to be {@code attrVal}. The old value is removed.
* If the attribute values are unordered,
* this method sets the value that happens to be at that index
* to <tt>attrVal</tt>, unless <tt>attrVal</tt> is already one of the values.
* In that case, <tt>IllegalStateException</tt> is thrown.
* to {@code attrVal}, unless {@code attrVal} is already one of the values.
* In that case, {@code IllegalStateException} is thrown.
*
* @param ix The index of the value in the ordered list of attribute values.
* {@code 0 <= ix < size()}.
@ -327,8 +327,8 @@ public interface Attribute extends Cloneable, java.io.Serializable {
* If null, 'null' replaces the old value.
* @return The possibly null attribute value at index ix that was replaced.
* Null if the attribute value was null.
* @exception IndexOutOfBoundsException If <tt>ix</tt> is outside the specified range.
* @exception IllegalStateException If <tt>attrVal</tt> already exists and the
* @exception IndexOutOfBoundsException If {@code ix} is outside the specified range.
* @exception IllegalStateException If {@code attrVal} already exists and the
* attribute values are unordered.
*/
Object set(int ix, Object attrVal);

2
jdk/src/java.naming/share/classes/javax/naming/directory/Attributes.java
View File

@ -103,7 +103,7 @@ public interface Attributes extends Cloneable, java.io.Serializable {
* are undefined.
*
* @return A non-null enumeration of the attributes in this attribute set.
* Each element of the enumeration is of class <tt>Attribute</tt>.
* Each element of the enumeration is of class {@code Attribute}.
* If attribute set has zero attributes, an empty enumeration
* is returned.
*/

62
jdk/src/java.naming/share/classes/javax/naming/directory/BasicAttribute.java
View File

@ -35,35 +35,35 @@ import javax.naming.NamingEnumeration;
import javax.naming.OperationNotSupportedException;
/**
* This class provides a basic implementation of the <tt>Attribute</tt> interface.
* This class provides a basic implementation of the {@code Attribute} interface.
*<p>
* This implementation does not support the schema methods
* <tt>getAttributeDefinition()</tt> and <tt>getAttributeSyntaxDefinition()</tt>.
* They simply throw <tt>OperationNotSupportedException</tt>.
* Subclasses of <tt>BasicAttribute</tt> should override these methods if they
* {@code getAttributeDefinition()} and {@code getAttributeSyntaxDefinition()}.
* They simply throw {@code OperationNotSupportedException}.
* Subclasses of {@code BasicAttribute} should override these methods if they
* support them.
*<p>
* The <tt>BasicAttribute</tt> class by default uses <tt>Object.equals()</tt> to
* The {@code BasicAttribute} class by default uses {@code Object.equals()} to
* determine equality of attribute values when testing for equality or
* when searching for values, <em>except</em> when the value is an array.
* For an array, each element of the array is checked using <tt>Object.equals()</tt>.
* Subclasses of <tt>BasicAttribute</tt> can make use of schema information
* For an array, each element of the array is checked using {@code Object.equals()}.
* Subclasses of {@code BasicAttribute} can make use of schema information
* when doing similar equality checks by overriding methods
* in which such use of schema is meaningful.
* Similarly, the <tt>BasicAttribute</tt> class by default returns the values passed to its
* Similarly, the {@code BasicAttribute} class by default returns the values passed to its
* constructor and/or manipulated using the add/remove methods.
* Subclasses of <tt>BasicAttribute</tt> can override <tt>get()</tt> and <tt>getAll()</tt>
* Subclasses of {@code BasicAttribute} can override {@code get()} and {@code getAll()}
* to get the values dynamically from the directory (or implement
* the <tt>Attribute</tt> interface directly instead of subclassing <tt>BasicAttribute</tt>).
* the {@code Attribute} interface directly instead of subclassing {@code BasicAttribute}).
*<p>
* Note that updates to <tt>BasicAttribute</tt> (such as adding or removing a value)
* Note that updates to {@code BasicAttribute} (such as adding or removing a value)
* does not affect the corresponding representation of the attribute
* in the directory. Updates to the directory can only be effected
* using operations in the <tt>DirContext</tt> interface.
* using operations in the {@code DirContext} interface.
*<p>
* A <tt>BasicAttribute</tt> instance is not synchronized against concurrent
* A {@code BasicAttribute} instance is not synchronized against concurrent
* multithreaded access. Multiple threads trying to access and modify a
* <tt>BasicAttribute</tt> should lock the object.
* {@code BasicAttribute} should lock the object.
*
* @author Rosanna Lee
* @author Scott Seligman
@ -112,16 +112,16 @@ public class BasicAttribute implements Attribute {
* order the values must match.
* If obj is null or not an Attribute, false is returned.
*<p>
* By default <tt>Object.equals()</tt> is used when comparing the attribute
* By default {@code Object.equals()} is used when comparing the attribute
* id and its values except when a value is an array. For an array,
* each element of the array is checked using <tt>Object.equals()</tt>.
* each element of the array is checked using {@code Object.equals()}.
* A subclass may override this to make
* use of schema syntax information and matching rules,
* which define what it means for two attributes to be equal.
* How and whether a subclass makes
* use of the schema information is determined by the subclass.
* If a subclass overrides <tt>equals()</tt>, it should also override
* <tt>hashCode()</tt>
* If a subclass overrides {@code equals()}, it should also override
* {@code hashCode()}
* such that two attributes that are equal have the same hash code.
*
* @param obj The possibly null object to check.
@ -172,8 +172,8 @@ public class BasicAttribute implements Attribute {
* the attribute's id and that of all of its values except for
* values that are arrays.
* For an array, the hash code of each element of the array is summed.
* If a subclass overrides <tt>hashCode()</tt>, it should override
* <tt>equals()</tt>
* If a subclass overrides {@code hashCode()}, it should override
* {@code equals()}
* as well so that two attributes that are equal have the same hash code.
*
* @return an int representing the hash code of this attribute.
@ -315,10 +315,10 @@ public class BasicAttribute implements Attribute {
* Determines whether a value is in this attribute.
*<p>
* By default,
* <tt>Object.equals()</tt> is used when comparing <tt>attrVal</tt>
* with this attribute's values except when <tt>attrVal</tt> is an array.
* {@code Object.equals()} is used when comparing {@code attrVal}
* with this attribute's values except when {@code attrVal} is an array.
* For an array, each element of the array is checked using
* <tt>Object.equals()</tt>.
* {@code Object.equals()}.
* A subclass may use schema information to determine equality.
*/
public boolean contains(Object attrVal) {
@ -352,7 +352,7 @@ public class BasicAttribute implements Attribute {
/**
* Determines whether two attribute values are equal.
* Use arrayEquals for arrays and <tt>Object.equals()</tt> otherwise.
* Use arrayEquals for arrays and {@code Object.equals()} otherwise.
*/
private static boolean valueEquals(Object obj1, Object obj2) {
if (obj1 == obj2) {
@ -370,7 +370,7 @@ public class BasicAttribute implements Attribute {
/**
* Determines whether two arrays are equal by comparing each of their
* elements using <tt>Object.equals()</tt>.
* elements using {@code Object.equals()}.
*/
private static boolean arrayEquals(Object a1, Object a2) {
int len;
@ -393,10 +393,10 @@ public class BasicAttribute implements Attribute {
/**
* Adds a new value to this attribute.
*<p>
* By default, <tt>Object.equals()</tt> is used when comparing <tt>attrVal</tt>
* with this attribute's values except when <tt>attrVal</tt> is an array.
* By default, {@code Object.equals()} is used when comparing {@code attrVal}
* with this attribute's values except when {@code attrVal} is an array.
* For an array, each element of the array is checked using
* <tt>Object.equals()</tt>.
* {@code Object.equals()}.
* A subclass may use schema information to determine equality.
*/
public boolean add(Object attrVal) {
@ -411,10 +411,10 @@ public class BasicAttribute implements Attribute {
/**
* Removes a specified value from this attribute.
*<p>
* By default, <tt>Object.equals()</tt> is used when comparing <tt>attrVal</tt>
* with this attribute's values except when <tt>attrVal</tt> is an array.
* By default, {@code Object.equals()} is used when comparing {@code attrVal}
* with this attribute's values except when {@code attrVal} is an array.
* For an array, each element of the array is checked using
* <tt>Object.equals()</tt>.
* {@code Object.equals()}.
* A subclass may use schema information to determine equality.
*/
public boolean remove(Object attrval) {

26
jdk/src/java.naming/share/classes/javax/naming/directory/BasicAttributes.java
View File

@ -207,17 +207,17 @@ public class BasicAttributes implements Attributes {
}
/**
* Determines whether this <tt>BasicAttributes</tt> is equal to another
* <tt>Attributes</tt>
* Two <tt>Attributes</tt> are equal if they are both instances of
* <tt>Attributes</tt>,
* Determines whether this {@code BasicAttributes} is equal to another
* {@code Attributes}
* Two {@code Attributes} are equal if they are both instances of
* {@code Attributes},
* treat the case of attribute IDs the same way, and contain the
* same attributes. Each <tt>Attribute</tt> in this <tt>BasicAttributes</tt>
* is checked for equality using <tt>Object.equals()</tt>, which may have
* be overridden by implementations of <tt>Attribute</tt>).
* If a subclass overrides <tt>equals()</tt>,
* it should override <tt>hashCode()</tt>
* as well so that two <tt>Attributes</tt> instances that are equal
* same attributes. Each {@code Attribute} in this {@code BasicAttributes}
* is checked for equality using {@code Object.equals()}, which may have
* be overridden by implementations of {@code Attribute}).
* If a subclass overrides {@code equals()},
* it should override {@code hashCode()}
* as well so that two {@code Attributes} instances that are equal
* have the same hash code.
* @param obj the possibly null object to compare against.
*
@ -259,9 +259,9 @@ public class BasicAttributes implements Attributes {
* The hash code is computed by adding the hash code of
* the attributes of this object. If this BasicAttributes
* ignores case of its attribute IDs, one is added to the hash code.
* If a subclass overrides <tt>hashCode()</tt>,
* it should override <tt>equals()</tt>
* as well so that two <tt>Attributes</tt> instances that are equal
* If a subclass overrides {@code hashCode()},
* it should override {@code equals()}
* as well so that two {@code Attributes} instances that are equal
* have the same hash code.
*
* @return an int representing the hash code of this BasicAttributes instance.

124
jdk/src/java.naming/share/classes/javax/naming/directory/DirContext.java
View File

@ -33,7 +33,7 @@ import javax.naming.*;
* associated with objects, and for searching the directory.
*
* <h1>Names</h1>
* Each name passed as an argument to a <tt>DirContext</tt> method is relative
* Each name passed as an argument to a {@code DirContext} method is relative
* to that context. The empty name is used to name the context itself.
* The name parameter may never be null.
* <p>
@ -47,9 +47,9 @@ import javax.naming.*;
* The second version instead has a link to the first: the same
* documentation applies to both.
* <p>
* See <tt>Context</tt> for a discussion on the interpretation of the
* name argument to the <tt>Context</tt> methods. These same rules
* apply to the name argument to the <tt>DirContext</tt> methods.
* See {@code Context} for a discussion on the interpretation of the
* name argument to the {@code Context} methods. These same rules
* apply to the name argument to the {@code DirContext} methods.
*
* <h1>Attribute Models</h1>
* There are two basic models of what attributes should be
@ -82,7 +82,7 @@ import javax.naming.*;
* within the parent object and associated with the object's name.
*
* <h1>Attribute Type Names</h1>
* In the <tt>getAttributes()</tt> and <tt>search()</tt> methods,
* In the {@code getAttributes()} and {@code search()} methods,
* you can supply the attributes to return by supplying a list of
* attribute names (strings).
* The attributes that you get back might not have the same names as the
@ -120,9 +120,9 @@ import javax.naming.*;
* purposes. An example of operational attributes is the access control
* list for an object.
* <p>
* In the <tt>getAttributes()</tt> and <tt>search()</tt> methods,
* In the {@code getAttributes()} and {@code search()} methods,
* you can specify that all attributes associated with the requested objects
* be returned by supply <tt>null</tt> as the list of attributes to return.
* be returned by supply {@code null} as the list of attributes to return.
* The attributes returned do <em>not</em> include operational attributes.
* In order to retrieve operational attributes, you must name them explicitly.
*
@ -140,13 +140,13 @@ import javax.naming.*;
*
*<h1>Parameters</h1>
*<p>
* An <tt>Attributes</tt>, <tt>SearchControls</tt>, or array object
* An {@code Attributes}, {@code SearchControls}, or array object
* passed as a parameter to any method 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.
* An <tt>Attributes</tt> object returned by any method is owned by
* An {@code Attributes} object returned by any method is owned by
* the caller. The caller may subsequently modify it; the service
* provider will not.
*
@ -254,7 +254,7 @@ public interface DirContext extends Context {
* If attempting to add more than one value to a single-valued attribute,
* throws <code>InvalidAttributeValueException</code>.
* <p>
* The value of this constant is <tt>1</tt>.
* The value of this constant is {@code 1}.
*
* @see ModificationItem
* @see #modifyAttributes
@ -273,7 +273,7 @@ public interface DirContext extends Context {
* attempting to add more than one value to a single-valued attribute,
* throws <code>InvalidAttributeValueException</code>.
* <p>
* The value of this constant is <tt>2</tt>.
* The value of this constant is {@code 2}.
*
* @see ModificationItem
* @see #modifyAttributes
@ -294,7 +294,7 @@ public interface DirContext extends Context {
* Removal of the last value will remove the attribute if the
* attribute is required to have at least one value.
* <p>
* The value of this constant is <tt>3</tt>.
* The value of this constant is {@code 3}.
*
* @see ModificationItem
* @see #modifyAttributes
@ -391,12 +391,12 @@ public interface DirContext extends Context {
/**
* Binds a name to an object, along with associated attributes.
* If <tt>attrs</tt> is null, the resulting binding will have
* the attributes associated with <tt>obj</tt> if <tt>obj</tt> is a
* <tt>DirContext</tt>, and no attributes otherwise.
* If <tt>attrs</tt> is non-null, the resulting binding will have
* <tt>attrs</tt> as its attributes; any attributes associated with
* <tt>obj</tt> are ignored.
* If {@code attrs} is null, the resulting binding will have
* the attributes associated with {@code obj} if {@code obj} is a
* {@code DirContext}, and no attributes otherwise.
* If {@code attrs} is non-null, the resulting binding will have
* {@code attrs} as its attributes; any attributes associated with
* {@code obj} are ignored.
*
* @param name
* the name to bind; may not be empty
@ -438,16 +438,16 @@ public interface DirContext extends Context {
/**
* Binds a name to an object, along with associated attributes,
* overwriting any existing binding.
* If <tt>attrs</tt> is null and <tt>obj</tt> is a <tt>DirContext</tt>,
* the attributes from <tt>obj</tt> are used.
* If <tt>attrs</tt> is null and <tt>obj</tt> is not a <tt>DirContext</tt>,
* If {@code attrs} is null and {@code obj} is a {@code DirContext},
* the attributes from {@code obj} are used.
* If {@code attrs} is null and {@code obj} is not a {@code DirContext},
* any existing attributes associated with the object already bound
* in the directory remain unchanged.
* If <tt>attrs</tt> is non-null, any existing attributes associated with
* the object already bound in the directory are removed and <tt>attrs</tt>
* is associated with the named object. If <tt>obj</tt> is a
* <tt>DirContext</tt> and <tt>attrs</tt> is non-null, the attributes
* of <tt>obj</tt> are ignored.
* If {@code attrs} is non-null, any existing attributes associated with
* the object already bound in the directory are removed and {@code attrs}
* is associated with the named object. If {@code obj} is a
* {@code DirContext} and {@code attrs} is non-null, the attributes
* of {@code obj} are ignored.
*
* @param name
* the name to bind; may not be empty
@ -492,8 +492,8 @@ public interface DirContext extends Context {
* component of the name), and associates the supplied attributes
* with the newly created object.
* All intermediate and target contexts must already exist.
* If <tt>attrs</tt> is null, this method is equivalent to
* <tt>Context.createSubcontext()</tt>.
* If {@code attrs} is null, this method is equivalent to
* {@code Context.createSubcontext()}.
*
* @param name
* the name of the context to create; may not be empty
@ -579,8 +579,8 @@ public interface DirContext extends Context {
* "object class" being referred to here is in the directory sense
* rather than in the Java sense.
* For example, if the named object is a directory object of
* "Person" class, <tt>getSchemaClassDefinition()</tt> would return a
* <tt>DirContext</tt> representing the (directory's) object class
* "Person" class, {@code getSchemaClassDefinition()} would return a
* {@code DirContext} representing the (directory's) object class
* definition of "Person".
*<p>
* The information that can be retrieved from an object class definition
@ -589,13 +589,13 @@ public interface DirContext extends Context {
* Prior to JNDI 1.2, this method
* returned a single schema object representing the class definition of
* the named object.
* Since JNDI 1.2, this method returns a <tt>DirContext</tt> containing
* Since JNDI 1.2, this method returns a {@code DirContext} containing
* all of the named object's class definitions.
*
* @param name
* the name of the object whose object class
* definition is to be retrieved
* @return the <tt>DirContext</tt> containing the named
* @return the {@code DirContext} containing the named
* object's class definitions; never null
*
* @throws OperationNotSupportedException if schema not supported
@ -612,7 +612,7 @@ public interface DirContext extends Context {
* @param name
* the name of the object whose object class
* definition is to be retrieved
* @return the <tt>DirContext</tt> containing the named
* @return the {@code DirContext} containing the named
* object's class definitions; never null
*
* @throws OperationNotSupportedException if schema not supported
@ -656,7 +656,7 @@ public interface DirContext extends Context {
* substring comparison) use the version of the <code>search</code>
* method that takes a filter argument.
* <p>
* When changes are made to this <tt>DirContext</tt>,
* When changes are made to this {@code DirContext},
* the effect on enumerations returned by prior calls to this method
* is undefined.
*<p>
@ -681,8 +681,8 @@ public interface DirContext extends Context {
* all attributes are to be returned;
* an empty array indicates that none are to be returned.
* @return
* a non-null enumeration of <tt>SearchResult</tt> objects.
* Each <tt>SearchResult</tt> contains the attributes
* a non-null enumeration of {@code SearchResult} objects.
* Each {@code SearchResult} contains the attributes
* identified by <code>attributesToReturn</code>
* and the name of the corresponding object, named relative
* to the context named by <code>name</code>.
@ -709,7 +709,7 @@ public interface DirContext extends Context {
* the attributes to search for
* @param attributesToReturn
* the attributes to return
* @return a non-null enumeration of <tt>SearchResult</tt> objects
* @return a non-null enumeration of {@code SearchResult} objects
* @throws NamingException if a naming exception is encountered
*/
public NamingEnumeration<SearchResult>
@ -723,7 +723,7 @@ public interface DirContext extends Context {
* specified set of attributes.
* This method returns all the attributes of such objects.
* It is equivalent to supplying null as
* the <tt>attributesToReturn</tt> parameter to the method
* the {@code attributesToReturn} parameter to the method
* <code>search(Name, Attributes, String[])</code>.
* <br>
* See {@link #search(Name, Attributes, String[])} for a full description.
@ -732,7 +732,7 @@ public interface DirContext extends Context {
* the name of the context to search
* @param matchingAttributes
* the attributes to search for
* @return an enumeration of <tt>SearchResult</tt> objects
* @return an enumeration of {@code SearchResult} objects
* @throws NamingException if a naming exception is encountered
*
* @see #search(Name, Attributes, String[])
@ -750,7 +750,7 @@ public interface DirContext extends Context {
* the name of the context to search
* @param matchingAttributes
* the attributes to search for
* @return an enumeration of <tt>SearchResult</tt> objects
* @return an enumeration of {@code SearchResult} objects
* @throws NamingException if a naming exception is encountered
*/
public NamingEnumeration<SearchResult>
@ -807,8 +807,8 @@ public interface DirContext extends Context {
* attributes. When an operator is not applicable, the exception
* <code>InvalidSearchFilterException</code> is thrown.
* <p>
* The result is returned in an enumeration of <tt>SearchResult</tt>s.
* Each <tt>SearchResult</tt> contains the name of the object
* The result is returned in an enumeration of {@code SearchResult}s.
* Each {@code SearchResult} contains the name of the object
* and other information about the object (see SearchResult).
* The name is either relative to the target context of the search
* (which is named by the <code>name</code> parameter), or
@ -817,8 +817,8 @@ public interface DirContext extends Context {
* <code>cons</code> specifies a search scope of
* <code>SearchControls.OBJECT_SCOPE</code> or
* <code>SearchControls.SUBSTREE_SCOPE</code>), its name is the empty
* string. The <tt>SearchResult</tt> may also contain attributes of the
* matching object if the <tt>cons</tt> argument specified that attributes
* string. The {@code SearchResult} may also contain attributes of the
* matching object if the {@code cons} argument specified that attributes
* be returned.
*<p>
* If the object does not have a requested attribute, that
@ -839,8 +839,8 @@ public interface DirContext extends Context {
* @param cons
* the search controls that control the search. If null,
* the default search controls are used (equivalent
* to <tt>(new SearchControls())</tt>).
* @return an enumeration of <tt>SearchResult</tt>s of
* to {@code (new SearchControls())}).
* @return an enumeration of {@code SearchResult}s of
* the objects that satisfy the filter; never null
*
* @throws InvalidSearchFilterException if the search filter specified is
@ -872,9 +872,9 @@ public interface DirContext extends Context {
* @param cons
* the search controls that control the search. If null,
* the default search controls are used (equivalent
* to <tt>(new SearchControls())</tt>).
* to {@code (new SearchControls())}).
*
* @return an enumeration of <tt>SearchResult</tt>s for
* @return an enumeration of {@code SearchResult}s for
* the objects that satisfy the filter.
* @throws InvalidSearchFilterException if the search filter specified is
* not supported or understood by the underlying directory
@ -935,8 +935,8 @@ public interface DirContext extends Context {
* <code>SearchControls.SUBSTREE_SCOPE</code>),
* its name is the empty string.
*<p>
* The <tt>SearchResult</tt> may also contain attributes of the matching
* object if the <tt>cons</tt> argument specifies that attributes be
* The {@code SearchResult} may also contain attributes of the matching
* object if the {@code cons} argument specifies that attributes be
* returned.
*<p>
* If the object does not have a requested attribute, that
@ -972,17 +972,17 @@ public interface DirContext extends Context {
* @param cons
* the search controls that control the search. If null,
* the default search controls are used (equivalent
* to <tt>(new SearchControls())</tt>).
* @return an enumeration of <tt>SearchResult</tt>s of the objects
* to {@code (new SearchControls())}).
* @return an enumeration of {@code SearchResult}s of the objects
* that satisfy the filter; never null
*
* @throws ArrayIndexOutOfBoundsException if <tt>filterExpr</tt> contains
* @throws ArrayIndexOutOfBoundsException if {@code filterExpr} contains
* <code>{i}</code> expressions where <code>i</code> is outside
* the bounds of the array <code>filterArgs</code>
* @throws InvalidSearchControlsException if <tt>cons</tt> contains
* @throws InvalidSearchControlsException if {@code cons} contains
* invalid settings
* @throws InvalidSearchFilterException if <tt>filterExpr</tt> with
* <tt>filterArgs</tt> represents an invalid search filter
* @throws InvalidSearchFilterException if {@code filterExpr} with
* {@code filterArgs} represents an invalid search filter
* @throws NamingException if a naming exception is encountered
*
* @see #search(Name, Attributes, String[])
@ -1017,17 +1017,17 @@ public interface DirContext extends Context {
* @param cons
* the search controls that control the search. If null,
* the default search controls are used (equivalent
* to <tt>(new SearchControls())</tt>).
* @return an enumeration of <tt>SearchResult</tt>s of the objects
* to {@code (new SearchControls())}).
* @return an enumeration of {@code SearchResult}s of the objects
* that satisfy the filter; never null
*
* @throws ArrayIndexOutOfBoundsException if <tt>filterExpr</tt> contains
* @throws ArrayIndexOutOfBoundsException if {@code filterExpr} contains
* <code>{i}</code> expressions where <code>i</code> is outside
* the bounds of the array <code>filterArgs</code>
* @throws InvalidSearchControlsException if <tt>cons</tt> contains
* @throws InvalidSearchControlsException if {@code cons} contains
* invalid settings
* @throws InvalidSearchFilterException if <tt>filterExpr</tt> with
* <tt>filterArgs</tt> represents an invalid search filter
* @throws InvalidSearchFilterException if {@code filterExpr} with
* {@code filterArgs} represents an invalid search filter
* @throws NamingException if a naming exception is encountered
*/
public NamingEnumeration<SearchResult>

14
jdk/src/java.naming/share/classes/javax/naming/directory/InitialDirContext.java
View File

@ -49,14 +49,14 @@ public class InitialDirContext extends InitialContext implements DirContext {
* Constructs an initial DirContext with the option of not
* initializing it. This may be used by a constructor in
* a subclass when the value of the environment parameter
* is not yet known at the time the <tt>InitialDirContext</tt>
* is not yet known at the time the {@code InitialDirContext}
* constructor is called. The subclass's constructor will
* call this constructor, compute the value of the environment,
* and then call <tt>init()</tt> before returning.
* and then call {@code init()} before returning.
*
* @param lazy
* true means do not initialize the initial DirContext; false
* is equivalent to calling <tt>new InitialDirContext()</tt>
* is equivalent to calling {@code new InitialDirContext()}
* @throws NamingException if a naming exception is encountered
*
* @see InitialContext#init(Hashtable)
@ -69,7 +69,7 @@ public class InitialDirContext extends InitialContext implements DirContext {
/**
* Constructs an initial DirContext.
* No environment properties are supplied.
* Equivalent to <tt>new InitialDirContext(null)</tt>.
* Equivalent to {@code new InitialDirContext(null)}.
*
* @throws NamingException if a naming exception is encountered
*
@ -82,12 +82,12 @@ public class InitialDirContext extends InitialContext implements DirContext {
/**
* Constructs an initial DirContext using the supplied environment.
* Environment properties are discussed in the
* <tt>javax.naming.InitialContext</tt> class description.
* {@code javax.naming.InitialContext} class description.
*
* <p> This constructor will not modify <tt>environment</tt>
* <p> This constructor will not modify {@code environment}
* or save a reference to it, but may save a clone.
* Caller should not modify mutable keys and values in
* <tt>environment</tt> after it has been passed to the constructor.
* {@code environment} after it has been passed to the constructor.
*
* @param environment
* environment used to create the initial DirContext.

14
jdk/src/java.naming/share/classes/javax/naming/directory/SearchControls.java
View File

@ -54,7 +54,7 @@ public class SearchControls implements java.io.Serializable {
* It contains zero element if the named object does not satisfy
* the search filter specified in search().
* <p>
* The value of this constant is <tt>0</tt>.
* The value of this constant is {@code 0}.
*/
public final static int OBJECT_SCOPE = 0;
@ -68,7 +68,7 @@ public class SearchControls implements java.io.Serializable {
* The names of elements in the NamingEnumeration are atomic names
* relative to the named context.
* <p>
* The value of this constant is <tt>1</tt>.
* The value of this constant is {@code 1}.
*/
public final static int ONELEVEL_SCOPE = 1;
/**
@ -90,14 +90,14 @@ public class SearchControls implements java.io.Serializable {
* included in the enumeration with the empty string as
* its name.
* <p>
* The value of this constant is <tt>2</tt>.
* The value of this constant is {@code 2}.
*/
public final static int SUBTREE_SCOPE = 2;
/**
* Contains the scope with which to apply the search. One of
* <tt>ONELEVEL_SCOPE</tt>, <tt>OBJECT_SCOPE</tt>, or
* <tt>SUBTREE_SCOPE</tt>.
* {@code ONELEVEL_SCOPE}, {@code OBJECT_SCOPE}, or
* {@code SUBTREE_SCOPE}.
* @serial
*/
private int searchScope;
@ -117,7 +117,7 @@ public class SearchControls implements java.io.Serializable {
private boolean derefLink;
/**
* Indicates whether object is returned in <tt>SearchResult</tt>.
* Indicates whether object is returned in {@code SearchResult}.
* @serial
*/
private boolean returnObj;
@ -130,7 +130,7 @@ public class SearchControls implements java.io.Serializable {
/**
* Contains the list of attributes to be returned in
* <tt>SearchResult</tt> for each matching entry of search. <tt>null</tt>
* {@code SearchResult} for each matching entry of search. {@code null}
* indicates that all attributes are to be returned.
* @serial
*/

24
jdk/src/java.naming/share/classes/javax/naming/directory/SearchResult.java
View File

@ -53,9 +53,9 @@ public class SearchResult extends Binding {
* Constructs a search result using the result's name, its bound object, and
* its attributes.
*<p>
* <tt>getClassName()</tt> will return the class name of <tt>obj</tt>
* (or null if <tt>obj</tt> is null) unless the class name has been
* explicitly set using <tt>setClassName()</tt>.
* {@code getClassName()} will return the class name of {@code obj}
* (or null if {@code obj} is null) unless the class name has been
* explicitly set using {@code setClassName()}.
*
* @param name The non-null name of the search item. It is relative
* to the <em>target context</em> of the search (which is
@ -76,9 +76,9 @@ public class SearchResult extends Binding {
* Constructs a search result using the result's name, its bound object, and
* its attributes, and whether the name is relative.
*<p>
* <tt>getClassName()</tt> will return the class name of <tt>obj</tt>
* (or null if <tt>obj</tt> is null) unless the class name has been
* explicitly set using <tt>setClassName()</tt>
* {@code getClassName()} will return the class name of {@code obj}
* (or null if {@code obj} is null) unless the class name has been
* explicitly set using {@code setClassName()}
*
* @param name The non-null name of the search item.
* @param obj The object bound to name. Can be null.
@ -106,9 +106,9 @@ public class SearchResult extends Binding {
* named by the first parameter of the <code>search()</code> method)
*
* @param className The possibly null class name of the object
* bound to <tt>name</tt>. If null, the class name of <tt>obj</tt> is
* returned by <tt>getClassName()</tt>. If <tt>obj</tt> is also null,
* <tt>getClassName()</tt> will return null.
* bound to {@code name}. If null, the class name of {@code obj} is
* returned by {@code getClassName()}. If {@code obj} is also null,
* {@code getClassName()} will return null.
* @param obj The object bound to name. Can be null.
* @param attrs The attributes that were requested to be returned with
* this search item. Cannot be null.
@ -127,9 +127,9 @@ public class SearchResult extends Binding {
*
* @param name The non-null name of the search item.
* @param className The possibly null class name of the object
* bound to <tt>name</tt>. If null, the class name of <tt>obj</tt> is
* returned by <tt>getClassName()</tt>. If <tt>obj</tt> is also null,
* <tt>getClassName()</tt> will return null.
* bound to {@code name}. If null, the class name of {@code obj} is
* returned by {@code getClassName()}. If {@code obj} is also null,
* {@code getClassName()} will return null.
* @param obj The object bound to name. Can be null.
* @param attrs The attributes that were requested to be returned with
* this search item. Cannot be null.

22
jdk/src/java.naming/share/classes/javax/naming/directory/package.html
View File

@ -28,7 +28,7 @@ questions.
</head>
<body bgcolor="white">
Extends the <tt>javax.naming</tt> package to provide functionality
Extends the <code>javax.naming</code> package to provide functionality
for accessing directory services.
<p>
@ -47,20 +47,20 @@ objects using specified attributes.
<h4>The Directory Context</h4>
The <tt>DirContext</tt>
The <code>DirContext</code>
interface represents a <em>directory context</em>.
It defines methods for examining and updating attributes associated with a
<em>directory object</em>, or <em>directory entry</em> as it is sometimes
called.
<p>
You use <tt>getAttributes()</tt> to retrieve the attributes
You use <code>getAttributes()</code> to retrieve the attributes
associated with a directory object (for which you supply the name).
Attributes are modified using <tt>modifyAttributes()</tt>.
Attributes are modified using <code>modifyAttributes()</code>.
You can add, replace, or remove attributes and/or attribute values
using this operation.
<p>
<tt>DirContext</tt> also behaves as a naming context
by extending the <tt>Context</tt> interface in the <tt>javax.naming</tt> package.
<code>DirContext</code> also behaves as a naming context
by extending the <code>Context</code> interface in the <code>javax.naming</code> package.
This means that any directory object can also provide
a naming context.
For example, the directory object for a person might contain
@ -69,13 +69,13 @@ a context for naming objects relative to that person
such as his printers and home directory.
<h4>Searches</h4>
<tt>DirContext</tt> contains methods for
<code>DirContext</code> contains methods for
performing content-based searching of the directory.
In the simplest and most common form of usage, the application
specifies a set of attributes--possibly with specific
values--to match, and submits this attribute set, to the
<tt>search()</tt> method.
There are other overloaded forms of <tt>search()</tt>
specifies a set of attributes--possibly with specific
values--to match, and submits this attribute set, to the
<code>search()</code> method.
There are other overloaded forms of <code>search()</code>
that support more sophisticated <em>search filters</em>.

106
jdk/src/java.naming/share/classes/javax/naming/event/EventContext.java
View File

@ -35,7 +35,7 @@ import javax.naming.NamingException;
* events fired when objects named in a context changes.
*
*<h1>Target</h1>
* The name parameter in the <tt>addNamingListener()</tt> methods is referred
* The name parameter in the {@code addNamingListener()} methods is referred
* to as the <em>target</em>. The target, along with the scope, identify
* the object(s) that the listener is interested in.
* It is possible to register interest in a target that does not exist, but
@ -44,23 +44,23 @@ import javax.naming.NamingException;
*<p>
* If a service only supports registration for existing
* targets, an attempt to register for a nonexistent target
* results in a <tt>NameNotFoundException</tt> being thrown as early as possible,
* preferably at the time <tt>addNamingListener()</tt> is called, or if that is
* results in a {@code NameNotFoundException} being thrown as early as possible,
* preferably at the time {@code addNamingListener()} is called, or if that is
* not possible, the listener will receive the exception through the
* <tt>NamingExceptionEvent</tt>.
* {@code NamingExceptionEvent}.
*<p>
* Also, for service providers that only support registration for existing
* targets, when the target that a listener has registered for is
* subsequently removed from the namespace, the listener is notified
* via a <tt>NamingExceptionEvent</tt> (containing a
*<tt>NameNotFoundException</tt>).
* via a {@code NamingExceptionEvent} (containing a
*{@code NameNotFoundException}).
*<p>
* An application can use the method <tt>targetMustExist()</tt> to check
* whether a <tt>EventContext</tt> supports registration
* An application can use the method {@code targetMustExist()} to check
* whether a {@code EventContext} supports registration
* of nonexistent targets.
*
*<h1>Event Source</h1>
* The <tt>EventContext</tt> instance on which you invoke the
* The {@code EventContext} instance on which you invoke the
* registration methods is the <em>event source</em> of the events that are
* (potentially) generated.
* The source is <em>not necessarily</em> the object named by the target.
@ -69,7 +69,7 @@ import javax.naming.NamingException;
* In other words, the target,
* along with the scope parameter, are used to identify
* the object(s) that the listener is interested in, but the event source
* is the <tt>EventContext</tt> instance with which the listener
* is the {@code EventContext} instance with which the listener
* has registered.
*<p>
* For example, suppose a listener makes the following registration:
@ -78,52 +78,52 @@ import javax.naming.NamingException;
* src.addNamingListener("x", SUBTREE_SCOPE, listener);
*</pre></blockquote>
* When an object named "x/y" is subsequently deleted, the corresponding
* <tt>NamingEvent</tt> (<tt>evt</tt>) must contain:
* {@code NamingEvent} ({@code evt}) must contain:
*<blockquote><pre>
* evt.getEventContext() == src
* evt.getOldBinding().getName().equals("x/y")
*</pre></blockquote>
*<p>
* Furthermore, listener registration/deregistration is with
* the <tt>EventContext</tt>
* the {@code EventContext}
* <em>instance</em>, and not with the corresponding object in the namespace.
* If the program intends at some point to remove a listener, then it needs to
* keep a reference to the <tt>EventContext</tt> instance on
* which it invoked <tt>addNamingListener()</tt> (just as
* keep a reference to the {@code EventContext} instance on
* which it invoked {@code addNamingListener()} (just as
* it needs to keep a reference to the listener in order to remove it
* later). It cannot expect to do a <tt>lookup()</tt> and get another instance of
* a <tt>EventContext</tt> on which to perform the deregistration.
* later). It cannot expect to do a {@code lookup()} and get another instance of
* a {@code EventContext} on which to perform the deregistration.
*<h1>Lifetime of Registration</h1>
* A registered listener becomes deregistered when:
*<ul>
*<li>It is removed using <tt>removeNamingListener()</tt>.
*<li>It is removed using {@code removeNamingListener()}.
*<li>An exception is thrown while collecting information about the events.
* That is, when the listener receives a <tt>NamingExceptionEvent</tt>.
*<li><tt>Context.close()</tt> is invoked on the <tt>EventContext</tt>
* That is, when the listener receives a {@code NamingExceptionEvent}.
*<li>{@code Context.close()} is invoked on the {@code EventContext}
* instance with which it has registered.
</ul>
* Until that point, a <tt>EventContext</tt> instance that has outstanding
* Until that point, a {@code EventContext} instance that has outstanding
* listeners will continue to exist and be maintained by the service provider.
*
*<h1>Listener Implementations</h1>
* The registration/deregistration methods accept an instance of
* <tt>NamingListener</tt>. There are subinterfaces of <tt>NamingListener</tt>
* for different of event types of <tt>NamingEvent</tt>.
* For example, the <tt>ObjectChangeListener</tt>
* interface is for the <tt>NamingEvent.OBJECT_CHANGED</tt> event type.
* {@code NamingListener}. There are subinterfaces of {@code NamingListener}
* for different of event types of {@code NamingEvent}.
* For example, the {@code ObjectChangeListener}
* interface is for the {@code NamingEvent.OBJECT_CHANGED} event type.
* To register interest in multiple event types, the listener implementation
* should implement multiple <tt>NamingListener</tt> subinterfaces and use a
* single invocation of <tt>addNamingListener()</tt>.
* should implement multiple {@code NamingListener} subinterfaces and use a
* single invocation of {@code addNamingListener()}.
* In addition to reducing the number of method calls and possibly the code size
* of the listeners, this allows some service providers to optimize the
* registration.
*
*<h1>Threading Issues</h1>
*
* Like <tt>Context</tt> instances in general, instances of
* <tt>EventContext</tt> are not guaranteed to be thread-safe.
* Like {@code Context} instances in general, instances of
* {@code EventContext} are not guaranteed to be thread-safe.
* Care must be taken when multiple threads are accessing the same
* <tt>EventContext</tt> concurrently.
* {@code EventContext} concurrently.
* See the
* <a href=package-summary.html#THREADING>package description</a>
* for more information on threading issues.
@ -138,7 +138,7 @@ public interface EventContext extends Context {
* Constant for expressing interest in events concerning the object named
* by the target.
*<p>
* The value of this constant is <tt>0</tt>.
* The value of this constant is {@code 0}.
*/
public final static int OBJECT_SCOPE = 0;
@ -147,7 +147,7 @@ public interface EventContext extends Context {
* in the context named by the target,
* excluding the context named by the target.
*<p>
* The value of this constant is <tt>1</tt>.
* The value of this constant is {@code 1}.
*/
public final static int ONELEVEL_SCOPE = 1;
@ -156,7 +156,7 @@ public interface EventContext extends Context {
* in the subtree of the object named by the target, including the object
* named by the target.
*<p>
* The value of this constant is <tt>2</tt>.
* The value of this constant is {@code 2}.
*/
public final static int SUBTREE_SCOPE = 2;
@ -167,31 +167,31 @@ public interface EventContext extends Context {
*
* The event source of those events is this context. See the
* class description for a discussion on event source and target.
* See the descriptions of the constants <tt>OBJECT_SCOPE</tt>,
* <tt>ONELEVEL_SCOPE</tt>, and <tt>SUBTREE_SCOPE</tt> to see how
* <tt>scope</tt> affects the registration.
* See the descriptions of the constants {@code OBJECT_SCOPE},
* {@code ONELEVEL_SCOPE}, and {@code SUBTREE_SCOPE} to see how
* {@code scope} affects the registration.
*<p>
* <tt>target</tt> needs to name a context only when <tt>scope</tt> is
* <tt>ONELEVEL_SCOPE</tt>.
* <tt>target</tt> may name a non-context if <tt>scope</tt> is either
* <tt>OBJECT_SCOPE</tt> or <tt>SUBTREE_SCOPE</tt>. Using
* <tt>SUBTREE_SCOPE</tt> for a non-context might be useful,
* for example, if the caller does not know in advance whether <tt>target</tt>
* {@code target} needs to name a context only when {@code scope} is
* {@code ONELEVEL_SCOPE}.
* {@code target} may name a non-context if {@code scope} is either
* {@code OBJECT_SCOPE} or {@code SUBTREE_SCOPE}. Using
* {@code SUBTREE_SCOPE} for a non-context might be useful,
* for example, if the caller does not know in advance whether {@code target}
* is a context and just wants to register interest in the (possibly
* degenerate subtree) rooted at <tt>target</tt>.
* degenerate subtree) rooted at {@code target}.
*<p>
* When the listener is notified of an event, the listener may
* in invoked in a thread other than the one in which
* <tt>addNamingListener()</tt> is executed.
* {@code addNamingListener()} is executed.
* Care must be taken when multiple threads are accessing the same
* <tt>EventContext</tt> concurrently.
* {@code EventContext} concurrently.
* See the
* <a href=package-summary.html#THREADING>package description</a>
* for more information on threading issues.
*
* @param target A nonnull name to be resolved relative to this context.
* @param scope One of <tt>OBJECT_SCOPE</tt>, <tt>ONELEVEL_SCOPE</tt>, or
* <tt>SUBTREE_SCOPE</tt>.
* @param scope One of {@code OBJECT_SCOPE}, {@code ONELEVEL_SCOPE}, or
* {@code SUBTREE_SCOPE}.
* @param l The nonnull listener.
* @exception NamingException If a problem was encountered while
* adding the listener.
@ -204,12 +204,12 @@ public interface EventContext extends Context {
* Adds a listener for receiving naming events fired
* when the object named by the string target name and scope changes.
*
* See the overload that accepts a <tt>Name</tt> for details.
* See the overload that accepts a {@code Name} for details.
*
* @param target The nonnull string name of the object resolved relative
* to this context.
* @param scope One of <tt>OBJECT_SCOPE</tt>, <tt>ONELEVEL_SCOPE</tt>, or
* <tt>SUBTREE_SCOPE</tt>.
* @param scope One of {@code OBJECT_SCOPE}, {@code ONELEVEL_SCOPE}, or
* {@code SUBTREE_SCOPE}.
* @param l The nonnull listener.
* @exception NamingException If a problem was encountered while
* adding the listener.
@ -220,15 +220,15 @@ public interface EventContext extends Context {
/**
* Removes a listener from receiving naming events fired
* by this <tt>EventContext</tt>.
* by this {@code EventContext}.
* The listener may have registered more than once with this
* <tt>EventContext</tt>, perhaps with different target/scope arguments.
* {@code EventContext}, perhaps with different target/scope arguments.
* After this method is invoked, the listener will no longer
* receive events with this <tt>EventContext</tt> instance
* receive events with this {@code EventContext} instance
* as the event source (except for those events already in the process of
* being dispatched).
* If the listener was not, or is no longer, registered with
* this <tt>EventContext</tt> instance, this method does not do anything.
* this {@code EventContext} instance, this method does not do anything.
*
* @param l The nonnull listener.
* @exception NamingException If a problem was encountered while

32
jdk/src/java.naming/share/classes/javax/naming/event/EventDirContext.java
View File

@ -42,17 +42,17 @@ import javax.naming.directory.SearchControls;
* satisfy the filter. However, there might be limitations in the extent
* to which this can be supported by the service provider and underlying
* protocol/service. If the caller submits a filter that cannot be
* supported in this way, <tt>addNamingListener()</tt> throws an
* <tt>InvalidSearchFilterException</tt>.
* supported in this way, {@code addNamingListener()} throws an
* {@code InvalidSearchFilterException}.
*<p>
* See <tt>EventContext</tt> for a description of event source
* See {@code EventContext} for a description of event source
* and target, and information about listener registration/deregistration
* that are also applicable to methods in this interface.
* See the
* <a href=package-summary.html#THREADING>package description</a>
* for information on threading issues.
*<p>
* A <tt>SearchControls</tt> or array object
* A {@code SearchControls} or array object
* passed as a parameter to any method is owned by the caller.
* The service provider will not modify the object or keep a reference to it.
*
@ -64,15 +64,15 @@ import javax.naming.directory.SearchControls;
public interface EventDirContext extends EventContext, DirContext {
/**
* Adds a listener for receiving naming events fired
* when objects identified by the search filter <tt>filter</tt> at
* when objects identified by the search filter {@code filter} at
* the object named by target are modified.
* <p>
* The scope, returningObj flag, and returningAttributes flag from
* the search controls <tt>ctls</tt> are used to control the selection
* the search controls {@code ctls} are used to control the selection
* of objects that the listener is interested in,
* and determines what information is returned in the eventual
* <tt>NamingEvent</tt> object. Note that the requested
* information to be returned might not be present in the <tt>NamingEvent</tt>
* {@code NamingEvent} object. Note that the requested
* information to be returned might not be present in the {@code NamingEvent}
* object if they are unavailable or could not be obtained by the
* service provider or service.
*
@ -91,9 +91,9 @@ public interface EventDirContext extends EventContext, DirContext {
/**
* Adds a listener for receiving naming events fired when
* objects identified by the search filter <tt>filter</tt> at the
* objects identified by the search filter {@code filter} at the
* object named by the string target name are modified.
* See the overload that accepts a <tt>Name</tt> for details of
* See the overload that accepts a {@code Name} for details of
* how this method behaves.
*
* @param target The nonnull string name of the object resolved relative to this context.
@ -111,14 +111,14 @@ public interface EventDirContext extends EventContext, DirContext {
/**
* Adds a listener for receiving naming events fired
* when objects identified by the search filter <tt>filter</tt> and
* when objects identified by the search filter {@code filter} and
* filter arguments at the object named by the target are modified.
* The scope, returningObj flag, and returningAttributes flag from
* the search controls <tt>ctls</tt> are used to control the selection
* the search controls {@code ctls} are used to control the selection
* of objects that the listener is interested in,
* and determines what information is returned in the eventual
* <tt>NamingEvent</tt> object. Note that the requested
* information to be returned might not be present in the <tt>NamingEvent</tt>
* {@code NamingEvent} object. Note that the requested
* information to be returned might not be present in the {@code NamingEvent}
* object if they are unavailable or could not be obtained by the
* service provider or service.
*
@ -138,10 +138,10 @@ public interface EventDirContext extends EventContext, DirContext {
/**
* Adds a listener for receiving naming events fired when
* objects identified by the search filter <tt>filter</tt>
* objects identified by the search filter {@code filter}
* and filter arguments at the
* object named by the string target name are modified.
* See the overload that accepts a <tt>Name</tt> for details of
* See the overload that accepts a {@code Name} for details of
* how this method behaves.
*
* @param target The nonnull string name of the object resolved relative to this context.

22
jdk/src/java.naming/share/classes/javax/naming/event/NamespaceChangeListener.java
View File

@ -28,21 +28,21 @@ package javax.naming.event;
/**
* Specifies the methods that a listener interested in namespace changes
* must implement.
* Specifically, the listener is interested in <tt>NamingEvent</tt>s
* with event types of <tt>OBJECT_ADDED</TT>, <TT>OBJECT_RENAMED</TT>, or
* <TT>OBJECT_REMOVED</TT>.
* Specifically, the listener is interested in {@code NamingEvent}s
* with event types of {@code OBJECT_ADDED, OBJECT_RENAMED}, or
* {@code OBJECT_REMOVED}.
*<p>
* Such a listener must:
*<ol>
*<li>Implement this interface and its methods.
*<li>Implement <tt>NamingListener.namingExceptionThrown()</tt> so that
*<li>Implement {@code NamingListener.namingExceptionThrown()} so that
* it will be notified of exceptions thrown while attempting to
* collect information about the events.
*<li>Register with the source using the source's <tt>addNamingListener()</tt>
*<li>Register with the source using the source's {@code addNamingListener()}
* method.
*</ol>
* A listener that wants to be notified of <tt>OBJECT_CHANGED</tt> event types
* should also implement the <tt>ObjectChangeListener</tt>
* A listener that wants to be notified of {@code OBJECT_CHANGED} event types
* should also implement the {@code ObjectChangeListener}
* interface.
*
* @author Rosanna Lee
@ -60,7 +60,7 @@ public interface NamespaceChangeListener extends NamingListener {
* Called when an object has been added.
*<p>
* The binding of the newly added object can be obtained using
* <tt>evt.getNewBinding()</tt>.
* {@code evt.getNewBinding()}.
* @param evt The nonnull event.
* @see NamingEvent#OBJECT_ADDED
*/
@ -70,7 +70,7 @@ public interface NamespaceChangeListener extends NamingListener {
* Called when an object has been removed.
*<p>
* The binding of the newly removed object can be obtained using
* <tt>evt.getOldBinding()</tt>.
* {@code evt.getOldBinding()}.
* @param evt The nonnull event.
* @see NamingEvent#OBJECT_REMOVED
*/
@ -80,8 +80,8 @@ public interface NamespaceChangeListener extends NamingListener {
* Called when an object has been renamed.
*<p>
* The binding of the renamed object can be obtained using
* <tt>evt.getNewBinding()</tt>. Its old binding (before the rename)
* can be obtained using <tt>evt.getOldBinding()</tt>.
* {@code evt.getNewBinding()}. Its old binding (before the rename)
* can be obtained using {@code evt.getOldBinding()}.
* One of these may be null if the old/new binding was outside the
* scope in which the listener has registered interest.
* @param evt The nonnull event.

70
jdk/src/java.naming/share/classes/javax/naming/event/NamingEvent.java
View File

@ -30,9 +30,9 @@ import javax.naming.Binding;
/**
* This class represents an event fired by a naming/directory service.
*<p>
* The <tt>NamingEvent</tt>'s state consists of
* The {@code NamingEvent}'s state consists of
* <ul>
* <li>The event source: the <tt>EventContext</tt> which fired this event.
* <li>The event source: the {@code EventContext} which fired this event.
* <li>The event type.
* <li>The new binding: information about the object after the change.
* <li>The old binding: information about the object before the change.
@ -41,24 +41,24 @@ import javax.naming.Binding;
* information.
* </ul>
* <p>
* Note that the event source is always the same <tt>EventContext</tt>
* Note that the event source is always the same {@code EventContext}
* <em>instance</em> that the listener has registered with.
* Furthermore, the names of the bindings in
* the <tt>NamingEvent</tt> are always relative to that instance.
* the {@code NamingEvent} are always relative to that instance.
* For example, suppose a listener makes the following registration:
*<blockquote><pre>
* NamespaceChangeListener listener = ...;
* src.addNamingListener("x", SUBTREE_SCOPE, listener);
*</pre></blockquote>
* When an object named "x/y" is subsequently deleted, the corresponding
* <tt>NamingEvent</tt> (<tt>evt</tt>) must contain:
* {@code NamingEvent} ({@code evt}) must contain:
*<blockquote><pre>
* evt.getEventContext() == src
* evt.getOldBinding().getName().equals("x/y")
*</pre></blockquote>
*
* Care must be taken when multiple threads are accessing the same
* <tt>EventContext</tt> concurrently.
* {@code EventContext} concurrently.
* See the
* <a href=package-summary.html#THREADING>package description</a>
* for more information on threading issues.
@ -73,13 +73,13 @@ import javax.naming.Binding;
public class NamingEvent extends java.util.EventObject {
/**
* Naming event type for indicating that a new object has been added.
* The value of this constant is <tt>0</tt>.
* The value of this constant is {@code 0}.
*/
public static final int OBJECT_ADDED = 0;
/**
* Naming event type for indicating that an object has been removed.
* The value of this constant is <tt>1</tt>.
* The value of this constant is {@code 1}.
*/
public static final int OBJECT_REMOVED = 1;
@ -90,7 +90,7 @@ public class NamingEvent extends java.util.EventObject {
* be implemented by adding a binding with the new name and removing
* the old binding.
*<p>
* The old/new binding in <tt>NamingEvent</tt> may be null if the old
* The old/new binding in {@code NamingEvent} may be null if the old
* name or new name is outside of the scope for which the listener
* has registered.
*<p>
@ -102,7 +102,7 @@ public class NamingEvent extends java.util.EventObject {
* corresponding provider might not be able to prevent those
* notifications from being propagated to the listeners.
*<p>
* The value of this constant is <tt>2</tt>.
* The value of this constant is {@code 2}.
*/
public static final int OBJECT_RENAMED = 2;
@ -114,7 +114,7 @@ public class NamingEvent extends java.util.EventObject {
* be implemented by first removing the old binding and adding
* a new binding containing the same name but a different object.
*<p>
* The value of this constant is <tt>3</tt>.
* The value of this constant is {@code 3}.
*/
public static final int OBJECT_CHANGED = 3;
@ -147,16 +147,16 @@ public class NamingEvent extends java.util.EventObject {
protected Binding newBinding;
/**
* Constructs an instance of <tt>NamingEvent</tt>.
* Constructs an instance of {@code NamingEvent}.
*<p>
* The names in <tt>newBd</tt> and <tt>oldBd</tt> are to be resolved relative
* to the event source <tt>source</tt>.
* The names in {@code newBd} and {@code oldBd} are to be resolved relative
* to the event source {@code source}.
*
* For an <tt>OBJECT_ADDED</tt> event type, <tt>newBd</tt> must not be null.
* For an <tt>OBJECT_REMOVED</tt> event type, <tt>oldBd</tt> must not be null.
* For an <tt>OBJECT_CHANGED</tt> event type, <tt>newBd</tt> and
* <tt>oldBd</tt> must not be null. For an <tt>OBJECT_RENAMED</tt> event type,
* one of <tt>newBd</tt> or <tt>oldBd</tt> may be null if the new or old
* For an {@code OBJECT_ADDED} event type, {@code newBd} must not be null.
* For an {@code OBJECT_REMOVED} event type, {@code oldBd} must not be null.
* For an {@code OBJECT_CHANGED} event type, {@code newBd} and
* {@code oldBd} must not be null. For an {@code OBJECT_RENAMED} event type,
* one of {@code newBd} or {@code oldBd} may be null if the new or old
* binding is outside of the scope for which the listener has registered.
*
* @param source The non-null context that fired this event.
@ -192,13 +192,13 @@ public class NamingEvent extends java.util.EventObject {
/**
* Retrieves the event source that fired this event.
* This returns the same object as <tt>EventObject.getSource()</tt>.
* This returns the same object as {@code EventObject.getSource()}.
*<p>
* If the result of this method is used to access the
* event source, for example, to look up the object or get its attributes,
* then it needs to be locked because implementations of <tt>Context</tt>
* then it needs to be locked because implementations of {@code Context}
* are not guaranteed to be thread-safe
* (and <tt>EventContext</tt> is a subinterface of <tt>Context</tt>).
* (and {@code EventContext} is a subinterface of {@code Context}).
* See the
* <a href=package-summary.html#THREADING>package description</a>
* for more information on threading issues.
@ -213,16 +213,16 @@ public class NamingEvent extends java.util.EventObject {
* Retrieves the binding of the object before the change.
*<p>
* The binding must be nonnull if the object existed before the change
* relative to the source context (<tt>getEventContext()</tt>).
* That is, it must be nonnull for <tt>OBJECT_REMOVED</tt> and
* <tt>OBJECT_CHANGED</tt>.
* For <tt>OBJECT_RENAMED</tt>, it is null if the object before the rename
* relative to the source context ({@code getEventContext()}).
* That is, it must be nonnull for {@code OBJECT_REMOVED} and
* {@code OBJECT_CHANGED}.
* For {@code OBJECT_RENAMED}, it is null if the object before the rename
* is outside of the scope for which the listener has registered interest;
* it is nonnull if the object is inside the scope before the rename.
*<p>
* The name in the binding is to be resolved relative
* to the event source <tt>getEventContext()</tt>.
* The object returned by <tt>Binding.getObject()</tt> may be null if
* to the event source {@code getEventContext()}.
* The object returned by {@code Binding.getObject()} may be null if
* such information is unavailable.
*
* @return The possibly null binding of the object before the change.
@ -235,16 +235,16 @@ public class NamingEvent extends java.util.EventObject {
* Retrieves the binding of the object after the change.
*<p>
* The binding must be nonnull if the object existed after the change
* relative to the source context (<tt>getEventContext()</tt>).
* That is, it must be nonnull for <tt>OBJECT_ADDED</tt> and
* <tt>OBJECT_CHANGED</tt>. For <tt>OBJECT_RENAMED</tt>,
* relative to the source context ({@code getEventContext()}).
* That is, it must be nonnull for {@code OBJECT_ADDED} and
* {@code OBJECT_CHANGED}. For {@code OBJECT_RENAMED},
* it is null if the object after the rename is outside the scope for
* which the listener registered interest; it is nonnull if the object
* is inside the scope after the rename.
*<p>
* The name in the binding is to be resolved relative
* to the event source <tt>getEventContext()</tt>.
* The object returned by <tt>Binding.getObject()</tt> may be null if
* to the event source {@code getEventContext()}.
* The object returned by {@code Binding.getObject()} may be null if
* such information is unavailable.
*
* @return The possibly null binding of the object after the change.
@ -268,8 +268,8 @@ public class NamingEvent extends java.util.EventObject {
* Invokes the appropriate listener method on this event.
* The default implementation of
* this method handles the following event types:
* <tt>OBJECT_ADDED</TT>, <TT>OBJECT_REMOVED</TT>,
* <TT>OBJECT_RENAMED</TT>, <TT>OBJECT_CHANGED</TT>.
* {@code OBJECT_ADDED, OBJECT_REMOVED,
* OBJECT_RENAMED, OBJECT_CHANGED}.
*<p>
* The listener method is executed in the same thread
* as this method. See the

18
jdk/src/java.naming/share/classes/javax/naming/event/NamingExceptionEvent.java
View File

@ -30,9 +30,9 @@ import javax.naming.NamingException;
/**
* This class represents an event fired when the procedures/processes
* used to collect information for notifying listeners of
* <tt>NamingEvent</tt>s threw a <tt>NamingException</tt>.
* {@code NamingEvent}s threw a {@code NamingException}.
* This can happen, for example, if the server which the listener is using
* aborts subsequent to the <tt>addNamingListener()</tt> call.
* aborts subsequent to the {@code addNamingListener()} call.
*
* @author Rosanna Lee
* @author Scott Seligman
@ -50,12 +50,12 @@ public class NamingExceptionEvent extends java.util.EventObject {
private NamingException exception;
/**
* Constructs an instance of <tt>NamingExceptionEvent</tt> using
* the context in which the <tt>NamingException</tt> was thrown and the exception
* Constructs an instance of {@code NamingExceptionEvent} using
* the context in which the {@code NamingException} was thrown and the exception
* that was thrown.
*
* @param source The non-null context in which the exception was thrown.
* @param exc The non-null <tt>NamingException</tt> that was thrown.
* @param exc The non-null {@code NamingException} that was thrown.
*
*/
public NamingExceptionEvent(EventContext source, NamingException exc) {
@ -72,16 +72,16 @@ public class NamingExceptionEvent extends java.util.EventObject {
}
/**
* Retrieves the <tt>EventContext</tt> that fired this event.
* This returns the same object as <tt>EventObject.getSource()</tt>.
* @return The non-null <tt>EventContext</tt> that fired this event.
* Retrieves the {@code EventContext} that fired this event.
* This returns the same object as {@code EventObject.getSource()}.
* @return The non-null {@code EventContext} that fired this event.
*/
public EventContext getEventContext() {
return (EventContext)getSource();
}
/**
* Invokes the <tt>namingExceptionThrown()</tt> method on
* Invokes the {@code namingExceptionThrown()} method on
* a listener using this event.
* @param listener The non-null naming listener on which to invoke
* the method.

18
jdk/src/java.naming/share/classes/javax/naming/event/NamingListener.java
View File

@ -27,22 +27,22 @@ package javax.naming.event;
/**
* This interface is the root of listener interfaces that
* handle <tt>NamingEvent</tt>s.
* handle {@code NamingEvent}s.
* It does not make sense for a listener to implement just this interface.
* A listener typically implements a subinterface of <tt>NamingListener</tt>,
* such as <tt>ObjectChangeListener</tt> or <tt>NamespaceChangeListener</tt>.
* A listener typically implements a subinterface of {@code NamingListener},
* such as {@code ObjectChangeListener} or {@code NamespaceChangeListener}.
*<p>
* This interface contains a single method, <tt>namingExceptionThrown()</tt>,
* This interface contains a single method, {@code namingExceptionThrown()},
* that must be implemented so that the listener can be notified of
* exceptions that are thrown (by the service provider) while gathering
* information about the events that they're interested in.
* When this method is invoked, the listener has been automatically deregistered
* from the <tt>EventContext</tt> with which it has registered.
* from the {@code EventContext} with which it has registered.
*<p>
* For example, suppose a listener implements <tt>ObjectChangeListener</tt> and
* registers with a <tt>EventContext</tt>.
* For example, suppose a listener implements {@code ObjectChangeListener} and
* registers with a {@code EventContext}.
* Then, if the connection to the server is subsequently broken,
* the listener will receive a <tt>NamingExceptionEvent</tt> and may
* the listener will receive a {@code NamingExceptionEvent} and may
* take some corrective action, such as notifying the user of the application.
*
* @author Rosanna Lee
@ -57,7 +57,7 @@ package javax.naming.event;
public interface NamingListener extends java.util.EventListener {
/**
* Called when a naming exception is thrown while attempting
* to fire a <tt>NamingEvent</tt>.
* to fire a {@code NamingEvent}.
*
* @param evt The nonnull event.
*/

22
jdk/src/java.naming/share/classes/javax/naming/event/ObjectChangeListener.java
View File

@ -26,27 +26,27 @@
package javax.naming.event;
/**
* Specifies the method that a listener of a <tt>NamingEvent</tt>
* with event type of <tt>OBJECT_CHANGED</tt> must implement.
* Specifies the method that a listener of a {@code NamingEvent}
* with event type of {@code OBJECT_CHANGED} must implement.
*<p>
* An <tt>OBJECT_CHANGED</tt> event type is fired when (the contents of)
* An {@code OBJECT_CHANGED} event type is fired when (the contents of)
* an object has changed. This might mean that its attributes have been modified,
* added, or removed, and/or that the object itself has been replaced.
* How the object has changed can be determined by examining the
* <tt>NamingEvent</tt>'s old and new bindings.
* {@code NamingEvent}'s old and new bindings.
*<p>
* A listener interested in <tt>OBJECT_CHANGED</tt> event types must:
* A listener interested in {@code OBJECT_CHANGED} event types must:
*<ol>
*
*<li>Implement this interface and its method (<tt>objectChanged()</tt>)
*<li>Implement <tt>NamingListener.namingExceptionThrown()</tt> so that
*<li>Implement this interface and its method ({@code objectChanged()})
*<li>Implement {@code NamingListener.namingExceptionThrown()} so that
* it will be notified of exceptions thrown while attempting to
* collect information about the events.
*<li>Register with the source using the source's <tt>addNamingListener()</tt>
*<li>Register with the source using the source's {@code addNamingListener()}
* method.
*</ol>
* A listener that wants to be notified of namespace change events
* should also implement the <tt>NamespaceChangeListener</tt>
* should also implement the {@code NamespaceChangeListener}
* interface.
*
* @author Rosanna Lee
@ -64,8 +64,8 @@ public interface ObjectChangeListener extends NamingListener {
* Called when an object has been changed.
*<p>
* The binding of the changed object can be obtained using
* <tt>evt.getNewBinding()</tt>. Its old binding (before the change)
* can be obtained using <tt>evt.getOldBinding()</tt>.
* {@code evt.getNewBinding()}. Its old binding (before the change)
* can be obtained using {@code evt.getOldBinding()}.
* @param evt The nonnull naming event.
* @see NamingEvent#OBJECT_CHANGED
*/

24
jdk/src/java.naming/share/classes/javax/naming/event/package.html
View File

@ -42,21 +42,21 @@ already deployed ones--can be accessed in a common way.
<h4>Naming Events</h4>
<p>
This package defines a <tt>NamingEvent</tt> class to represent an event
This package defines a <code>NamingEvent</code> class to represent an event
that is generated by a naming/directory service.
It also defines subinterfaces of <tt>Context</tt> and <tt>DirContext</tt>,
called <tt>EventContext</tt> and <tt>EventDirContext</tt>,
It also defines subinterfaces of <code>Context</code> and <code>DirContext</code>,
called <code>EventContext</code> and <code>EventDirContext</code>,
through which applications can register their interest in events
fired by the context.
<p>
<tt>NamingEvent</tt> represents an event that occurs in a
<code>NamingEvent</code> represents an event that occurs in a
naming or directory service. There are two categories of naming events:
<ul>
<li>Those that affect the namespace (add/remove/rename an object)
<li>Those that affect the objects' contents.
</ul>
Each category of events is handled by a corresponding listener:
<tt>NamespaceChangeListener</tt>, <tt>ObjectChangeListener</tt>.
<code>NamespaceChangeListener</code>, <code>ObjectChangeListener</code>.
<p>
An application, for example, can register its interest in changes to
objects in a context as follows:
@ -82,19 +82,19 @@ class ChangeHandler implements ObjectChangeListener {
<h4>Threading Issues</h4>
When an event is dispatched to a listener, the listener method (such
as <tt>objectChanged()</tt>) may be executed in a thread other than the
one in which the call to <tt>addNamingListener()</tt> was executed.
as <code>objectChanged()</code>) may be executed in a thread other than the
one in which the call to <code>addNamingListener()</code> was executed.
The choice of which thread to use is made by the service provider.
When an event is dispatched to multiple listeners, the service provider
may choose (and is generally encouraged) to execute the listener methods
concurrently in separate threads.
<p>
When a listener instance invokes <tt>NamingEvent.getEventContext()</tt>,
When a listener instance invokes <code>NamingEvent.getEventContext()</code>,
it must take into account the possibility that other threads will be
working with that context concurrently. Likewise, when a listener is
registered via <tt>addNamingListener()</tt>, the registering thread
registered via <code>addNamingListener()</code>, the registering thread
must take into account the likely possibility that the service provider
will later invoke the listeners in newly-created threads. As <tt>Context</tt>
will later invoke the listeners in newly-created threads. As <code>Context</code>
instances are not guaranteed to be thread-safe in general, all context
operations must be synchronized as needed.
@ -107,9 +107,9 @@ to make a request to the server to register interest in changes
on the server that will eventually be translated into events.
If an exception occurs that prevents information about the events from
being collected, the listener will never be notified of the events.
When such an exception occurs, a <tt>NamingExceptionEvent</tt> is
When such an exception occurs, a <code>NamingExceptionEvent</code> is
fired to notify the listener. The listener's
<tt>namingExceptionThrown()</tt> method is invoked, as shown in the
<code>namingExceptionThrown()</code> method is invoked, as shown in the
sample code above,
and the listener is automatically deregistered.

2
jdk/src/java.naming/share/classes/javax/naming/ldap/BasicControl.java
View File

@ -26,7 +26,7 @@
package javax.naming.ldap;
/**
* This class provides a basic implementation of the <tt>Control</tt>
* This class provides a basic implementation of the {@code Control}
* interface. It represents an LDAPv3 Control as defined in
* <a href="http://www.ietf.org/rfc/rfc2251.txt">RFC 2251</a>.
*

6
jdk/src/java.naming/share/classes/javax/naming/ldap/Control.java
View File

@ -52,13 +52,13 @@ package javax.naming.ldap;
public interface Control extends java.io.Serializable {
/**
* Indicates a critical control.
* The value of this constant is <tt>true</tt>.
* The value of this constant is {@code true}.
*/
public static final boolean CRITICAL = true;
/**
* Indicates a non-critical control.
* The value of this constant is <tt>false</tt>.
* The value of this constant is {@code false}.
*/
public static final boolean NONCRITICAL = false;
@ -75,7 +75,7 @@ public interface Control extends java.io.Serializable {
* In other words, if the server receives a critical control
* that it does not support, regardless of whether the control
* makes sense for the operation, the operation will not be performed
* and an <tt>OperationNotSupportedException</tt> will be thrown.
* and an {@code OperationNotSupportedException} will be thrown.
* @return true if this control is critical; false otherwise.
*/
public boolean isCritical();

22
jdk/src/java.naming/share/classes/javax/naming/ldap/ControlFactory.java
View File

@ -65,7 +65,7 @@ public abstract class ControlFactory {
* Without this mechanism, the provider would be returning
* controls that only contained data in BER encoded format.
*<p>
* Typically, <tt>ctl</tt> is a "basic" control containing
* Typically, {@code ctl} is a "basic" control containing
* BER encoded data. The factory is used to create a specialized
* control implementation, usually by decoding the BER encoded data,
* that provides methods to access that data in a type-safe and friendly
@ -80,14 +80,14 @@ public abstract class ControlFactory {
* it is the only intended factory and that no other control factories
* should be tried. This might happen, for example, if the BER data
* in the control does not match what is expected of a control with
* the given OID. Since this method throws <tt>NamingException</tt>,
* the given OID. Since this method throws {@code NamingException},
* any other internally generated exception that should be propagated
* must be wrapped inside a <tt>NamingException</tt>.
* must be wrapped inside a {@code NamingException}.
*
* @param ctl A non-null control.
*
* @return A possibly null Control.
* @exception NamingException If <tt>ctl</tt> contains invalid data that prevents it
* @exception NamingException If {@code ctl} contains invalid data that prevents it
* from being used to create a control. A factory should only throw
* an exception if it knows how to produce the control (identified by the OID)
* but is unable to because of, for example invalid BER data.
@ -100,14 +100,14 @@ public abstract class ControlFactory {
* The following rule is used to create the control:
*<ul>
* <li> Use the control factories specified in
* the <tt>LdapContext.CONTROL_FACTORIES</tt> property of the
* the {@code LdapContext.CONTROL_FACTORIES} property of the
* environment, and of the provider resource file associated with
* <tt>ctx</tt>, in that order.
* {@code ctx}, in that order.
* The value of this property is a colon-separated list of factory
* class names that are tried in order, and the first one that succeeds
* in creating the control is the one used.
* If none of the factories can be loaded,
* return <code>ctl</code>.
* return {@code ctl}.
* If an exception is encountered while creating the control, the
* exception is passed up to the caller.
*</ul>
@ -119,9 +119,9 @@ public abstract class ControlFactory {
* @param ctx The possibly null context in which the control is being created.
* If null, no such information is available.
* @param env The possibly null environment of the context. This is used
* to find the value of the <tt>LdapContext.CONTROL_FACTORIES</tt> property.
* @return A control object created using <code>ctl</code>; or
* <code>ctl</code> if a control object cannot be created using
* to find the value of the {@code LdapContext.CONTROL_FACTORIES} property.
* @return A control object created using {@code ctl}; or
* {@code ctl} if a control object cannot be created using
* the algorithm described above.
* @exception NamingException if a naming exception was encountered
* while attempting to create the control object.
@ -129,7 +129,7 @@ public abstract class ControlFactory {
* exception, it is propagated up to the caller.
* If an error was encountered while loading
* and instantiating the factory and object classes, the exception
* is wrapped inside a <tt>NamingException</tt> and then rethrown.
* is wrapped inside a {@code NamingException} and then rethrown.
*/
public static Control getControlInstance(Control ctl, Context ctx,
Hashtable<?,?> env)

6
jdk/src/java.naming/share/classes/javax/naming/ldap/ExtendedRequest.java
View File

@ -43,7 +43,7 @@ import javax.naming.NamingException;
* the classes that implement this interface, supplying them with
* any information required for a particular extended operation request.
* It would then pass such a class as an argument to the
* <tt>LdapContext.extendedOperation()</tt> method for performing the
* {@code LdapContext.extendedOperation()} method for performing the
* LDAPv3 extended operation.
*<p>
* For example, suppose the LDAP server supported a 'get time' extended operation.
@ -90,7 +90,7 @@ public interface ExtendedRequest extends java.io.Serializable {
* Retrieves the object identifier of the request.
*
* @return The non-null object identifier string representing the LDAP
* <tt>ExtendedRequest.requestName</tt> component.
* {@code ExtendedRequest.requestName} component.
*/
public String getID();
@ -104,7 +104,7 @@ public interface ExtendedRequest extends java.io.Serializable {
* put into the extended operation to be sent to the LDAP server.
*
* @return A possibly null byte array representing the ASN.1 BER encoded
* contents of the LDAP <tt>ExtendedRequest.requestValue</tt>
* contents of the LDAP {@code ExtendedRequest.requestValue}
* component.
* @exception IllegalStateException If the encoded value cannot be retrieved
* because the request contains insufficient or invalid data/state.

4
jdk/src/java.naming/share/classes/javax/naming/ldap/ExtendedResponse.java
View File

@ -78,7 +78,7 @@ public interface ExtendedResponse extends java.io.Serializable {
* If the server does not send it, the response will contain no ID (i.e. null).
*
* @return A possibly null object identifier string representing the LDAP
* <tt>ExtendedResponse.responseName</tt> component.
* {@code ExtendedResponse.responseName} component.
*/
public String getID();
@ -90,7 +90,7 @@ public interface ExtendedResponse extends java.io.Serializable {
* the response value. It does not include the response OID.
*
* @return A possibly null byte array representing the ASN.1 BER encoded
* contents of the LDAP <tt>ExtendedResponse.response</tt>
* contents of the LDAP {@code ExtendedResponse.response}
* component.
*/
public byte[] getEncodedValue();

4
jdk/src/java.naming/share/classes/javax/naming/ldap/HasControls.java
View File

@ -60,10 +60,10 @@ import javax.naming.NamingException;
public interface HasControls {
/**
* Retrieves an array of <tt>Control</tt>s from the object that
* Retrieves an array of {@code Control}s from the object that
* implements this interface. It is null if there are no controls.
*
* @return A possibly null array of <tt>Control</tt> objects.
* @return A possibly null array of {@code Control} objects.
* @throws NamingException If cannot return controls due to an error.
*/
public Control[] getControls() throws NamingException;

30
jdk/src/java.naming/share/classes/javax/naming/ldap/InitialLdapContext.java
View File

@ -34,24 +34,24 @@ import java.util.Hashtable;
* This class is the starting context for performing
* LDAPv3-style extended operations and controls.
*<p>
* See <tt>javax.naming.InitialContext</tt> and
* <tt>javax.naming.InitialDirContext</tt> for details on synchronization,
* See {@code javax.naming.InitialContext} and
* {@code javax.naming.InitialDirContext} for details on synchronization,
* and the policy for how an initial context is created.
*
* <h1>Request Controls</h1>
* When you create an initial context (<tt>InitialLdapContext</tt>),
* When you create an initial context ({@code InitialLdapContext}),
* you can specify a list of request controls.
* These controls will be used as the request controls for any
* implicit LDAP "bind" operation performed by the context or contexts
* derived from the context. These are called <em>connection request controls</em>.
* Use <tt>getConnectControls()</tt> to get a context's connection request
* Use {@code getConnectControls()} to get a context's connection request
* controls.
*<p>
* The request controls supplied to the initial context constructor
* are <em>not</em> used as the context request controls
* for subsequent context operations such as searches and lookups.
* Context request controls are set and updated by using
* <tt>setRequestControls()</tt>.
* {@code setRequestControls()}.
*<p>
* As shown, there can be two different sets of request controls
* associated with a context: connection request controls and context
@ -67,14 +67,14 @@ import java.util.Hashtable;
* Controls[] respCtls = lctx.getResponseControls();
*</pre></blockquote>
* It specifies first the critical controls for creating the initial context
* (<tt>critConnCtls</tt>), and then sets the context's request controls
* (<tt>critModCtls</tt>) for the context operation. If for some reason
* <tt>lctx</tt> needs to reconnect to the server, it will use
* <tt>critConnCtls</tt>. See the <tt>LdapContext</tt> interface for
* ({@code critConnCtls}), and then sets the context's request controls
* ({@code critModCtls}) for the context operation. If for some reason
* {@code lctx} needs to reconnect to the server, it will use
* {@code critConnCtls}. See the {@code LdapContext} interface for
* more discussion about request controls.
*<p>
* Service provider implementors should read the "Service Provider" section
* in the <tt>LdapContext</tt> class description for implementation details.
* in the {@code LdapContext} class description for implementation details.
*
* @author Rosanna Lee
* @author Scott Seligman
@ -94,7 +94,7 @@ public class InitialLdapContext extends InitialDirContext implements LdapContext
/**
* Constructs an initial context using no environment properties or
* connection request controls.
* Equivalent to <tt>new InitialLdapContext(null, null)</tt>.
* Equivalent to {@code new InitialLdapContext(null, null)}.
*
* @throws NamingException if a naming exception is encountered
*/
@ -105,15 +105,15 @@ public class InitialLdapContext extends InitialDirContext implements LdapContext
/**
* Constructs an initial context
* using environment properties and connection request controls.
* See <tt>javax.naming.InitialContext</tt> for a discussion of
* See {@code javax.naming.InitialContext} for a discussion of
* environment properties.
*
* <p> This constructor will not modify its parameters or
* save references to them, but may save a clone or copy.
* Caller should not modify mutable keys and values in
* <tt>environment</tt> after it has been passed to the constructor.
* {@code environment} after it has been passed to the constructor.
*
* <p> <tt>connCtls</tt> is used as the underlying context instance's
* <p> {@code connCtls} is used as the underlying context instance's
* connection request controls. See the class description
* for details.
*
@ -159,7 +159,7 @@ public class InitialLdapContext extends InitialDirContext implements LdapContext
*
* @return The non-null cached initial context.
* @exception NotContextException If the initial context is not an
* instance of <tt>LdapContext</tt>.
* instance of {@code LdapContext}.
* @exception NamingException If a naming exception was encountered.
*/
private LdapContext getDefaultLdapInitCtx() throws NamingException{

94
jdk/src/java.naming/share/classes/javax/naming/ldap/LdapContext.java
View File

@ -35,7 +35,7 @@ import java.util.Hashtable;
* extended operations.
*
* For applications that do not require such controls or extended
* operations, the more generic <tt>javax.naming.directory.DirContext</tt>
* operations, the more generic {@code javax.naming.directory.DirContext}
* should be used instead.
*
* <h3>Usage Details About Controls</h3>
@ -44,7 +44,7 @@ import java.util.Hashtable;
* At a high level, this support allows a user
* program to set request controls for LDAP operations that are executed
* in the course of the user program's invocation of
* <tt>Context</tt>/<tt>DirContext</tt>
* {@code Context}/{@code DirContext}
* methods, and read response controls resulting from LDAP operations.
* At the implementation level, there are some details that developers of
* both the user program and service providers need to understand in order
@ -78,60 +78,60 @@ import java.util.Hashtable;
* <h4>Context Request Controls</h4>
* There are two ways in which a context instance gets its request controls:
* <ol>
* <li><tt>ldapContext.newInstance(<strong>reqCtls</strong>)</tt>
* <li><tt>ldapContext.setRequestControls(<strong>reqCtls</strong>)</tt>
* <li><code>ldapContext.newInstance(<strong>reqCtls</strong>)</code>
* <li><code>ldapContext.setRequestControls(<strong>reqCtls</strong>)</code>
* </ol>
* where <tt>ldapContext</tt> is an instance of <tt>LdapContext</tt>.
* Specifying <tt>null</tt> or an empty array for <tt>reqCtls</tt>
* where {@code ldapContext} is an instance of {@code LdapContext}.
* Specifying {@code null} or an empty array for {@code reqCtls}
* means no request controls.
* <tt>newInstance()</tt> creates a new instance of a context using
* <tt>reqCtls</tt>, while <tt>setRequestControls()</tt>
* updates an existing context instance's request controls to <tt>reqCtls</tt>.
* {@code newInstance()} creates a new instance of a context using
* {@code reqCtls}, while {@code setRequestControls()}
* updates an existing context instance's request controls to {@code reqCtls}.
* <p>
* Unlike environment properties, request controls of a context instance
* <em>are not inherited</em> by context instances that are derived from
* it. Derived context instances have <tt>null</tt> as their context
* it. Derived context instances have {@code null} as their context
* request controls. You must set the request controls of a derived context
* instance explicitly using <tt>setRequestControls()</tt>.
* instance explicitly using {@code setRequestControls()}.
* <p>
* A context instance's request controls are retrieved using
* the method <tt>getRequestControls()</tt>.
* the method {@code getRequestControls()}.
*
* <h4>Connection Request Controls</h4>
* There are three ways in which connection request controls are set:
* <ol>
* <li><tt>
* new InitialLdapContext(env, <strong>connCtls</strong>)</tt>
* <li><tt>refException.getReferralContext(env, <strong>connCtls</strong>)</tt>
* <li><tt>ldapContext.reconnect(<strong>connCtls</strong>);</tt>
* <li><code>
* new InitialLdapContext(env, <strong>connCtls</strong>)</code>
* <li><code>refException.getReferralContext(env, <strong>connCtls</strong>)</code>
* <li><code>ldapContext.reconnect(<strong>connCtls</strong>);</code>
* </ol>
* where <tt>refException</tt> is an instance of
* <tt>LdapReferralException</tt>, and <tt>ldapContext</tt> is an
* instance of <tt>LdapContext</tt>.
* Specifying <tt>null</tt> or an empty array for <tt>connCtls</tt>
* where {@code refException} is an instance of
* {@code LdapReferralException}, and {@code ldapContext} is an
* instance of {@code LdapContext}.
* Specifying {@code null} or an empty array for {@code connCtls}
* means no connection request controls.
* <p>
* Like environment properties, connection request controls of a context
* <em>are inherited</em> by contexts that are derived from it.
* Typically, you initialize the connection request controls using the
* <tt>InitialLdapContext</tt> constructor or
* <tt>LdapReferralContext.getReferralContext()</tt>. These connection
* {@code InitialLdapContext} constructor or
* {@code LdapReferralContext.getReferralContext()}. These connection
* request controls are inherited by contexts that share the same
* connection--that is, contexts derived from the initial or referral
* contexts.
* <p>
* Use <tt>reconnect()</tt> to change the connection request controls of
* Use {@code reconnect()} to change the connection request controls of
* a context.
* Invoking <tt>ldapContext.reconnect()</tt> affects only the
* connection used by <tt>ldapContext</tt> and any new contexts instances that are
* derived form <tt>ldapContext</tt>. Contexts that previously shared the
* connection with <tt>ldapContext</tt> remain unchanged. That is, a context's
* Invoking {@code ldapContext.reconnect()} affects only the
* connection used by {@code ldapContext} and any new contexts instances that are
* derived form {@code ldapContext}. Contexts that previously shared the
* connection with {@code ldapContext} remain unchanged. That is, a context's
* connection request controls must be explicitly changed and is not
* affected by changes to another context's connection request
* controls.
* <p>
* A context instance's connection request controls are retrieved using
* the method <tt>getConnectControls()</tt>.
* the method {@code getConnectControls()}.
*
* <h4>Service Provider Requirements</h4>
*
@ -145,22 +145,22 @@ import java.util.Hashtable;
*
* <h3>Response Controls</h3>
*
* The method <tt>LdapContext.getResponseControls()</tt> is used to
* The method {@code LdapContext.getResponseControls()} is used to
* retrieve the response controls generated by LDAP operations executed
* as the result of invoking a <tt>Context</tt>/<tt>DirContext</tt>
* as the result of invoking a {@code Context}/{@code DirContext}
* operation. The result is all of the responses controls generated
* by the underlying LDAP operations, including any implicit reconnection.
* To get only the reconnection response controls,
* use <tt>reconnect()</tt> followed by <tt>getResponseControls()</tt>.
* use {@code reconnect()} followed by {@code getResponseControls()}.
*
* <h3>Parameters</h3>
*
* A <tt>Control[]</tt> array
* A {@code Control[]} array
* passed as a parameter to any method is owned by the caller.
* The service provider will not modify the array or keep a reference to it,
* although it may keep references to the individual <tt>Control</tt> objects
* although it may keep references to the individual {@code Control} objects
* in the array.
* A <tt>Control[]</tt> array returned by any method is immutable, and may
* A {@code Control[]} array returned by any method is immutable, and may
* not subsequently be modified by either the caller or the service provider.
*
* @author Rosanna Lee
@ -207,7 +207,7 @@ public interface LdapContext extends DirContext {
* to use for the new context.
* If null, the context is initialized with no request controls.
*
* @return A non-null <tt>LdapContext</tt> instance.
* @return A non-null {@code LdapContext} instance.
* @exception NamingException If an error occurred while creating
* the new instance.
* @see InitialLdapContext
@ -224,16 +224,16 @@ public interface LdapContext extends DirContext {
* the LDAP "bind" operation, or to explicitly connect to the server
* to get response controls returned by the LDAP "bind" operation.
*<p>
* This method sets this context's <tt>connCtls</tt>
* This method sets this context's {@code connCtls}
* to be its new connection request controls. This context's
* context request controls are not affected.
* After this method has been invoked, any subsequent
* implicit reconnections will be done using <tt>connCtls</tt>.
* <tt>connCtls</tt> are also used as
* implicit reconnections will be done using {@code connCtls}.
* {@code connCtls} are also used as
* connection request controls for new context instances derived from this
* context.
* These connection request controls are not
* affected by <tt>setRequestControls()</tt>.
* affected by {@code setRequestControls()}.
*<p>
* Service provider implementors should read the "Service Provider" section
* in the class description for implementation details.
@ -266,17 +266,17 @@ public interface LdapContext extends DirContext {
* caller.
* <p>
* This removes any previous request controls and adds
* <tt>requestControls</tt>
* {@code requestControls}
* for use by subsequent methods invoked on this context.
* This method does not affect this context's connection request controls.
*<p>
* Note that <tt>requestControls</tt> will be in effect until the next
* invocation of <tt>setRequestControls()</tt>. You need to explicitly
* invoke <tt>setRequestControls()</tt> with <tt>null</tt> or an empty
* Note that {@code requestControls} will be in effect until the next
* invocation of {@code setRequestControls()}. You need to explicitly
* invoke {@code setRequestControls()} with {@code null} or an empty
* array to clear the controls if you don't want them to affect the
* context methods any more.
* To check what request controls are in effect for this context, use
* <tt>getRequestControls()</tt>.
* {@code getRequestControls()}.
* @param requestControls The possibly null controls to use. If null, no
* controls are used.
* @exception NamingException If an error occurred while setting the
@ -312,10 +312,10 @@ public interface LdapContext extends DirContext {
*<p>
* When a context method that may return response controls is invoked,
* response controls from the previous method invocation are cleared.
* <tt>getResponseControls()</tt> returns all of the response controls
* {@code getResponseControls()} returns all of the response controls
* generated by LDAP operations used by the context method in the order
* received from the LDAP server.
* Invoking <tt>getResponseControls()</tt> does not
* Invoking {@code getResponseControls()} does not
* clear the response controls. You can call it many times (and get
* back the same controls) until the next context method that may return
* controls is invoked.
@ -333,7 +333,7 @@ public interface LdapContext extends DirContext {
* of the property should be a colon-separated list of the fully
* qualified class names of factory classes that will create a control
* given another control. See
* <tt>ControlFactory.getControlInstance()</tt> for details.
* {@code ControlFactory.getControlInstance()} for details.
* This property may be specified in the environment, a system property,
* or one or more resource files.
*<p>

40
jdk/src/java.naming/share/classes/javax/naming/ldap/LdapName.java
View File

@ -59,7 +59,7 @@ import java.io.IOException;
* characters (unescaped) are accepted.
* </ul>
*<p>
* String names passed to <code>LdapName</code> or returned by it
* String names passed to {@code LdapName} or returned by it
* use the full Unicode character set. They may also contain
* characters encoded into UTF-8 with each octet represented by a
* three-character substring such as "\\B4".
@ -67,7 +67,7 @@ import java.io.IOException;
* each octet represented by a single character in the string: the
* meaning would be ambiguous.
*<p>
* <code>LdapName</code> will properly parse all valid names, but
* {@code LdapName} will properly parse all valid names, but
* does not attempt to detect all possible violations when parsing
* invalid names. It is "generous" in accepting invalid names.
* The "validity" of a name is determined ultimately when it
@ -92,7 +92,7 @@ import java.io.IOException;
* empty LDAP name is represented by an empty RDN list.
*<p>
* Concurrent multithreaded read-only access of an instance of
* <tt>LdapName</tt> need not be synchronized.
* {@code LdapName} need not be synchronized.
*<p>
* Unless otherwise noted, the behavior of passing a null argument
* to a constructor or method in this class will cause a
@ -129,7 +129,7 @@ public class LdapName implements Name {
* The indexing of RDNs in the list follows the numbering of
* RDNs described in the class description.
*
* @param rdns The non-null list of <tt>Rdn</tt>s forming this LDAP name.
* @param rdns The non-null list of {@code Rdn}s forming this LDAP name.
*/
public LdapName(List<Rdn> rdns) {
@ -240,7 +240,7 @@ public class LdapName implements Name {
* that is returned and vice versa.
* @param posn The 0-based index of the component at which to stop.
* Must be in the range [0,size()].
* @return An instance of <tt>LdapName</tt> consisting of the
* @return An instance of {@code LdapName} consisting of the
* components at indexes in the range [0,posn).
* If posn is zero, an empty LDAP name is returned.
* @exception IndexOutOfBoundsException
@ -263,7 +263,7 @@ public class LdapName implements Name {
*
* @param posn The 0-based index of the component at which to start.
* Must be in the range [0,size()].
* @return An instance of <tt>LdapName</tt> consisting of the
* @return An instance of {@code LdapName} consisting of the
* components at indexes in the range [posn,size()).
* If posn is equal to size(), an empty LDAP name is
* returned.
@ -282,13 +282,13 @@ public class LdapName implements Name {
/**
* Determines whether this LDAP name starts with a specified LDAP name
* prefix.
* A name <tt>n</tt> is a prefix if it is equal to
* <tt>getPrefix(n.size())</tt>--in other words this LDAP
* A name {@code n} is a prefix if it is equal to
* {@code getPrefix(n.size())}--in other words this LDAP
* name starts with 'n'. If n is null or not a RFC2253 formatted name
* as described in the class description, false is returned.
*
* @param n The LDAP name to check.
* @return true if <tt>n</tt> is a prefix of this LDAP name,
* @return true if {@code n} is a prefix of this LDAP name,
* false otherwise.
* @see #getPrefix(int posn)
*/
@ -309,8 +309,8 @@ public class LdapName implements Name {
* getRdn(p) matches rdns.get(p). Returns false otherwise. If rdns is
* null, false is returned.
*
* @param rdns The sequence of <tt>Rdn</tt>s to check.
* @return true if <tt>rdns</tt> form a prefix of this LDAP name,
* @param rdns The sequence of {@code Rdn}s to check.
* @return true if {@code rdns} form a prefix of this LDAP name,
* false otherwise.
*/
public boolean startsWith(List<Rdn> rdns) {
@ -326,13 +326,13 @@ public class LdapName implements Name {
/**
* Determines whether this LDAP name ends with a specified
* LDAP name suffix.
* A name <tt>n</tt> is a suffix if it is equal to
* <tt>getSuffix(size()-n.size())</tt>--in other words this LDAP
* A name {@code n} is a suffix if it is equal to
* {@code getSuffix(size()-n.size())}--in other words this LDAP
* name ends with 'n'. If n is null or not a RFC2253 formatted name
* as described in the class description, false is returned.
*
* @param n The LDAP name to check.
* @return true if <tt>n</tt> is a suffix of this name, false otherwise.
* @return true if {@code n} is a suffix of this name, false otherwise.
* @see #getSuffix(int posn)
*/
public boolean endsWith(Name n) {
@ -352,8 +352,8 @@ public class LdapName implements Name {
* the component getRdn(p) matches rdns.get(p). Returns false otherwise.
* If rdns is null, false is returned.
*
* @param rdns The sequence of <tt>Rdn</tt>s to check.
* @return true if <tt>rdns</tt> form a suffix of this LDAP name,
* @param rdns The sequence of {@code Rdn}s to check.
* @return true if {@code rdns} form a suffix of this LDAP name,
* false otherwise.
*/
public boolean endsWith(List<Rdn> rdns) {
@ -409,7 +409,7 @@ public class LdapName implements Name {
* @param suffix The non-null components to add.
* @return The updated name (not a new instance).
*
* @throws InvalidNameException if <tt>suffix</tt> is not a valid LDAP
* @throws InvalidNameException if {@code suffix} is not a valid LDAP
* name, or if the addition of the components would violate the
* syntax rules of this LDAP name.
*/
@ -421,7 +421,7 @@ public class LdapName implements Name {
/**
* Adds the RDNs of a name -- in order -- to the end of this name.
*
* @param suffixRdns The non-null suffix <tt>Rdn</tt>s to add.
* @param suffixRdns The non-null suffix {@code Rdn}s to add.
* @return The updated name (not a new instance).
*/
public Name addAll(List<Rdn> suffixRdns) {
@ -440,7 +440,7 @@ public class LdapName implements Name {
*
* @return The updated name (not a new instance).
*
* @throws InvalidNameException if <tt>suffix</tt> is not a valid LDAP
* @throws InvalidNameException if {@code suffix} is not a valid LDAP
* name, or if the addition of the components would violate the
* syntax rules of this LDAP name.
* @throws IndexOutOfBoundsException
@ -469,7 +469,7 @@ public class LdapName implements Name {
* index (if any) of the first new RDN are shifted up (away from index 0) to
* accommodate the new RDNs.
*
* @param suffixRdns The non-null suffix <tt>Rdn</tt>s to add.
* @param suffixRdns The non-null suffix {@code Rdn}s to add.
* @param posn The index at which to add the suffix RDNs.
* Must be in the range [0,size()].
*

34
jdk/src/java.naming/share/classes/javax/naming/ldap/LdapReferralException.java
View File

@ -32,15 +32,15 @@ import java.util.Hashtable;
/**
* This abstract class is used to represent an LDAP referral exception.
* It extends the base <tt>ReferralException</tt> by providing a
* <tt>getReferralContext()</tt> method that accepts request controls.
* It extends the base {@code ReferralException} by providing a
* {@code getReferralContext()} method that accepts request controls.
* LdapReferralException is an abstract class. Concrete implementations of it
* determine its synchronization and serialization properties.
*<p>
* A <tt>Control[]</tt> array passed as a parameter to
* the <tt>getReferralContext()</tt> method is owned by the caller.
* A {@code Control[]} array passed as a parameter to
* the {@code getReferralContext()} method is owned by the caller.
* The service provider will not modify the array or keep a reference to it,
* although it may keep references to the individual <tt>Control</tt> objects
* although it may keep references to the individual {@code Control} objects
* in the array.
*
* @author Rosanna Lee
@ -73,20 +73,20 @@ public abstract class LdapReferralException extends ReferralException {
* Retrieves the context at which to continue the method using the
* context's environment and no controls.
* The referral context is created using the environment properties of
* the context that threw the <tt>ReferralException</tt> and no controls.
* the context that threw the {@code ReferralException} and no controls.
*<p>
* This method is equivalent to
*<blockquote><pre>
* getReferralContext(ctx.getEnvironment(), null);
*</pre></blockquote>
* where <tt>ctx</tt> is the context that threw the <tt>ReferralException.</tt>
* where {@code ctx} is the context that threw the {@code ReferralException.}
*<p>
* It is overridden in this class for documentation purposes only.
* See <tt>ReferralException</tt> for how to use this method.
* See {@code ReferralException} for how to use this method.
*
* @return The non-null context at which to continue the method.
* @exception NamingException If a naming exception was encountered.
* Call either <tt>retryReferral()</tt> or <tt>skipReferral()</tt>
* Call either {@code retryReferral()} or {@code skipReferral()}
* to continue processing referrals.
*/
public abstract Context getReferralContext() throws NamingException;
@ -94,7 +94,7 @@ public abstract class LdapReferralException extends ReferralException {
/**
* Retrieves the context at which to continue the method using
* environment properties and no controls.
* The referral context is created using <tt>env</tt> as its environment
* The referral context is created using {@code env} as its environment
* properties and no controls.
*<p>
* This method is equivalent to
@ -103,14 +103,14 @@ public abstract class LdapReferralException extends ReferralException {
*</pre></blockquote>
*<p>
* It is overridden in this class for documentation purposes only.
* See <tt>ReferralException</tt> for how to use this method.
* See {@code ReferralException} for how to use this method.
*
* @param env The possibly null environment to use when retrieving the
* referral context. If null, no environment properties will be used.
*
* @return The non-null context at which to continue the method.
* @exception NamingException If a naming exception was encountered.
* Call either <tt>retryReferral()</tt> or <tt>skipReferral()</tt>
* Call either {@code retryReferral()} or {@code skipReferral()}
* to continue processing referrals.
*/
public abstract Context
@ -127,12 +127,12 @@ public abstract class LdapReferralException extends ReferralException {
* To continue the operation, the client program should re-invoke
* the method using the same arguments as the original invocation.
*<p>
* <tt>reqCtls</tt> is used when creating the connection to the referred
* {@code reqCtls} is used when creating the connection to the referred
* server. These controls will be used as the connection request controls for
* the context and context instances
* derived from the context.
* <tt>reqCtls</tt> will also be the context's request controls for
* subsequent context operations. See the <tt>LdapContext</tt> class
* {@code reqCtls} will also be the context's request controls for
* subsequent context operations. See the {@code LdapContext} class
* description for details.
*<p>
* This method should be used instead of the other two overloaded forms
@ -141,7 +141,7 @@ public abstract class LdapReferralException extends ReferralException {
* it needs to supply special controls relating to authentication.
*<p>
* Service provider implementors should read the "Service Provider" section
* in the <tt>LdapContext</tt> class description for implementation details.
* in the {@code LdapContext} class description for implementation details.
*
* @param reqCtls The possibly null request controls to use for the new context.
* If null or the empty array means use no request controls.
@ -150,7 +150,7 @@ public abstract class LdapReferralException extends ReferralException {
* properties.
* @return The non-null context at which to continue the method.
* @exception NamingException If a naming exception was encountered.
* Call either <tt>retryReferral()</tt> or <tt>skipReferral()</tt>
* Call either {@code retryReferral()} or {@code skipReferral()}
* to continue processing referrals.
*/
public abstract Context

22
jdk/src/java.naming/share/classes/javax/naming/ldap/Rdn.java
View File

@ -50,7 +50,7 @@ import java.io.IOException;
* An example of an RDN is "OU=Sales+CN=J.Smith". In this example,
* the RDN consist of multiple attribute type/value pairs. The
* RDN is parsed as described in the class description for
* {@link javax.naming.ldap.LdapName <tt>LdapName</tt>}.
* {@link javax.naming.ldap.LdapName LdapName}.
* <p>
* The Rdn class represents an RDN as attribute type/value mappings,
* which can be viewed using
@ -79,11 +79,11 @@ import java.io.IOException;
* Rdn rdn = new Rdn("cn", "Juicy, Fruit");
* System.out.println(rdn.toString());
* </pre>
* The last line will print <tt>cn=Juicy\, Fruit</tt>. The
* {@link #unescapeValue(String) <tt>unescapeValue()</tt>} method can be
* The last line will print {@code cn=Juicy\, Fruit}. The
* {@link #unescapeValue(String) unescapeValue()} method can be
* used to unescape the escaped comma resulting in the original
* value <tt>"Juicy, Fruit"</tt>. The {@link #escapeValue(Object)
* <tt>escapeValue()</tt>} method adds the escape back preceding the comma.
* value {@code "Juicy, Fruit"}. The {@link #escapeValue(Object)
* escapeValue()} method adds the escape back preceding the comma.
* <p>
* This class can be instantiated by a string representation
* of the RDN defined in RFC 2253 as shown in the following code example:
@ -91,10 +91,10 @@ import java.io.IOException;
* Rdn rdn = new Rdn("cn=Juicy\\, Fruit");
* System.out.println(rdn.toString());
* </pre>
* The last line will print <tt>cn=Juicy\, Fruit</tt>.
* The last line will print {@code cn=Juicy\, Fruit}.
* <p>
* Concurrent multithreaded read-only access of an instance of
* <tt>Rdn</tt> need not be synchronized.
* {@code Rdn} need not be synchronized.
* <p>
* Unless otherwise noted, the behavior of passing a null argument
* to a constructor or method in this class will cause NullPointerException
@ -123,7 +123,7 @@ public class Rdn implements Serializable, Comparable<Object> {
*
* @param attrSet The non-null and non-empty attributes containing
* type/value mappings.
* @throws InvalidNameException If contents of <tt>attrSet</tt> cannot
* @throws InvalidNameException If contents of {@code attrSet} cannot
* be used to construct a valid RDN.
*/
public Rdn(Attributes attrSet) throws InvalidNameException {
@ -166,8 +166,8 @@ public class Rdn implements Serializable, Comparable<Object> {
}
/**
* Constructs an Rdn from the given <tt>rdn</tt>.
* The contents of the <tt>rdn</tt> are simply copied into the newly
* Constructs an Rdn from the given {@code rdn}.
* The contents of the {@code rdn} are simply copied into the newly
* created Rdn.
* @param rdn The non-null Rdn to be copied.
*/
@ -583,7 +583,7 @@ public class Rdn implements Serializable, Comparable<Object> {
* This method is generous in accepting the values and does not
* catch all illegal values.
* Therefore, passing in an illegal value might not necessarily
* trigger an <tt>IllegalArgumentException</tt>.
* trigger an {@code IllegalArgumentException}.
*
* @param val The non-null string to be unescaped.
* @return Unescaped value.

12
jdk/src/java.naming/share/classes/javax/naming/ldap/StartTlsRequest.java
View File

@ -43,9 +43,9 @@ import java.util.ServiceConfigurationError;
* The object identifier for StartTLS is 1.3.6.1.4.1.1466.20037
* and no extended request value is defined.
*<p>
* <tt>StartTlsRequest</tt>/<tt>StartTlsResponse</tt> are used to establish
* {@code StartTlsRequest}/{@code StartTlsResponse} are used to establish
* a TLS connection over the existing LDAP connection associated with
* the JNDI context on which <tt>extendedOperation()</tt> is invoked.
* the JNDI context on which {@code extendedOperation()} is invoked.
* Typically, a JNDI program uses these classes as follows.
* <blockquote><pre>
* import javax.naming.ldap.*;
@ -127,16 +127,16 @@ public class StartTlsRequest implements ExtendedRequest {
* <p>
* This method locates the implementation class by locating
* configuration files that have the name:
* <blockquote><tt>
* <blockquote>{@code
* META-INF/services/javax.naming.ldap.StartTlsResponse
* </tt></blockquote>
* }</blockquote>
* The configuration files and their corresponding implementation classes must
* be accessible to the calling thread's context class loader.
* <p>
* Each configuration file should contain a list of fully-qualified class
* names, one per line. Space and tab characters surrounding each name, as
* well as blank lines, are ignored. The comment character is <tt>'#'</tt>
* (<tt>0x23</tt>); on each line all characters following the first comment
* well as blank lines, are ignored. The comment character is {@code '#'}
* ({@code 0x23}); on each line all characters following the first comment
* character are ignored. The file must be encoded in UTF-8.
* <p>
* This method will return an instance of the first implementation

20
jdk/src/java.naming/share/classes/javax/naming/ldap/StartTlsResponse.java
View File

@ -42,7 +42,7 @@ import javax.net.ssl.HostnameVerifier;
*<p>
* The Start TLS extended request and response are used to establish
* a TLS connection over the existing LDAP connection associated with
* the JNDI context on which <tt>extendedOperation()</tt> is invoked.
* the JNDI context on which {@code extendedOperation()} is invoked.
* Typically, a JNDI program uses the StartTLS extended request and response
* classes as follows.
* <blockquote><pre>
@ -122,7 +122,7 @@ public abstract class StartTlsResponse implements ExtendedResponse {
/**
* Overrides the default list of cipher suites enabled for use on the
* TLS connection. The cipher suites must have already been listed by
* <tt>SSLSocketFactory.getSupportedCipherSuites()</tt> as being supported.
* {@code SSLSocketFactory.getSupportedCipherSuites()} as being supported.
* Even if a suite has been enabled, it still might not be used because
* the peer does not support it, or because the requisite certificates
* (and private keys) are not available.
@ -134,13 +134,13 @@ public abstract class StartTlsResponse implements ExtendedResponse {
public abstract void setEnabledCipherSuites(String[] suites);
/**
* Sets the hostname verifier used by <tt>negotiate()</tt>
* Sets the hostname verifier used by {@code negotiate()}
* after the TLS handshake has completed and the default hostname
* verification has failed.
* <tt>setHostnameVerifier()</tt> must be called before
* <tt>negotiate()</tt> is invoked for it to have effect.
* {@code setHostnameVerifier()} must be called before
* {@code negotiate()} is invoked for it to have effect.
* If called after
* <tt>negotiate()</tt>, this method does not do anything.
* {@code negotiate()}, this method does not do anything.
*
* @param verifier The non-null hostname verifier callback.
* @see #negotiate
@ -150,7 +150,7 @@ public abstract class StartTlsResponse implements ExtendedResponse {
/**
* Negotiates a TLS session using the default SSL socket factory.
* <p>
* This method is equivalent to <tt>negotiate(null)</tt>.
* This method is equivalent to {@code negotiate(null)}.
*
* @return The negotiated SSL session
* @throws IOException If an IO error was encountered while establishing
@ -167,16 +167,16 @@ public abstract class StartTlsResponse implements ExtendedResponse {
* attaches it to the existing connection. Performs the TLS handshake
* and returns the negotiated session information.
* <p>
* If cipher suites have been set via <tt>setEnabledCipherSuites</tt>
* If cipher suites have been set via {@code setEnabledCipherSuites}
* then they are enabled before the TLS handshake begins.
* <p>
* Hostname verification is performed after the TLS handshake completes.
* The default hostname verification performs a match of the server's
* hostname against the hostname information found in the server's certificate.
* If this verification fails and no callback has been set via
* <tt>setHostnameVerifier</tt> then the negotiation fails.
* {@code setHostnameVerifier} then the negotiation fails.
* If this verification fails and a callback has been set via
* <tt>setHostnameVerifier</tt>, then the callback is used to determine whether
* {@code setHostnameVerifier}, then the callback is used to determine whether
* the negotiation succeeds.
* <p>
* If an error occurs then the SSL socket is closed and an IOException

2
jdk/src/java.naming/share/classes/javax/naming/ldap/UnsolicitedNotification.java
View File

@ -32,7 +32,7 @@ import javax.naming.NamingException;
* <A HREF="http://www.ietf.org/rfc/rfc2251.txt">RFC 2251</A>.
* An unsolicited notification is sent by the LDAP server to the LDAP
* client without any provocation from the client.
* Its format is that of an extended response (<tt>ExtendedResponse</tt>).
* Its format is that of an extended response ({@code ExtendedResponse}).
*
* @author Rosanna Lee
* @author Scott Seligman

6
jdk/src/java.naming/share/classes/javax/naming/ldap/UnsolicitedNotificationEvent.java
View File

@ -49,7 +49,7 @@ public class UnsolicitedNotificationEvent extends java.util.EventObject {
private UnsolicitedNotification notice;
/**
* Constructs a new instance of <tt>UnsolicitedNotificationEvent</tt>.
* Constructs a new instance of {@code UnsolicitedNotificationEvent}.
*
* @param src The non-null source that fired the event.
* @param notice The non-null unsolicited notification.
@ -71,10 +71,10 @@ public class UnsolicitedNotificationEvent extends java.util.EventObject {
}
/**
* Invokes the <tt>notificationReceived()</tt> method on
* Invokes the {@code notificationReceived()} method on
* a listener using this event.
* @param listener The non-null listener on which to invoke
* <tt>notificationReceived</tt>.
* {@code notificationReceived}.
*/
public void dispatch(UnsolicitedNotificationListener listener) {
listener.notificationReceived(this);

14
jdk/src/java.naming/share/classes/javax/naming/ldap/UnsolicitedNotificationListener.java
View File

@ -28,20 +28,20 @@ package javax.naming.ldap;
import javax.naming.event.NamingListener;
/**
* This interface is for handling <tt>UnsolicitedNotificationEvent</tt>.
* This interface is for handling {@code UnsolicitedNotificationEvent}.
* "Unsolicited notification" is defined in
* <A HREF="http://www.ietf.org/rfc/rfc2251.txt">RFC 2251</A>.
* It allows the server to send unsolicited notifications to the client.
* A <tt>UnsolicitedNotificationListener</tt> must:
* A {@code UnsolicitedNotificationListener} must:
*<ol>
* <li>Implement this interface and its method
* <li>Implement <tt>NamingListener.namingExceptionThrown()</tt> so
* <li>Implement {@code NamingListener.namingExceptionThrown()} so
* that it will be notified of exceptions thrown while attempting to
* collect unsolicited notification events.
* <li>Register with the context using one of the <tt>addNamingListener()</tt>
* methods from <tt>EventContext</tt> or <tt>EventDirContext</tt>.
* Only the <tt>NamingListener</tt> argument of these methods are applicable;
* the rest are ignored for a <tt>UnsolicitedNotificationListener</tt>.
* <li>Register with the context using one of the {@code addNamingListener()}
* methods from {@code EventContext} or {@code EventDirContext}.
* Only the {@code NamingListener} argument of these methods are applicable;
* the rest are ignored for a {@code UnsolicitedNotificationListener}.
* (These arguments might be applicable to the listener if it implements
* other listener interfaces).
*</ol>

36
jdk/src/java.naming/share/classes/javax/naming/ldap/package.html
View File

@ -44,15 +44,15 @@ already deployed ones--can be accessed in a common way.
This package is for applications and service providers that deal with
LDAPv3 extended operations and controls, as defined by
<a href=http://www.ietf.org/rfc/rfc2251.txt>RFC 2251</a>.
The core interface in this package is <tt>LdapContext</tt>, which defines
The core interface in this package is <code>LdapContext</code>, which defines
methods on a context for performing extended operations and handling
controls.
<h4>Extended Operations</h4>
<p>
This package defines the interface <tt>ExtendedRequest</tt>
This package defines the interface <code>ExtendedRequest</code>
to represent the argument to an extended operation,
and the interface <tt>ExtendedResponse</tt> to represent the result
and the interface <code>ExtendedResponse</code> to represent the result
of the extended operation.
An extended response is always paired with an extended request
but not necessarily vice versa. That is, you can have an extended request
@ -73,7 +73,7 @@ BER values.
<p>
For example, suppose an LDAP server supports a "get time" extended operation.
It would supply classes such as
<tt>GetTimeRequest</tt> and <tt>GetTimeResponse</tt>,
<code>GetTimeRequest</code> and <code>GetTimeResponse</code>,
so that applications can use this feature.
An application would use these classes as follows:
<blockquote><pre>
@ -82,7 +82,7 @@ GetTimeResponse resp =
long time = resp.getTime();
</pre></blockquote>
<p>
The <tt>GetTimeRequest</tt> and <tt>GetTimeResponse</tt> classes might
The <code>GetTimeRequest</code> and <code>GetTimeResponse</code> classes might
be defined as follows:
<blockquote><pre>
public class GetTimeRequest implements ExtendedRequest {
@ -105,7 +105,7 @@ public class GetTimeRequest implements ExtendedRequest {
public class GetTimeResponse() implements ExtendedResponse {
long time;
// called by GetTimeRequest.createExtendedResponse()
public GetTimeResponse(String id, byte[] berValue, int offset, int length)
public GetTimeResponse(String id, byte[] berValue, int offset, int length)
throws NamingException {
// check validity of id
long time = ... // decode berValue to get time
@ -127,7 +127,7 @@ public class GetTimeResponse() implements ExtendedResponse {
<h4>Controls</h4>
This package defines the interface <tt>Control</tt> to represent an LDAPv3
This package defines the interface <code>Control</code> to represent an LDAPv3
control. It can be a control that is sent to an LDAP server
(<em>request control</em>) or a control returned by an LDAP server
(<em>response control</em>). Unlike extended requests and responses,
@ -149,8 +149,8 @@ encoding and decoding BER values.
<p>
For example, suppose an LDAP server supports a "signed results"
request control, which when sent with a request, asks the
server to digitally sign the results of an operation.
It would supply a class <tt>SignedResultsControl</tt> so that applications
server to digitally sign the results of an operation.
It would supply a class <code>SignedResultsControl</code> so that applications
can use this feature.
An application would use this class as follows:
<blockquote>
@ -160,7 +160,7 @@ ectx.setRequestControls(reqCtls);
NamingEnumeration enum = ectx.search(...);
</pre>
</blockquote>
The <tt>SignedResultsControl</tt> class might be defined as follows:
The <code>SignedResultsControl</code> class might be defined as follows:
<blockquote><pre>
public class SignedResultsControl implements Control {
// User-friendly constructor
@ -180,19 +180,19 @@ public class SignedResultsControl implements Control {
</pre></blockquote>
<p>
When a service provider receives response controls, it uses
the <tt>ControlFactory</tt> class to produce specific classes
that implement the <tt>Control</tt> interface.
the <code>ControlFactory</code> class to produce specific classes
that implement the <code>Control</code> interface.
<p>
An LDAP server can send back response controls with an LDAP operation
and also with enumeration results, such as those returned
by a list or search operation.
The <tt>LdapContext</tt> provides a method (<tt>getResponseControls()</tt>)
The <code>LdapContext</code> provides a method (<code>getResponseControls()</code>)
for getting the response controls sent with an LDAP operation,
while the <tt>HasControls</tt> interface is used to retrieve
while the <code>HasControls</code> interface is used to retrieve
response controls associated with enumeration results.
<p>
For example, suppose an LDAP server sends back a "change ID" control in response
to a successful modification. It would supply a class <tt>ChangeIDControl</tt>
to a successful modification. It would supply a class <code>ChangeIDControl</code>
so that the application can use this feature.
An application would perform an update, and then try to get the change ID.
<blockquote><pre>
@ -211,8 +211,8 @@ if (respCtls != null) {
}
}
</pre></blockquote>
The vendor might supply the following <tt>ChangeIDControl</tt> and
<tt>VendorXControlFactory</tt> classes. The <tt>VendorXControlFactory</tt>
The vendor might supply the following <code>ChangeIDControl</code> and
<code>VendorXControlFactory</code> classes. The <code>VendorXControlFactory</code>
will be used by the service provider when the provider receives response
controls from the LDAP server.
<blockquote><pre>
@ -245,7 +245,7 @@ public class VendorXControlFactory extends ControlFactory {
public Control getControlInstance(Control orig) throws NamingException {
if (isOneOfMyControls(orig.getID())) {
...
...
// determine which of ours it is and call its constructor
return (new ChangeIDControl(orig.getID(), orig.getEncodedValue()));

36
jdk/src/java.naming/share/classes/javax/naming/package.html
View File

@ -43,13 +43,13 @@ already deployed ones--can be accessed in a common way.
<h4>Context</h4>
<p>
This package defines the notion of a <em>context</em>, represented
by the <tt>Context</tt> interface.
by the <code>Context</code> interface.
A context consists of a set of name-to-object <em>bindings</em>.
<tt>Context</tt> is the core interface for looking up, binding, unbinding,
<code>Context</code> is the core interface for looking up, binding, unbinding,
and renaming objects, and for creating and destroying subcontexts.
<p>
<tt>lookup()</tt> is the most commonly used operation.
You supply <tt>lookup()</tt>
<code>lookup()</code> is the most commonly used operation.
You supply <code>lookup()</code>
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
@ -65,17 +65,17 @@ printer.print(report);
<h4>Names</h4>
<p>
Every naming method in the <tt>Context</tt>
Every naming method in the <code>Context</code>
interface has two
overloads: one that accepts a
<tt>Name</tt> argument and one that accepts a string name.
<tt>Name</tt> is an interface that represents a generic
<code>Name</code> argument and one that accepts a string name.
<code>Name</code> is an interface that represents a generic
name--an ordered sequence of zero of more components.
For these methods, <tt>Name</tt> can be used to represent a
<em>composite name</em> (<tt>CompositeName</tt>)
For these methods, <code>Name</code> can be used to represent a
<em>composite name</em> (<code>CompositeName</code>)
so that you can name an object using a name which spans multiple namespaces.
<p>
The overloads that accept <tt>Name</tt>
The overloads that accept <code>Name</code>
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
@ -84,14 +84,14 @@ and look up the corresponding object.
<h4>Bindings</h4>
The <tt>Binding</tt> class represents a name-to-object binding.
The <code>Binding</code> 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.
<p>
The <tt>Binding</tt> class is actually a subclass of
<tt>NameClassPair</tt>, which consists
The <code>Binding</code> class is actually a subclass of
<code>NameClassPair</code>, which consists
simply of the object's name and the object's class name.
The <tt>NameClassPair</tt> is useful when you only want
The <code>NameClassPair</code> 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.
@ -104,7 +104,7 @@ 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 <em>reference</em>, represented by the <tt>Reference</tt>
JNDI defines a <em>reference</em>, represented by the <code>Reference</code>
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
@ -117,7 +117,7 @@ is stored in the directory are Java objects.
In JNDI, all naming and directory operations are performed relative
to a context. There are no absolute roots.
Therefore JNDI defines an <em>initial context</em>,
<tt>InitialContext</tt>,
<code>InitialContext</code>,
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.
@ -126,10 +126,10 @@ look up other contexts and objects.
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 <tt>NamingException</tt>.
this class hierarchy is <code>NamingException</code>.
Programs interested in dealing with a particular exception
can catch the corresponding subclass of the exception.
Otherwise, programs should catch <tt>NamingException</tt>.
Otherwise, programs should catch <code>NamingException</code>.
<h2>Package Specification</h2>

42
jdk/src/java.naming/share/classes/javax/naming/spi/DirObjectFactory.java
View File

@ -35,12 +35,12 @@ import javax.naming.directory.Attributes;
*<p>
* The JNDI framework allows for object implementations to
* be loaded in dynamically via <em>object factories</em>. See
* <tt>ObjectFactory</tt> for details.
* {@code ObjectFactory} for details.
* <p>
* A <tt>DirObjectFactory</tt> extends <tt>ObjectFactory</tt> by allowing
* an <tt>Attributes</tt> instance
* to be supplied to the <tt>getObjectInstance()</tt> method.
* <tt>DirObjectFactory</tt> implementations are intended to be used by <tt>DirContext</tt>
* A {@code DirObjectFactory} extends {@code ObjectFactory} by allowing
* an {@code Attributes} instance
* to be supplied to the {@code getObjectInstance()} method.
* {@code DirObjectFactory} implementations are intended to be used by {@code DirContext}
* service providers. The service provider, in addition reading an
* object from the directory, might already have attributes that
* are useful for the object factory to check to see whether the
@ -71,34 +71,34 @@ public interface DirObjectFactory extends ObjectFactory {
* An example of such an environment property is user identity
* information.
*<p>
* <tt>DirectoryManager.getObjectInstance()</tt>
* successively loads in object factories. If it encounters a <tt>DirObjectFactory</tt>,
* it will invoke <tt>DirObjectFactory.getObjectInstance()</tt>;
* {@code DirectoryManager.getObjectInstance()}
* successively loads in object factories. If it encounters a {@code DirObjectFactory},
* it will invoke {@code DirObjectFactory.getObjectInstance()};
* otherwise, it invokes
* <tt>ObjectFactory.getObjectInstance()</tt>. It does this until a factory
* {@code ObjectFactory.getObjectInstance()}. It does this until a factory
* produces a non-null answer.
* <p> When an exception
* is thrown by an object factory, the exception is passed on to the caller
* of <tt>DirectoryManager.getObjectInstance()</tt>. The search for other factories
* of {@code DirectoryManager.getObjectInstance()}. The search for other factories
* that may produce a non-null answer is halted.
* An object factory should only throw an exception if it is sure that
* it is the only intended factory and that no other object factories
* should be tried.
* If this factory cannot create an object using the arguments supplied,
* it should return null.
*<p>Since <tt>DirObjectFactory</tt> extends <tt>ObjectFactory</tt>, it
*<p>Since {@code DirObjectFactory} extends {@code ObjectFactory}, it
* effectively
* has two <tt>getObjectInstance()</tt> methods, where one differs from the other by
* the attributes argument. Given a factory that implements <tt>DirObjectFactory</tt>,
* <tt>DirectoryManager.getObjectInstance()</tt> will only
* has two {@code getObjectInstance()} methods, where one differs from the other by
* the attributes argument. Given a factory that implements {@code DirObjectFactory},
* {@code DirectoryManager.getObjectInstance()} will only
* use the method that accepts the attributes argument, while
* <tt>NamingManager.getObjectInstance()</tt> will only use the one that does not accept
* {@code NamingManager.getObjectInstance()} will only use the one that does not accept
* the attributes argument.
*<p>
* See <tt>ObjectFactory</tt> for a description URL context factories and other
* properties of object factories that apply equally to <tt>DirObjectFactory</tt>.
* See {@code ObjectFactory} for a description URL context factories and other
* properties of object factories that apply equally to {@code DirObjectFactory}.
*<p>
* The <tt>name</tt>, <tt>attrs</tt>, and <tt>environment</tt> parameters
* The {@code name}, {@code attrs}, and {@code environment} parameters
* are owned by the caller.
* The implementation will not modify these objects or keep references
* to them, although it may keep references to clones or copies.
@ -112,10 +112,10 @@ public interface DirObjectFactory extends ObjectFactory {
* relative to the default initial context.
* @param environment The possibly null environment that is used in
* creating the object.
* @param attrs The possibly null attributes containing some of <tt>obj</tt>'s
* attributes. <tt>attrs</tt> might not necessarily have all of <tt>obj</tt>'s
* @param attrs The possibly null attributes containing some of {@code obj}'s
* attributes. {@code attrs} might not necessarily have all of {@code obj}'s
* attributes. If the object factory requires more attributes, it needs
* to get it, either using <tt>obj</tt>, or <tt>name</tt> and <tt>nameCtx</tt>.
* to get it, either using {@code obj}, or {@code name} and {@code nameCtx}.
* The factory must not modify attrs.
* @return The object created; null if an object cannot be created.
* @exception Exception If this object factory encountered an exception

64
jdk/src/java.naming/share/classes/javax/naming/spi/DirStateFactory.java
View File

@ -33,17 +33,17 @@ import java.util.Hashtable;
* object and corresponding attributes for binding.
*<p>
* The JNDI framework allows for object implementations to
* be loaded in dynamically via <tt>object factories</tt>.
* be loaded in dynamically via {@code object factories}.
* <p>
* A <tt>DirStateFactory</tt> extends <tt>StateFactory</tt>
* by allowing an <tt>Attributes</tt> instance
* to be supplied to and be returned by the <tt>getStateToBind()</tt> method.
* <tt>DirStateFactory</tt> implementations are intended to be used by
* <tt>DirContext</tt> service providers.
* When a caller binds an object using <tt>DirContext.bind()</tt>,
* A {@code DirStateFactory} extends {@code StateFactory}
* by allowing an {@code Attributes} instance
* to be supplied to and be returned by the {@code getStateToBind()} method.
* {@code DirStateFactory} implementations are intended to be used by
* {@code DirContext} service providers.
* When a caller binds an object using {@code DirContext.bind()},
* he might also specify a set of attributes to be bound with the object.
* The object and attributes to be bound are passed to
* the <tt>getStateToBind()</tt> method of a factory.
* the {@code getStateToBind()} method of a factory.
* If the factory processes the object and attributes, it returns
* a corresponding pair of object and attributes to be bound.
* If the factory does not process the object, it must return null.
@ -53,23 +53,23 @@ import java.util.Hashtable;
*<blockquote><pre>
* ctx.rebind("inky", printer, printerAttrs);
*</pre></blockquote>
* An LDAP service provider for <tt>ctx</tt> uses a <tt>DirStateFactory</tt>
* (indirectly via <tt>DirectoryManager.getStateToBind()</tt>)
* and gives it <tt>printer</tt> and <tt>printerAttrs</tt>. A factory for
* an LDAP directory might turn <tt>printer</tt> into a set of attributes
* and merge that with <tt>printerAttrs</tt>. The service provider then
* An LDAP service provider for {@code ctx} uses a {@code DirStateFactory}
* (indirectly via {@code DirectoryManager.getStateToBind()})
* and gives it {@code printer} and {@code printerAttrs}. A factory for
* an LDAP directory might turn {@code printer} into a set of attributes
* and merge that with {@code printerAttrs}. The service provider then
* uses the resulting attributes to create an LDAP entry and updates
* the directory.
*
* <p> Since <tt>DirStateFactory</tt> extends <tt>StateFactory</tt>, it
* has two <tt>getStateToBind()</tt> methods, where one
* <p> Since {@code DirStateFactory} extends {@code StateFactory}, it
* has two {@code getStateToBind()} methods, where one
* differs from the other by the attributes
* argument. <tt>DirectoryManager.getStateToBind()</tt> will only use
* argument. {@code DirectoryManager.getStateToBind()} will only use
* the form that accepts the attributes argument, while
* <tt>NamingManager.getStateToBind()</tt> will only use the form that
* {@code NamingManager.getStateToBind()} will only use the form that
* does not accept the attributes argument.
*
* <p> Either form of the <tt>getStateToBind()</tt> method of a
* <p> Either form of the {@code getStateToBind()} method of a
* DirStateFactory may be invoked multiple times, possibly using different
* parameters. The implementation is thread-safe.
*
@ -85,15 +85,15 @@ public interface DirStateFactory extends StateFactory {
* Retrieves the state of an object for binding given the object and attributes
* to be transformed.
*<p>
* <tt>DirectoryManager.getStateToBind()</tt>
* {@code DirectoryManager.getStateToBind()}
* successively loads in state factories. If a factory implements
* <tt>DirStateFactory</tt>, <tt>DirectoryManager</tt> invokes this method;
* otherwise, it invokes <tt>StateFactory.getStateToBind()</tt>.
* {@code DirStateFactory}, {@code DirectoryManager} invokes this method;
* otherwise, it invokes {@code StateFactory.getStateToBind()}.
* It does this until a factory produces a non-null answer.
*<p>
* When an exception is thrown by a factory,
* the exception is passed on to the caller
* of <tt>DirectoryManager.getStateToBind()</tt>. The search for other factories
* of {@code DirectoryManager.getStateToBind()}. The search for other factories
* that may produce a non-null answer is halted.
* A factory should only throw an exception if it is sure that
* it is the only intended factory and that no other factories
@ -101,36 +101,36 @@ public interface DirStateFactory extends StateFactory {
* If this factory cannot create an object using the arguments supplied,
* it should return null.
* <p>
* The <code>name</code> and <code>nameCtx</code> parameters may
* The {@code name} and {@code nameCtx} parameters may
* optionally be used to specify the name of the object being created.
* See the description of "Name and Context Parameters" in
* {@link ObjectFactory#getObjectInstance ObjectFactory.getObjectInstance()}
* for details.
* If a factory uses <code>nameCtx</code> it should synchronize its use
* If a factory uses {@code nameCtx} it should synchronize its use
* against concurrent access, since context implementations are not
* guaranteed to be thread-safe.
*<p>
* The <tt>name</tt>, <tt>inAttrs</tt>, and <tt>environment</tt> parameters
* The {@code name}, {@code inAttrs}, and {@code environment} parameters
* are owned by the caller.
* The implementation will not modify these objects or keep references
* to them, although it may keep references to clones or copies.
* The object returned by this method is owned by the caller.
* The implementation will not subsequently modify it.
* It will contain either a new <tt>Attributes</tt> object that is
* It will contain either a new {@code Attributes} object that is
* likewise owned by the caller, or a reference to the original
* <tt>inAttrs</tt> parameter.
* {@code inAttrs} parameter.
*
* @param obj A possibly null object whose state is to be retrieved.
* @param name The name of this object relative to <code>nameCtx</code>,
* @param name The name of this object relative to {@code nameCtx},
* or null if no name is specified.
* @param nameCtx The context relative to which the <code>name</code>
* parameter is specified, or null if <code>name</code> is
* @param nameCtx The context relative to which the {@code name}
* parameter is specified, or null if {@code name} is
* relative to the default initial context.
* @param environment The possibly null environment to
* be used in the creation of the object's state.
* @param inAttrs The possibly null attributes to be bound with the object.
* The factory must not modify <tt>inAttrs</tt>.
* @return A <tt>Result</tt> containing the object's state for binding
* The factory must not modify {@code inAttrs}.
* @return A {@code Result} containing the object's state for binding
* and the corresponding
* attributes to be bound; null if the object don't use this factory.
* @exception NamingException If this factory encountered an exception

82
jdk/src/java.naming/share/classes/javax/naming/spi/DirectoryManager.java
View File

@ -41,18 +41,18 @@ import com.sun.naming.internal.FactoryEnumeration;
/**
* This class contains methods for supporting <tt>DirContext</tt>
* This class contains methods for supporting {@code DirContext}
* implementations.
*<p>
* This class is an extension of <tt>NamingManager</tt>. It contains methods
* This class is an extension of {@code NamingManager}. It contains methods
* for use by service providers for accessing object factories and
* state factories, and for getting continuation contexts for
* supporting federation.
*<p>
* <tt>DirectoryManager</tt> is safe for concurrent access by multiple threads.
* {@code DirectoryManager} is safe for concurrent access by multiple threads.
*<p>
* Except as otherwise noted,
* a <tt>Name</tt>, <tt>Attributes</tt>, or environment parameter
* a {@code Name}, {@code Attributes}, or environment parameter
* passed to any method is owned by the caller.
* The implementation will not modify the object or keep a reference
* to it, although it may keep a reference to a clone or copy.
@ -73,13 +73,13 @@ public class DirectoryManager extends NamingManager {
DirectoryManager() {}
/**
* Creates a context in which to continue a <tt>DirContext</tt> operation.
* Operates just like <tt>NamingManager.getContinuationContext()</tt>,
* only the continuation context returned is a <tt>DirContext</tt>.
* Creates a context in which to continue a {@code DirContext} operation.
* Operates just like {@code NamingManager.getContinuationContext()},
* only the continuation context returned is a {@code DirContext}.
*
* @param cpe
* The non-null exception that triggered this continuation.
* @return A non-null <tt>DirContext</tt> object for continuing the operation.
* @return A non-null {@code DirContext} object for continuing the operation.
* @exception NamingException If a naming exception occurred.
*
* @see NamingManager#getContinuationContext(CannotProceedException)
@ -104,37 +104,37 @@ public class DirectoryManager extends NamingManager {
* Creates an instance of an object for the specified object,
* attributes, and environment.
* <p>
* This method is the same as <tt>NamingManager.getObjectInstance</tt>
* This method is the same as {@code NamingManager.getObjectInstance}
* except for the following differences:
*<ul>
*<li>
* It accepts an <tt>Attributes</tt> parameter that contains attributes
* associated with the object. The <tt>DirObjectFactory</tt> might use these
* It accepts an {@code Attributes} parameter that contains attributes
* associated with the object. The {@code DirObjectFactory} might use these
* attributes to save having to look them up from the directory.
*<li>
* The object factories tried must implement either
* <tt>ObjectFactory</tt> or <tt>DirObjectFactory</tt>.
* If it implements <tt>DirObjectFactory</tt>,
* <tt>DirObjectFactory.getObjectInstance()</tt> is used, otherwise,
* <tt>ObjectFactory.getObjectInstance()</tt> is used.
* {@code ObjectFactory} or {@code DirObjectFactory}.
* If it implements {@code DirObjectFactory},
* {@code DirObjectFactory.getObjectInstance()} is used, otherwise,
* {@code ObjectFactory.getObjectInstance()} is used.
*</ul>
* Service providers that implement the <tt>DirContext</tt> interface
* should use this method, not <tt>NamingManager.getObjectInstance()</tt>.
* Service providers that implement the {@code DirContext} interface
* should use this method, not {@code NamingManager.getObjectInstance()}.
*
* @param refInfo The possibly null object for which to create an object.
* @param name The name of this object relative to <code>nameCtx</code>.
* @param name The name of this object relative to {@code nameCtx}.
* Specifying a name is optional; if it is
* omitted, <code>name</code> should be null.
* @param nameCtx The context relative to which the <code>name</code>
* parameter is specified. If null, <code>name</code> is
* omitted, {@code name} should be null.
* @param nameCtx The context relative to which the {@code name}
* parameter is specified. If null, {@code name} is
* relative to the default initial context.
* @param environment The possibly null environment to
* be used in the creation of the object factory and the object.
* @param attrs The possibly null attributes associated with refInfo.
* This might not be the complete set of attributes for refInfo;
* you might be able to read more attributes from the directory.
* @return An object created using <code>refInfo</code> and <tt>attrs</tt>; or
* <code>refInfo</code> if an object cannot be created by
* @return An object created using {@code refInfo} and {@code attrs}; or
* {@code refInfo} if an object cannot be created by
* a factory.
* @exception NamingException If a naming exception was encountered
* while attempting to get a URL context, or if one of the
@ -144,7 +144,7 @@ public class DirectoryManager extends NamingManager {
* and instantiating the factory and object classes.
* A factory should only throw an exception if it does not want
* other factories to be used in an attempt to create an object.
* See <tt>DirObjectFactory.getObjectInstance()</tt>.
* See {@code DirObjectFactory.getObjectInstance()}.
* @see NamingManager#getURLContext
* @see DirObjectFactory
* @see DirObjectFactory#getObjectInstance
@ -246,39 +246,39 @@ public class DirectoryManager extends NamingManager {
* Retrieves the state of an object for binding when given the original
* object and its attributes.
* <p>
* This method is like <tt>NamingManager.getStateToBind</tt> except
* This method is like {@code NamingManager.getStateToBind} except
* for the following differences:
*<ul>
*<li>It accepts an <tt>Attributes</tt> parameter containing attributes
* that were passed to the <tt>DirContext.bind()</tt> method.
*<li>It returns a non-null <tt>DirStateFactory.Result</tt> instance
*<li>It accepts an {@code Attributes} parameter containing attributes
* that were passed to the {@code DirContext.bind()} method.
*<li>It returns a non-null {@code DirStateFactory.Result} instance
* containing the object to be bound, and the attributes to
* accompany the binding. Either the object or the attributes may be null.
*<li>
* The state factories tried must each implement either
* <tt>StateFactory</tt> or <tt>DirStateFactory</tt>.
* If it implements <tt>DirStateFactory</tt>, then
* <tt>DirStateFactory.getStateToBind()</tt> is called; otherwise,
* <tt>StateFactory.getStateToBind()</tt> is called.
* {@code StateFactory} or {@code DirStateFactory}.
* If it implements {@code DirStateFactory}, then
* {@code DirStateFactory.getStateToBind()} is called; otherwise,
* {@code StateFactory.getStateToBind()} is called.
*</ul>
*
* Service providers that implement the <tt>DirContext</tt> interface
* should use this method, not <tt>NamingManager.getStateToBind()</tt>.
* Service providers that implement the {@code DirContext} interface
* should use this method, not {@code NamingManager.getStateToBind()}.
*<p>
* See NamingManager.getStateToBind() for a description of how
* the list of state factories to be tried is determined.
*<p>
* The object returned by this method is owned by the caller.
* The implementation will not subsequently modify it.
* It will contain either a new <tt>Attributes</tt> object that is
* It will contain either a new {@code Attributes} object that is
* likewise owned by the caller, or a reference to the original
* <tt>attrs</tt> parameter.
* {@code attrs} parameter.
*
* @param obj The non-null object for which to get state to bind.
* @param name The name of this object relative to <code>nameCtx</code>,
* @param name The name of this object relative to {@code nameCtx},
* or null if no name is specified.
* @param nameCtx The context relative to which the <code>name</code>
* parameter is specified, or null if <code>name</code> is
* @param nameCtx The context relative to which the {@code name}
* parameter is specified, or null if {@code name} is
* relative to the default initial context.
* @param environment The possibly null environment to
* be used in the creation of the state factory and
@ -288,12 +288,12 @@ public class DirectoryManager extends NamingManager {
* @return A non-null DirStateFactory.Result containing
* the object and attributes to be bound.
* If no state factory returns a non-null answer, the result will contain
* the object (<tt>obj</tt>) itself with the original attributes.
* the object ({@code obj}) itself with the original attributes.
* @exception NamingException If a naming exception was encountered
* while using the factories.
* A factory should only throw an exception if it does not want
* other factories to be used in an attempt to create an object.
* See <tt>DirStateFactory.getStateToBind()</tt>.
* See {@code DirStateFactory.getStateToBind()}.
* @see DirStateFactory
* @see DirStateFactory#getStateToBind
* @see NamingManager#getStateToBind

128
jdk/src/java.naming/share/classes/javax/naming/spi/NamingManager.java
View File

@ -49,7 +49,7 @@ import com.sun.naming.internal.FactoryEnumeration;
* NamingManager is safe for concurrent access by multiple threads.
*<p>
* Except as otherwise noted,
* a <tt>Name</tt> or environment parameter
* a {@code Name} or environment parameter
* passed to any method is owned by the caller.
* The implementation will not modify the object or keep a reference
* to it, although it may keep a reference to a clone or copy.
@ -164,8 +164,8 @@ public class NamingManager {
/**
* Creates an object using the factories specified in the
* <tt>Context.OBJECT_FACTORIES</tt> property of the environment
* or of the provider resource file associated with <tt>nameCtx</tt>.
* {@code Context.OBJECT_FACTORIES} property of the environment
* or of the provider resource file associated with {@code nameCtx}.
*
* @return factory created; null if cannot create
*/
@ -205,69 +205,69 @@ public class NamingManager {
* create a factory for creating the object.
* Otherwise, the following rules are used to create the object:
*<ol>
* <li>If <code>refInfo</code> is a <code>Reference</code>
* or <code>Referenceable</code> containing a factory class name,
* <li>If {@code refInfo} is a {@code Reference}
* or {@code Referenceable} containing a factory class name,
* use the named factory to create the object.
* Return <code>refInfo</code> if the factory cannot be created.
* Return {@code refInfo} if the factory cannot be created.
* Under JDK 1.1, if the factory class must be loaded from a location
* specified in the reference, a <tt>SecurityManager</tt> must have
* specified in the reference, a {@code SecurityManager} must have
* been installed or the factory creation will fail.
* If an exception is encountered while creating the factory,
* it is passed up to the caller.
* <li>If <tt>refInfo</tt> is a <tt>Reference</tt> or
* <tt>Referenceable</tt> with no factory class name,
* and the address or addresses are <tt>StringRefAddr</tt>s with
* <li>If {@code refInfo} is a {@code Reference} or
* {@code Referenceable} with no factory class name,
* and the address or addresses are {@code StringRefAddr}s with
* address type "URL",
* try the URL context factory corresponding to each URL's scheme id
* to create the object (see <tt>getURLContext()</tt>).
* to create the object (see {@code getURLContext()}).
* If that fails, continue to the next step.
* <li> Use the object factories specified in
* the <tt>Context.OBJECT_FACTORIES</tt> property of the environment,
* the {@code Context.OBJECT_FACTORIES} property of the environment,
* and of the provider resource file associated with
* <tt>nameCtx</tt>, in that order.
* {@code nameCtx}, in that order.
* The value of this property is a colon-separated list of factory
* class names that are tried in order, and the first one that succeeds
* in creating an object is the one used.
* If none of the factories can be loaded,
* return <code>refInfo</code>.
* return {@code refInfo}.
* If an exception is encountered while creating the object, the
* exception is passed up to the caller.
*</ol>
*<p>
* Service providers that implement the <tt>DirContext</tt>
* Service providers that implement the {@code DirContext}
* interface should use
* <tt>DirectoryManager.getObjectInstance()</tt>, not this method.
* Service providers that implement only the <tt>Context</tt>
* {@code DirectoryManager.getObjectInstance()}, not this method.
* Service providers that implement only the {@code Context}
* interface should use this method.
* <p>
* Note that an object factory (an object that implements the ObjectFactory
* interface) must be public and must have a public constructor that
* accepts no arguments.
* <p>
* The <code>name</code> and <code>nameCtx</code> parameters may
* The {@code name} and {@code nameCtx} parameters may
* optionally be used to specify the name of the object being created.
* <code>name</code> is the name of the object, relative to context
* <code>nameCtx</code>. This information could be useful to the object
* {@code name} is the name of the object, relative to context
* {@code nameCtx}. This information could be useful to the object
* factory or to the object implementation.
* If there are several possible contexts from which the object
* could be named -- as will often be the case -- it is up to
* the caller to select one. A good rule of thumb is to select the
* "deepest" context available.
* If <code>nameCtx</code> is null, <code>name</code> is relative
* If {@code nameCtx} is null, {@code name} is relative
* to the default initial context. If no name is being specified, the
* <code>name</code> parameter should be null.
* {@code name} parameter should be null.
*
* @param refInfo The possibly null object for which to create an object.
* @param name The name of this object relative to <code>nameCtx</code>.
* @param name The name of this object relative to {@code nameCtx}.
* Specifying a name is optional; if it is
* omitted, <code>name</code> should be null.
* @param nameCtx The context relative to which the <code>name</code>
* parameter is specified. If null, <code>name</code> is
* omitted, {@code name} should be null.
* @param nameCtx The context relative to which the {@code name}
* parameter is specified. If null, {@code name} is
* relative to the default initial context.
* @param environment The possibly null environment to
* be used in the creation of the object factory and the object.
* @return An object created using <code>refInfo</code>; or
* <code>refInfo</code> if an object cannot be created using
* @return An object created using {@code refInfo}; or
* {@code refInfo} if an object cannot be created using
* the algorithm described above.
* @exception NamingException if a naming exception was encountered
* while attempting to get a URL context, or if one of the
@ -404,23 +404,23 @@ public class NamingManager {
/**
* Retrieves a context identified by <code>obj</code>, using the specified
* Retrieves a context identified by {@code obj}, using the specified
* environment.
* Used by ContinuationContext.
*
* @param obj The object identifying the context.
* @param name The name of the context being returned, relative to
* <code>nameCtx</code>, or null if no name is being
* {@code nameCtx}, or null if no name is being
* specified.
* See the <code>getObjectInstance</code> method for
* See the {@code getObjectInstance} method for
* details.
* @param nameCtx The context relative to which <code>name</code> is
* @param nameCtx The context relative to which {@code name} is
* specified, or null for the default initial context.
* See the <code>getObjectInstance</code> method for
* See the {@code getObjectInstance} method for
* details.
* @param environment Environment specifying characteristics of the
* resulting context.
* @return A context identified by <code>obj</code>.
* @return A context identified by {@code obj}.
*
* @see #getObjectInstance
*/
@ -480,7 +480,7 @@ public class NamingManager {
* Creates a context for the given URL scheme id.
* <p>
* The resulting context is for resolving URLs of the
* scheme <code>scheme</code>. The resulting context is not tied
* scheme {@code scheme}. The resulting context is not tied
* to a specific URL. It is able to handle arbitrary URLs with
* the specified scheme.
*<p>
@ -488,7 +488,7 @@ public class NamingManager {
* has the naming convention <i>scheme-id</i>URLContextFactory
* (e.g. "ftpURLContextFactory" for the "ftp" scheme-id),
* in the package specified as follows.
* The <tt>Context.URL_PKG_PREFIXES</tt> environment property (which
* The {@code Context.URL_PKG_PREFIXES} environment property (which
* may contain values taken from system properties,
* or application resource files)
* contains a colon-separated list of package prefixes.
@ -500,7 +500,7 @@ public class NamingManager {
* concatenated with the scheme id.
*<p>
* For example, if the scheme id is "ldap", and the
* <tt>Context.URL_PKG_PREFIXES</tt> property
* {@code Context.URL_PKG_PREFIXES} property
* contains "com.widget:com.wiz.jndi",
* the naming manager would attempt to load the following classes
* until one is successfully instantiated:
@ -514,7 +514,7 @@ public class NamingManager {
* If a factory is instantiated, it is invoked with the following
* parameters to produce the resulting context.
* <p>
* <code>factory.getObjectInstance(null, environment);</code>
* {@code factory.getObjectInstance(null, environment);}
* <p>
* For example, invoking getObjectInstance() as shown above
* on a LDAP URL context factory would return a
@ -530,8 +530,8 @@ public class NamingManager {
* @param environment The possibly null environment properties to be
* used in the creation of the object factory and the context.
* @return A context for resolving URLs with the
* scheme id <code>scheme</code>;
* <code>null</code> if the factory for creating the
* scheme id {@code scheme};
* {@code null} if the factory for creating the
* context is not found.
* @exception NamingException If a naming exception occurs while creating
* the context.
@ -575,7 +575,7 @@ public class NamingManager {
* context factory for the URL scheme.
* @param scheme the URL scheme id for the context
* @param urlInfo information used to create the context
* @param name name of this object relative to <code>nameCtx</code>
* @param name name of this object relative to {@code nameCtx}
* @param nameCtx Context whose provider resource file will be searched
* for package prefix values (or null if none)
* @param environment Environment properties for creating the context
@ -630,7 +630,7 @@ public class NamingManager {
* it is used to create the factory for creating the initial
* context</li>
* <li>Otherwise, the class specified in the
* <tt>Context.INITIAL_CONTEXT_FACTORY</tt> environment property
* {@code Context.INITIAL_CONTEXT_FACTORY} environment property
* is used
* <ul>
* <li>First, the {@linkplain java.util.ServiceLoader ServiceLoader}
@ -649,7 +649,7 @@ public class NamingManager {
* creating the context.
* @return A non-null initial context.
* @exception NoInitialContextException If the
* <tt>Context.INITIAL_CONTEXT_FACTORY</tt> property
* {@code Context.INITIAL_CONTEXT_FACTORY} property
* is not found or names a nonexistent
* class or a class that cannot be instantiated,
* or if the initial context could not be created for some other
@ -764,8 +764,8 @@ public class NamingManager {
/**
* Constant that holds the name of the environment property into
* which <tt>getContinuationContext()</tt> stores the value of its
* <tt>CannotProceedException</tt> parameter.
* which {@code getContinuationContext()} stores the value of its
* {@code CannotProceedException} parameter.
* This property is inherited by the continuation context, and may
* be used by that context's service provider to inspect the
* fields of the exception.
@ -784,18 +784,18 @@ public class NamingManager {
* namespaces, a context from one naming system may need to pass
* the operation on to the next naming system. The context
* implementation does this by first constructing a
* <code>CannotProceedException</code> containing information
* {@code CannotProceedException} containing information
* pinpointing how far it has proceeded. It then obtains a
* continuation context from JNDI by calling
* <code>getContinuationContext</code>. The context
* {@code getContinuationContext}. The context
* implementation should then resume the context operation by
* invoking the same operation on the continuation context, using
* the remainder of the name that has not yet been resolved.
*<p>
* Before making use of the <tt>cpe</tt> parameter, this method
* Before making use of the {@code cpe} parameter, this method
* updates the environment associated with that object by setting
* the value of the property <a href="#CPE"><tt>CPE</tt></a>
* to <tt>cpe</tt>. This property will be inherited by the
* the value of the property <a href="#CPE">{@code CPE}</a>
* to {@code cpe}. This property will be inherited by the
* continuation context, and may be used by that context's
* service provider to inspect the fields of this exception.
*
@ -826,15 +826,15 @@ public class NamingManager {
/**
* Retrieves the state of an object for binding.
* <p>
* Service providers that implement the <tt>DirContext</tt> interface
* should use <tt>DirectoryManager.getStateToBind()</tt>, not this method.
* Service providers that implement only the <tt>Context</tt> interface
* Service providers that implement the {@code DirContext} interface
* should use {@code DirectoryManager.getStateToBind()}, not this method.
* Service providers that implement only the {@code Context} interface
* should use this method.
*<p>
* This method uses the specified state factories in
* the <tt>Context.STATE_FACTORIES</tt> property from the environment
* the {@code Context.STATE_FACTORIES} property from the environment
* properties, and from the provider resource file associated with
* <tt>nameCtx</tt>, in that order.
* {@code nameCtx}, in that order.
* The value of this property is a colon-separated list of factory
* class names that are tried in order, and the first one that succeeds
* in returning the object's state is the one used.
@ -848,35 +848,35 @@ public class NamingManager {
* interface) must be public and must have a public constructor that
* accepts no arguments.
* <p>
* The <code>name</code> and <code>nameCtx</code> parameters may
* The {@code name} and {@code nameCtx} parameters may
* optionally be used to specify the name of the object being created.
* See the description of "Name and Context Parameters" in
* {@link ObjectFactory#getObjectInstance
* ObjectFactory.getObjectInstance()}
* for details.
* <p>
* This method may return a <tt>Referenceable</tt> object. The
* This method may return a {@code Referenceable} object. The
* service provider obtaining this object may choose to store it
* directly, or to extract its reference (using
* <tt>Referenceable.getReference()</tt>) and store that instead.
* {@code Referenceable.getReference()}) and store that instead.
*
* @param obj The non-null object for which to get state to bind.
* @param name The name of this object relative to <code>nameCtx</code>,
* @param name The name of this object relative to {@code nameCtx},
* or null if no name is specified.
* @param nameCtx The context relative to which the <code>name</code>
* parameter is specified, or null if <code>name</code> is
* @param nameCtx The context relative to which the {@code name}
* parameter is specified, or null if {@code name} is
* relative to the default initial context.
* @param environment The possibly null environment to
* be used in the creation of the state factory and
* the object's state.
* @return The non-null object representing <tt>obj</tt>'s state for
* binding. It could be the object (<tt>obj</tt>) itself.
* @return The non-null object representing {@code obj}'s state for
* binding. It could be the object ({@code obj}) itself.
* @exception NamingException If one of the factories accessed throws an
* exception, or if an error was encountered while loading
* and instantiating the factory and object classes.
* A factory should only throw an exception if it does not want
* other factories to be used in an attempt to create an object.
* See <tt>StateFactory.getStateToBind()</tt>.
* See {@code StateFactory.getStateToBind()}.
* @see StateFactory
* @see StateFactory#getStateToBind
* @see DirectoryManager#getStateToBind

50
jdk/src/java.naming/share/classes/javax/naming/spi/ObjectFactory.java
View File

@ -39,15 +39,15 @@ import javax.naming.*;
* Reference could be used to create a printer object, so that
* the caller of lookup can directly operate on the printer object
* after the lookup.
* <p>An <tt>ObjectFactory</tt> is responsible
* <p>An {@code ObjectFactory} is responsible
* for creating objects of a specific type. In the above example,
* you may have a PrinterObjectFactory for creating Printer objects.
*<p>
* An object factory must implement the <tt>ObjectFactory</tt> interface.
* An object factory must implement the {@code ObjectFactory} interface.
* In addition, the factory class must be public and must have a
* public constructor that accepts no parameters.
*<p>
* The <tt>getObjectInstance()</tt> method of an object factory may
* The {@code getObjectInstance()} method of an object factory may
* be invoked multiple times, possibly using different parameters.
* The implementation is thread-safe.
*<p>
@ -73,15 +73,15 @@ public interface ObjectFactory {
* specified.
* <p>
* Special requirements of this object are supplied
* using <code>environment</code>.
* using {@code environment}.
* An example of such an environment property is user identity
* information.
*<p>
* <tt>NamingManager.getObjectInstance()</tt>
* {@code NamingManager.getObjectInstance()}
* successively loads in object factories and invokes this method
* on them until one produces a non-null answer. When an exception
* is thrown by an object factory, the exception is passed on to the caller
* of <tt>NamingManager.getObjectInstance()</tt>
* of {@code NamingManager.getObjectInstance()}
* (and no search is made for other factories
* that may produce a non-null answer).
* An object factory should only throw an exception if it is sure that
@ -92,27 +92,27 @@ public interface ObjectFactory {
*<p>
* A <em>URL context factory</em> is a special ObjectFactory that
* creates contexts for resolving URLs or objects whose locations
* are specified by URLs. The <tt>getObjectInstance()</tt> method
* are specified by URLs. The {@code getObjectInstance()} method
* of a URL context factory will obey the following rules.
* <ol>
* <li>If <code>obj</code> is null, create a context for resolving URLs of the
* <li>If {@code obj} is null, create a context for resolving URLs of the
* scheme associated with this factory. The resulting context is not tied
* to a specific URL: it is able to handle arbitrary URLs with this factory's
* scheme id. For example, invoking <tt>getObjectInstance()</tt> with
* <code>obj</code> set to null on an LDAP URL context factory would return a
* scheme id. For example, invoking {@code getObjectInstance()} with
* {@code obj} set to null on an LDAP URL context factory would return a
* context that can resolve LDAP URLs
* such as "ldap://ldap.wiz.com/o=wiz,c=us" and
* "ldap://ldap.umich.edu/o=umich,c=us".
* <li>
* If <code>obj</code> is a URL string, create an object (typically a context)
* If {@code obj} is a URL string, create an object (typically a context)
* identified by the URL. For example, suppose this is an LDAP URL context
* factory. If <code>obj</code> is "ldap://ldap.wiz.com/o=wiz,c=us",
* factory. If {@code obj} is "ldap://ldap.wiz.com/o=wiz,c=us",
* getObjectInstance() would return the context named by the distinguished
* name "o=wiz, c=us" at the LDAP server ldap.wiz.com. This context can
* then be used to resolve LDAP names (such as "cn=George")
* relative to that context.
* <li>
* If <code>obj</code> is an array of URL strings, the assumption is that the
* If {@code obj} is an array of URL strings, the assumption is that the
* URLs are equivalent in terms of the context to which they refer.
* Verification of whether the URLs are, or need to be, equivalent is up
* to the context factory. The order of the URLs in the array is
@ -120,13 +120,13 @@ public interface ObjectFactory {
* The object returned by getObjectInstance() is like that of the single
* URL case. It is the object named by the URLs.
* <li>
* If <code>obj</code> is of any other type, the behavior of
* <tt>getObjectInstance()</tt> is determined by the context factory
* If {@code obj} is of any other type, the behavior of
* {@code getObjectInstance()} is determined by the context factory
* implementation.
* </ol>
*
* <p>
* The <tt>name</tt> and <tt>environment</tt> parameters
* The {@code name} and {@code environment} parameters
* are owned by the caller.
* The implementation will not modify these objects or keep references
* to them, although it may keep references to clones or copies.
@ -135,27 +135,27 @@ public interface ObjectFactory {
* <b>Name and Context Parameters.</b> &nbsp;&nbsp;&nbsp;
* <a name=NAMECTX></a>
*
* The <code>name</code> and <code>nameCtx</code> parameters may
* The {@code name} and {@code nameCtx} parameters may
* optionally be used to specify the name of the object being created.
* <code>name</code> is the name of the object, relative to context
* <code>nameCtx</code>.
* {@code name} is the name of the object, relative to context
* {@code nameCtx}.
* If there are several possible contexts from which the object
* could be named -- as will often be the case -- it is up to
* the caller to select one. A good rule of thumb is to select the
* "deepest" context available.
* If <code>nameCtx</code> is null, <code>name</code> is relative
* If {@code nameCtx} is null, {@code name} is relative
* to the default initial context. If no name is being specified, the
* <code>name</code> parameter should be null.
* If a factory uses <code>nameCtx</code> it should synchronize its use
* {@code name} parameter should be null.
* If a factory uses {@code nameCtx} it should synchronize its use
* against concurrent access, since context implementations are not
* guaranteed to be thread-safe.
*
* @param obj The possibly null object containing location or reference
* information that can be used in creating an object.
* @param name The name of this object relative to <code>nameCtx</code>,
* @param name The name of this object relative to {@code nameCtx},
* or null if no name is specified.
* @param nameCtx The context relative to which the <code>name</code>
* parameter is specified, or null if <code>name</code> is
* @param nameCtx The context relative to which the {@code name}
* parameter is specified, or null if {@code name} is
* relative to the default initial context.
* @param environment The possibly null environment that is used in
* creating the object.

4
jdk/src/java.naming/share/classes/javax/naming/spi/ObjectFactoryBuilder.java
View File

@ -40,10 +40,10 @@ import javax.naming.NamingException;
* after the lookup. An ObjectFactory is responsible for creating
* objects of a specific type. JNDI uses a default policy for using
* and loading object factories. You can override this default policy
* by calling <tt>NamingManager.setObjectFactoryBuilder()</tt> with an ObjectFactoryBuilder,
* by calling {@code NamingManager.setObjectFactoryBuilder()} with an ObjectFactoryBuilder,
* which contains the program-defined way of creating/loading
* object factories.
* Any <tt>ObjectFactoryBuilder</tt> implementation must implement this
* Any {@code ObjectFactoryBuilder} implementation must implement this
* interface that for creating object factories.
*
* @author Rosanna Lee

4
jdk/src/java.naming/share/classes/javax/naming/spi/Resolver.java
View File

@ -37,10 +37,10 @@ import javax.naming.NamingException;
* that do not support subtypes of Context, but which can act as
* intermediate contexts for resolution purposes.
*<p>
* A <tt>Name</tt> parameter passed to any method is owned
* A {@code Name} parameter passed to any method is owned
* by the caller. The service provider will not modify the object
* or keep a reference to it.
* A <tt>ResolveResult</tt> object returned by any
* A {@code ResolveResult} object returned by any
* method is owned by the caller. The caller may subsequently modify it;
* the service provider may not.
*

44
jdk/src/java.naming/share/classes/javax/naming/spi/StateFactory.java
View File

@ -34,14 +34,14 @@ import java.util.Hashtable;
* The JNDI framework allows for object implementations to
* be loaded in dynamically via <em>object factories</em>.
* For example, when looking up a printer bound in the name space,
* if the print service binds printer names to <tt>Reference</tt>s, the printer
* <tt>Reference</tt> could be used to create a printer object, so that
* if the print service binds printer names to {@code Reference}s, the printer
* {@code Reference} could be used to create a printer object, so that
* the caller of lookup can directly operate on the printer object
* after the lookup.
* <p>An <tt>ObjectFactory</tt> is responsible
* <p>An {@code ObjectFactory} is responsible
* for creating objects of a specific type. In the above example,
* you may have a <tt>PrinterObjectFactory</tt> for creating
* <tt>Printer</tt> objects.
* you may have a {@code PrinterObjectFactory} for creating
* {@code Printer} objects.
* <p>
* For the reverse process, when an object is bound into the namespace,
* JNDI provides <em>state factories</em>.
@ -50,23 +50,23 @@ import java.util.Hashtable;
* <blockquote><pre>
* ctx.rebind("inky", printer);
* </pre></blockquote>
* The service provider for <tt>ctx</tt> uses a state factory
* to obtain the state of <tt>printer</tt> for binding into its namespace.
* A state factory for the <tt>Printer</tt> type object might return
* The service provider for {@code ctx} uses a state factory
* to obtain the state of {@code printer} for binding into its namespace.
* A state factory for the {@code Printer} type object might return
* a more compact object for storage in the naming system.
*<p>
* A state factory must implement the <tt>StateFactory</tt> interface.
* A state factory must implement the {@code StateFactory} interface.
* In addition, the factory class must be public and must have a
* public constructor that accepts no parameters.
*<p>
* The <tt>getStateToBind()</tt> method of a state factory may
* The {@code getStateToBind()} method of a state factory may
* be invoked multiple times, possibly using different parameters.
* The implementation is thread-safe.
*<p>
* <tt>StateFactory</tt> is intended for use with service providers
* that implement only the <tt>Context</tt> interface.
* <tt>DirStateFactory</tt> is intended for use with service providers
* that implement the <tt>DirContext</tt> interface.
* {@code StateFactory} is intended for use with service providers
* that implement only the {@code Context} interface.
* {@code DirStateFactory} is intended for use with service providers
* that implement the {@code DirContext} interface.
*
* @author Rosanna Lee
* @author Scott Seligman
@ -81,18 +81,18 @@ public interface StateFactory {
/**
* Retrieves the state of an object for binding.
*<p>
* <tt>NamingManager.getStateToBind()</tt>
* {@code NamingManager.getStateToBind()}
* successively loads in state factories and invokes this method
* on them until one produces a non-null answer.
* <tt>DirectoryManager.getStateToBind()</tt>
* {@code DirectoryManager.getStateToBind()}
* successively loads in state factories. If a factory implements
* <tt>DirStateFactory</tt>, then <tt>DirectoryManager</tt>
* invokes <tt>DirStateFactory.getStateToBind()</tt>; otherwise
* it invokes <tt>StateFactory.getStateToBind()</tt>.
* {@code DirStateFactory}, then {@code DirectoryManager}
* invokes {@code DirStateFactory.getStateToBind()}; otherwise
* it invokes {@code StateFactory.getStateToBind()}.
*<p> When an exception
* is thrown by a factory, the exception is passed on to the caller
* of <tt>NamingManager.getStateToBind()</tt> and
* <tt>DirectoryManager.getStateToBind()</tt>.
* of {@code NamingManager.getStateToBind()} and
* {@code DirectoryManager.getStateToBind()}.
* The search for other factories
* that may produce a non-null answer is halted.
* A factory should only throw an exception if it is sure that
@ -110,7 +110,7 @@ public interface StateFactory {
* against concurrent access, since context implementations are not
* guaranteed to be thread-safe.
* <p>
* The <tt>name</tt> and <tt>environment</tt> parameters
* The {@code name} and {@code environment} parameters
* are owned by the caller.
* The implementation will not modify these objects or keep references
* to them, although it may keep references to clones or copies.

6
jdk/src/java.naming/share/classes/javax/naming/spi/package.html
View File

@ -29,7 +29,7 @@ questions.
<body bgcolor="white">
Provides the means for dynamically plugging in support for accessing
naming and directory services through the <tt>javax.naming</tt>
naming and directory services through the <code>javax.naming</code>
and related packages.
<p>
@ -58,9 +58,9 @@ from the initial context.
<h4>Java Object Support</h4>
The service provider package provides support
The service provider package provides support
for implementors of the
<tt>javax.naming.Context.lookup()</tt>
<code>javax.naming.Context.lookup()</code>
method and related methods to return Java objects that are natural
and intuitive for the Java programmer.
For example, when looking up a printer name from the directory,