Hi Joe,
Looks good.
fwiw, I was able to use H3 vs H1 tags to make doclint accessibility happy.
Not sure if it matters below but thought I would point it out if you want a
smaller heading
Best
Lance
On Jun 28, 2013, at 1:54 PM, Joe Darcy wrote:
> Hello,
>
> Still more doclint fixes for review below; this time to javax.naming.*.
>
> Thanks,
>
> -Joe
>
> --- a/src/share/classes/javax/naming/CompositeName.java Fri Jun 28
> 16:39:15 2013 +0100
> +++ b/src/share/classes/javax/naming/CompositeName.java Fri Jun 28
> 10:54:12 2013 -0700
> @@ -1,5 +1,5 @@
> /*
> - * Copyright (c) 1999, 2011, Oracle and/or its affiliates. All rights
> reserved.
> + * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights
> reserved.
> * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
> *
> * This code is free software; you can redistribute it and/or modify it
> @@ -42,7 +42,7 @@
> * The most significant component is at index 0.
> * An empty composite name has no components.
> *<p>
> - * <h4>JNDI Composite Name Syntax</h4>
> + * <h1>JNDI Composite Name Syntax</h1>
> * JNDI defines a standard string representation for composite names. This
> * representation is the concatenation of the components of a composite name
> * from left to right using the component separator (a forward
> @@ -73,12 +73,12 @@
> * a separator) denotes a trailing empty component.
> * Adjacent component separators denote an empty component.
> *<p>
> - *<h4>Composite Name Examples</h4>
> + *<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>).
> *<p>
> -<table border="1" cellpadding=3 width="70%" summary="examples showing string
> form of composite name and its corresponding structural form (CompositeName)">
> +<table border="1" cellpadding=3 summary="examples showing string form of
> composite name and its corresponding structural form (CompositeName)">
>
> <tr>
> <th>String Name</th>
> @@ -137,14 +137,14 @@
> </tr>
> </table>
> * <p>
> - *<h4>Composition Examples</h4>
> + *<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
> * string forms of two composite names simply involves concatenating
> * their string forms together.
>
> -<p> <table border="1" cellpadding=3 width="70%" summary="composition
> examples showing string names and composite names">
> +<p> <table border="1" cellpadding=3 summary="composition examples showing
> string names and composite names">
>
> <tr>
> <th>String Names</th>
> @@ -189,7 +189,7 @@
>
> </table>
> *<p>
> - *<h4>Multithreaded Access</h4>
> + *<h1>Multithreaded Access</h1>
> * A <tt>CompositeName</tt> instance is not synchronized against concurrent
> * multithreaded access. Multiple threads trying to access and modify a
> * <tt>CompositeName</tt> should lock the object.
> diff -r 52b4527d3fc7 src/share/classes/javax/naming/CompoundName.java
> --- a/src/share/classes/javax/naming/CompoundName.java Fri Jun 28 16:39:15
> 2013 +0100
> +++ b/src/share/classes/javax/naming/CompoundName.java Fri Jun 28 10:54:12
> 2013 -0700
> @@ -1,5 +1,5 @@
> /*
> - * Copyright (c) 1999, 2011, Oracle and/or its affiliates. All rights
> reserved.
> + * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights
> reserved.
> * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
> *
> * This code is free software; you can redistribute it and/or modify it
> @@ -39,7 +39,7 @@
> * The most significant component is at index 0.
> * An empty compound name has no components.
> *<p>
> - * <h4>Compound Name Syntax</h4>
> + * <h1>Compound Name Syntax</h1>
> * The syntax of a compound name is specified using a set of properties:
> *<dl>
> * <dt>jndi.syntax.direction
> @@ -136,7 +136,7 @@
> * so that when the same string is parsed, it will yield the same components
> * of the original compound name.
> *<p>
> - *<h4>Multithreaded Access</h4>
> + *<h1>Multithreaded Access</h1>
> * A <tt>CompoundName</tt> instance is not synchronized against concurrent
> * multithreaded access. Multiple threads trying to access and modify a
> * <tt>CompoundName</tt> should lock the object.
> diff -r 52b4527d3fc7 src/share/classes/javax/naming/Context.java
> --- a/src/share/classes/javax/naming/Context.java Fri Jun 28 16:39:15 2013
> +0100
> +++ b/src/share/classes/javax/naming/Context.java Fri Jun 28 10:54:12 2013
> -0700
> @@ -1,5 +1,5 @@
> /*
> - * Copyright (c) 1999, 2006, Oracle and/or its affiliates. All rights
> reserved.
> + * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights
> reserved.
> * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
> *
> * This code is free software; you can redistribute it and/or modify it
> @@ -32,7 +32,7 @@
> * consists of a set of name-to-object bindings.
> * It contains methods for examining and updating these bindings.
> * <p>
> - * <h4>Names</h4>
> + * <h1>Names</h1>
> * Each name passed as an argument to a <tt>Context</tt> method is relative
> * to that context. The empty name is used to name the context itself.
> * A name parameter may never be null.
> @@ -69,12 +69,12 @@
> * names in a composite namespace, at the discretion of the service
> * provider.
> *<p>
> - *<h4>Exceptions</h4>
> + *<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
> * for details on each exception.
> *<p>
> - *<h4>Concurrent Access</h4>
> + *<h1>Concurrent Access</h1>
> * A Context instance is not guaranteed to be synchronized against
> * concurrent access by multiple threads. Threads that need to access
> * a single Context instance concurrently should synchronize amongst
> @@ -91,7 +91,7 @@
> * being followed.
> *
> *<p>
> - *<h4>Parameters</h4>
> + *<h1>Parameters</h1>
> * A <tt>Name</tt> parameter passed to any method of the
> * <tt>Context</tt> interface or one of its subinterfaces
> * will not be modified by the service provider.
> @@ -103,7 +103,7 @@
> * The caller may subsequently modify it; the service provider may not.
> *
> *<p>
> - *<h4>Environment Properties</h4>
> + *<h1>Environment Properties</h1>
> *<p>
> * JNDI applications need a way to communicate various preferences
> * and properties that define the environment in which naming and
> @@ -138,7 +138,7 @@
> *
> *<p>
> *<a name=RESOURCEFILES></a>
> - *<h4>Resource Files</h4>
> + *<h1>Resource Files</h1>
> *<p>
> * To simplify the task of setting up the environment
> * required by a JNDI application,
> @@ -151,11 +151,11 @@
> * and the value is a string in the format defined
> * for that property. Here is an example of a JNDI resource file:
> *
> - * <blockquote><tt><pre>
> + * <blockquote>{@code
> *
> java.naming.factory.object=com.sun.jndi.ldap.AttrsToCorba:com.wiz.from.Person
> *
> java.naming.factory.state=com.sun.jndi.ldap.CorbaToAttrs:com.wiz.from.Person
> * java.naming.factory.control=com.sun.jndi.ldap.ResponseControlFactory
> - * </pre></tt></blockquote>
> + * }</blockquote>
> *
> * The JNDI class library reads the resource files and makes the property
> * values freely available. Thus JNDI resource files should be considered
> @@ -165,7 +165,7 @@
> * There are two kinds of JNDI resource files:
> * <em>provider</em> and <em>application</em>.
> *
> - * <h5>Provider Resource Files</h5>
> + * <h2>Provider Resource Files</h2>
> *
> * Each service provider has an optional resource that lists properties
> * specific to that provider. The name of this resource is:
> @@ -200,7 +200,7 @@
> * The service provider's documentation should clearly state which
> * properties are allowed; other properties in the file will be ignored.
> *
> - * <h5>Application Resource Files</h5>
> + * <h2>Application Resource Files</h2>
> *
> * When an application is deployed, it will generally have several
> * codebase directories and JARs in its classpath. Similarly, when an
> @@ -232,7 +232,7 @@
> * collects and uses all of these export lists when searching for factory
> * classes.
> *
> - * <h5>Search Algorithm for Properties</h5>
> + * <h2>Search Algorithm for Properties</h2>
> *
> * When JNDI constructs an initial context, the context's environment
> * is initialized with properties defined in the environment parameter
> diff -r 52b4527d3fc7 src/share/classes/javax/naming/InitialContext.java
> --- a/src/share/classes/javax/naming/InitialContext.java Fri Jun 28
> 16:39:15 2013 +0100
> +++ b/src/share/classes/javax/naming/InitialContext.java Fri Jun 28
> 10:54:12 2013 -0700
> @@ -1,5 +1,5 @@
> /*
> - * Copyright (c) 1999, 2011, Oracle and/or its affiliates. All rights
> reserved.
> + * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights
> reserved.
> * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
> *
> * This code is free software; you can redistribute it and/or modify it
> @@ -258,6 +258,7 @@
> * environment may be modified independently and it may be accessed
> * concurrently).
> *
> + * @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>
> @@ -276,11 +277,12 @@
> /**
> * A static method to retrieve the named object.
> * See {@link #doLookup(Name)} for details.
> + * @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>
> * @throws NamingException if a naming exception is encountered
> - * @since 1.6
> + * @since 1.6
> */
> @SuppressWarnings("unchecked")
> public static <T> T doLookup(String name)
> diff -r 52b4527d3fc7 src/share/classes/javax/naming/RefAddr.java
> --- a/src/share/classes/javax/naming/RefAddr.java Fri Jun 28 16:39:15 2013
> +0100
> +++ b/src/share/classes/javax/naming/RefAddr.java Fri Jun 28 10:54:12 2013
> -0700
> @@ -1,5 +1,5 @@
> /*
> - * Copyright (c) 1999, 2000, Oracle and/or its affiliates. All rights
> reserved.
> + * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights
> reserved.
> * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
> *
> * This code is free software; you can redistribute it and/or modify it
> @@ -91,7 +91,8 @@
> * Determines whether obj is equal to this RefAddr.
> *<p>
> * obj is equal to this RefAddr all of these conditions are true
> - *<ul> non-null
> + *<ul>
> + *<li> non-null
> *<li> instance of RefAddr
> *<li> obj has the same address type as this RefAddr (using
> String.compareTo())
> *<li> both obj and this RefAddr's contents are null or they are equal
> diff -r 52b4527d3fc7 src/share/classes/javax/naming/ReferralException.java
> --- a/src/share/classes/javax/naming/ReferralException.java Fri Jun 28
> 16:39:15 2013 +0100
> +++ b/src/share/classes/javax/naming/ReferralException.java Fri Jun 28
> 10:54:12 2013 -0700
> @@ -1,5 +1,5 @@
> /*
> - * Copyright (c) 1999, 2004, Oracle and/or its affiliates. All rights
> reserved.
> + * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights
> reserved.
> * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
> *
> * This code is free software; you can redistribute it and/or modify it
> @@ -38,7 +38,7 @@
> * constructors and/or corresponding "set" methods).
> * <p>
> * The following code sample shows how <tt>ReferralException</tt> can be used.
> - * <p><blockquote><pre>
> + * <blockquote>{@code
> * while (true) {
> * try {
> * bindings = ctx.listBindings(name);
> @@ -51,7 +51,7 @@
> * ctx = e.getReferralContext();
> * }
> * }
> - * </pre></blockquote></p>
> + * }</blockquote>
> *<p>
> * <tt>ReferralException</tt> is an abstract class. Concrete implementations
> * determine its synchronization and serialization properties.
> diff -r 52b4527d3fc7 src/share/classes/javax/naming/directory/DirContext.java
> --- a/src/share/classes/javax/naming/directory/DirContext.java Fri Jun 28
> 16:39:15 2013 +0100
> +++ b/src/share/classes/javax/naming/directory/DirContext.java Fri Jun 28
> 10:54:12 2013 -0700
> @@ -1,5 +1,5 @@
> /*
> - * Copyright (c) 1999, 2005, Oracle and/or its affiliates. All rights
> reserved.
> + * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights
> reserved.
> * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
> *
> * This code is free software; you can redistribute it and/or modify it
> @@ -32,7 +32,7 @@
> * methods for examining and updating attributes
> * associated with objects, and for searching the directory.
> * <p>
> - * <h4>Names</h4>
> + * <h1>Names</h1>
> * Each name passed as an argument to a <tt>DirContext</tt> method is relative
> * to that context. The empty name is used to name the context itself.
> * The name parameter may never be null.
> @@ -51,7 +51,7 @@
> * name argument to the <tt>Context</tt> methods. These same rules
> * apply to the name argument to the <tt>DirContext</tt> methods.
> * <p>
> - * <h4>Attribute Models</h4>
> + * <h1>Attribute Models</h1>
> * There are two basic models of what attributes should be
> * associated with. First, attributes may be directly associated with a
> * DirContext object.
> @@ -81,7 +81,7 @@
> * whether an object's attributes are stored as part of the object, or stored
> * within the parent object and associated with the object's name.
> * <p>
> - * <h4>Attribute Type Names</h4>
> + * <h1>Attribute Type Names</h1>
> * In the <tt>getAttributes()</tt> and <tt>search()</tt> methods,
> * you can supply the attributes to return by supplying a list of
> * attribute names (strings).
> @@ -113,7 +113,7 @@
> * </ul>
> *
> * <p>
> - *<h4>Operational Attributes</h4>
> + *<h1>Operational Attributes</h1>
> *<p>
> * Some directories have the notion of "operational attributes" which are
> * attributes associated with a directory object for administrative
> @@ -127,7 +127,7 @@
> * In order to retrieve operational attributes, you must name them explicitly.
> *
> * <p>
> - * <h4>Named Context</h4>
> + * <h1>Named Context</h1>
> * <p>
> * There are certain methods in which the name must resolve to a context
> * (for example, when searching a single level context). The documentation
> @@ -138,7 +138,7 @@
> * Aside from these methods, there is no requirement that the
> * <em>named object</em> be a DirContext.
> *<p>
> - *<h4>Parameters</h4>
> + *<h1>Parameters</h1>
> *<p>
> * An <tt>Attributes</tt>, <tt>SearchControls</tt>, or array object
> * passed as a parameter to any method will not be modified by the
> @@ -150,7 +150,7 @@
> * the caller. The caller may subsequently modify it; the service
> * provider will not.
> *<p>
> - *<h4>Exceptions</h4>
> + *<h1>Exceptions</h1>
> *<p>
> * All the methods in this interface can throw a NamingException or
> * any of its subclasses. See NamingException and their subclasses
> diff -r 52b4527d3fc7 src/share/classes/javax/naming/event/EventContext.java
> --- a/src/share/classes/javax/naming/event/EventContext.java Fri Jun 28
> 16:39:15 2013 +0100
> +++ b/src/share/classes/javax/naming/event/EventContext.java Fri Jun 28
> 10:54:12 2013 -0700
> @@ -1,5 +1,5 @@
> /*
> - * Copyright (c) 1999, 2004, Oracle and/or its affiliates. All rights
> reserved.
> + * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights
> reserved.
> * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
> *
> * This code is free software; you can redistribute it and/or modify it
> @@ -34,7 +34,7 @@
> * Contains methods for registering/deregistering listeners to be notified of
> * events fired when objects named in a context changes.
> *<p>
> - *<h4>Target</h4>
> + *<h1>Target</h1>
> * The name parameter in the <tt>addNamingListener()</tt> 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.
> @@ -59,7 +59,7 @@
> * whether a <tt>EventContext</tt> supports registration
> * of nonexistent targets.
> *<p>
> - *<h4>Event Source</h4>
> + *<h1>Event Source</h1>
> * The <tt>EventContext</tt> instance on which you invoke the
> * registration methods is the <em>event source</em> of the events that are
> * (potentially) generated.
> @@ -93,7 +93,7 @@
> * 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.
> - *<h4>Lifetime of Registration</h4>
> + *<h1>Lifetime of Registration</h1>
> * A registered listener becomes deregistered when:
> *<ul>
> *<li>It is removed using <tt>removeNamingListener()</tt>.
> @@ -105,7 +105,7 @@
> * Until that point, a <tt>EventContext</tt> instance that has outstanding
> * listeners will continue to exist and be maintained by the service provider.
> *
> - *<h4>Listener Implementations</h4>
> + *<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>.
> @@ -118,7 +118,7 @@
> * of the listeners, this allows some service providers to optimize the
> * registration.
> *
> - *<h4>Threading Issues</h4>
> + *<h1>Threading Issues</h1>
> *
> * Like <tt>Context</tt> instances in general, instances of
> * <tt>EventContext</tt> are not guaranteed to be thread-safe.
> diff -r 52b4527d3fc7 src/share/classes/javax/naming/ldap/ControlFactory.java
> --- a/src/share/classes/javax/naming/ldap/ControlFactory.java Fri Jun 28
> 16:39:15 2013 +0100
> +++ b/src/share/classes/javax/naming/ldap/ControlFactory.java Fri Jun 28
> 10:54:12 2013 -0700
> @@ -1,5 +1,5 @@
> /*
> - * Copyright (c) 1999, 2010, Oracle and/or its affiliates. All rights
> reserved.
> + * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights
> reserved.
> * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
> *
> * This code is free software; you can redistribute it and/or modify it
> @@ -51,7 +51,7 @@
> */
>
> public abstract class ControlFactory {
> - /*
> + /**
> * Creates a new instance of a control factory.
> */
> protected ControlFactory() {
> diff -r 52b4527d3fc7
> src/share/classes/javax/naming/ldap/InitialLdapContext.java
> --- a/src/share/classes/javax/naming/ldap/InitialLdapContext.java Fri Jun 28
> 16:39:15 2013 +0100
> +++ b/src/share/classes/javax/naming/ldap/InitialLdapContext.java Fri Jun 28
> 10:54:12 2013 -0700
> @@ -38,7 +38,7 @@
> * <tt>javax.naming.InitialDirContext</tt> for details on synchronization,
> * and the policy for how an initial context is created.
> *
> - * <h4>Request Controls</h4>
> + * <h1>Request Controls</h1>
> * When you create an initial context (<tt>InitialLdapContext</tt>),
> * you can specify a list of request controls.
> * These controls will be used as the request controls for any
> diff -r 52b4527d3fc7 src/share/classes/javax/naming/ldap/LdapContext.java
> --- a/src/share/classes/javax/naming/ldap/LdapContext.java Fri Jun 28
> 16:39:15 2013 +0100
> +++ b/src/share/classes/javax/naming/ldap/LdapContext.java Fri Jun 28
> 10:54:12 2013 -0700
> @@ -1,5 +1,5 @@
> /*
> - * Copyright (c) 1999, 2000, Oracle and/or its affiliates. All rights
> reserved.
> + * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights
> reserved.
> * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
> *
> * This code is free software; you can redistribute it and/or modify it
> @@ -78,10 +78,8 @@
> * <h4>Context Request Controls</h4>
> * There are two ways in which a context instance gets its request controls:
> * <ol>
> - * <tt>
> - * <li>ldapContext.newInstance(<strong>reqCtls</strong>)
> - * <li>ldapContext.setRequestControls(<strong>reqCtls</strong>)
> - * </tt>
> + * <li><tt>ldapContext.newInstance(<strong>reqCtls</strong>)</tt>
> + * <li><tt>ldapContext.setRequestControls(<strong>reqCtls</strong>)</tt>
> * </ol>
> * where <tt>ldapContext</tt> is an instance of <tt>LdapContext</tt>.
> * Specifying <tt>null</tt> or an empty array for <tt>reqCtls</tt>
> @@ -102,12 +100,10 @@
> * <h4>Connection Request Controls</h4>
> * There are three ways in which connection request controls are set:
> * <ol>
> - * <tt>
> - * <li>
> - * new InitialLdapContext(env, <strong>connCtls</strong>)
> - * <li>refException.getReferralContext(env, <strong>connCtls</strong>)
> - * <li>ldapContext.reconnect(<strong>connCtls</strong>);
> - * </tt>
> + * <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>
> * </ol>
> * where <tt>refException</tt> is an instance of
> * <tt>LdapReferralException</tt>, and <tt>ldapContext</tt> is an
>
Lance Andersen| Principal Member of Technical Staff | +1.781.442.2037
Oracle Java Engineering
1 Network Drive
Burlington, MA 01803
lance.ander...@oracle.com
