JDK 8 RFR for JDK-8026840: Fix new doclint issues in javax.naming

Mandy Chung mandy.chung at oracle.com
Fri Oct 18 03:33:04 UTC 2013


Thumbs up.
Mandy

On 10/17/2013 7:45 PM, Joe Darcy wrote:
> Hello,
>
> Please review the patch below which addresses
>
>     JDK-8026840: Fix new doclint issues in javax.naming
>
> (A new version of doclint reveals additional issues.)
>
> Thanks,
>
> -Joe
>
> diff -r c1616a944d1c src/share/classes/javax/naming/CompositeName.java
> --- a/src/share/classes/javax/naming/CompositeName.java    Fri Oct 18 
> 08:57:52 2013 +0800
> +++ b/src/share/classes/javax/naming/CompositeName.java    Thu Oct 17 
> 19:43:25 2013 -0700
> @@ -41,7 +41,7 @@
>   * This range may be written as [0,N).
>   * The most significant component is at index 0.
>   * An empty composite name has no components.
> - *<p>
> + *
>   * <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
> @@ -72,12 +72,12 @@
>   * A trailing component separator (the composite name string ends with
>   * a separator) denotes a trailing empty component.
>   * Adjacent component separators denote an empty component.
> - *<p>
> + *
>   *<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 summary="examples showing string form 
> of composite name and its corresponding structural form (CompositeName)">
>
>  <tr>
> @@ -136,7 +136,7 @@
>  <td>{"x", "", "y"}</td>
>  </tr>
>  </table>
> - * <p>
> + *
>   *<h1>Composition Examples</h1>
>   * Here are some composition examples.  The right column shows composing
>   * string composite names while the left column shows composing the
> @@ -144,7 +144,7 @@
>   * string forms of two composite names simply involves concatenating
>   * their string forms together.
>
> -<p> <table border="1" cellpadding=3 summary="composition examples 
> showing string names and composite names">
> +<table border="1" cellpadding=3 summary="composition examples showing 
> string names and composite names">
>
>  <tr>
>  <th>String Names</th>
> @@ -188,7 +188,7 @@
>  </tr>
>
>  </table>
> - *<p>
> + *
>   *<h1>Multithreaded Access</h1>
>   * A <tt>CompositeName</tt> instance is not synchronized against 
> concurrent
>   * multithreaded access. Multiple threads trying to access and modify a
> diff -r c1616a944d1c src/share/classes/javax/naming/CompoundName.java
> --- a/src/share/classes/javax/naming/CompoundName.java    Fri Oct 18 
> 08:57:52 2013 +0800
> +++ b/src/share/classes/javax/naming/CompoundName.java    Thu Oct 17 
> 19:43:25 2013 -0700
> @@ -38,7 +38,7 @@
>   * This range may be written as [0,N).
>   * The most significant component is at index 0.
>   * An empty compound name has no components.
> - *<p>
> + *
>   * <h1>Compound Name Syntax</h1>
>   * The syntax of a compound name is specified using a set of properties:
>   *<dl>
> @@ -135,7 +135,7 @@
>   * applied (e.g. embedded separators are escaped or quoted)
>   * so that when the same string is parsed, it will yield the same 
> components
>   * of the original compound name.
> - *<p>
> + *
>   *<h1>Multithreaded Access</h1>
>   * A <tt>CompoundName</tt> instance is not synchronized against 
> concurrent
>   * multithreaded access. Multiple threads trying to access and modify a
> diff -r c1616a944d1c src/share/classes/javax/naming/Context.java
> --- a/src/share/classes/javax/naming/Context.java    Fri Oct 18 
> 08:57:52 2013 +0800
> +++ b/src/share/classes/javax/naming/Context.java    Thu Oct 17 
> 19:43:25 2013 -0700
> @@ -31,7 +31,7 @@
>   * This interface represents a naming context, which
>   * consists of a set of name-to-object bindings.
>   * It contains methods for examining and updating these bindings.
> - * <p>
> + *
>   * <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.
> @@ -68,12 +68,12 @@
>   * <tt>NamingEnumeration</tt> may be names in their own namespace 
> rather than
>   * names in a composite namespace, at the discretion of the service
>   * provider.
> - *<p>
> + *
>   *<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>
> + *
>   *<h1>Concurrent Access</h1>
>   * A Context instance is not guaranteed to be synchronized against
>   * concurrent access by multiple threads.  Threads that need to access
> @@ -90,7 +90,7 @@
>   * use, or while any referrals generated by that operation are still
>   * being followed.
>   *
> - *<p>
> + *
>   *<h1>Parameters</h1>
>   * A <tt>Name</tt> parameter passed to any method of the
>   * <tt>Context</tt> interface or one of its subinterfaces
> @@ -102,7 +102,7 @@
>   * A <tt>Name</tt> returned by any such method is owned by the caller.
>   * The caller may subsequently modify it; the service provider may not.
>   *
> - *<p>
> + *
>   *<h1>Environment Properties</h1>
>   *<p>
>   * JNDI applications need a way to communicate various preferences
> diff -r c1616a944d1c src/share/classes/javax/naming/InitialContext.java
> --- a/src/share/classes/javax/naming/InitialContext.java    Fri Oct 18 
> 08:57:52 2013 +0800
> +++ b/src/share/classes/javax/naming/InitialContext.java    Thu Oct 17 
> 19:43:25 2013 -0700
> @@ -361,7 +361,7 @@
>       * follows.
>       * Define a new method that uses this method to get an initial
>       * context of the desired subclass.
> -     * <p><blockquote><pre>
> +     * <blockquote><pre>
>       * protected XXXContext getURLOrDefaultInitXXXCtx(Name name)
>       * throws NamingException {
>       *  Context answer = getURLOrDefaultInitCtx(name);
> @@ -377,7 +377,7 @@
>       * </pre></blockquote>
>       * When providing implementations for the new methods in the 
> subclass,
>       * use this newly defined method to get the initial context.
> -     * <p><blockquote><pre>
> +     * <blockquote><pre>
>       * public Object XXXMethod1(Name name, ...) {
>       *  throws NamingException {
>       *    return getURLOrDefaultInitXXXCtx(name).XXXMethod1(name, ...);
> diff -r c1616a944d1c 
> src/share/classes/javax/naming/ReferralException.java
> --- a/src/share/classes/javax/naming/ReferralException.java    Fri Oct 
> 18 08:57:52 2013 +0800
> +++ b/src/share/classes/javax/naming/ReferralException.java    Thu Oct 
> 17 19:43:25 2013 -0700
> @@ -156,7 +156,7 @@
>       * <code>getReferralContext</code> to allow the processing of
>       * other referrals to continue.
>       * The following code fragment shows a typical usage pattern.
> -     * <p><blockquote><pre>
> +     * <blockquote><pre>
>       *  } catch (ReferralException e) {
>       *      if (!shallIFollow(e.getReferralInfo())) {
>       *          if (!e.skipReferral()) {
> @@ -177,7 +177,7 @@
>       * <code>getReferralContext</code> to allow the current
>       * referral to be retried.
>       * The following code fragment shows a typical usage pattern.
> -     * <p><blockquote><pre>
> +     * <blockquote><pre>
>       *  } catch (ReferralException e) {
>       *      while (true) {
>       *          try {
> diff -r c1616a944d1c 
> src/share/classes/javax/naming/directory/DirContext.java
> --- a/src/share/classes/javax/naming/directory/DirContext.java Fri Oct 
> 18 08:57:52 2013 +0800
> +++ b/src/share/classes/javax/naming/directory/DirContext.java Thu Oct 
> 17 19:43:25 2013 -0700
> @@ -31,7 +31,7 @@
>   * The directory service interface, containing
>   * methods for examining and updating attributes
>   * associated with objects, and for searching the directory.
> - * <p>
> + *
>   * <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.
> @@ -50,7 +50,7 @@
>   * 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.
> - * <p>
> + *
>   * <h1>Attribute Models</h1>
>   * There are two basic models of what attributes should be
>   * associated with.  First, attributes may be directly associated with a
> @@ -80,7 +80,7 @@
>   * JNDI clients are safest when they do not make assumptions about
>   * 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>
> + *
>   * <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
> @@ -112,7 +112,7 @@
>   * <li>description;lang-fr
>   * </ul>
>   *
> - * <p>
> + *
>   *<h1>Operational Attributes</h1>
>   *<p>
>   * Some directories have the notion of "operational attributes" which 
> are
> @@ -126,7 +126,7 @@
>   * The attributes returned do <em>not</em> include operational 
> attributes.
>   * In order to retrieve operational attributes, you must name them 
> explicitly.
>   *
> - * <p>
> + *
>   * <h1>Named Context</h1>
>   * <p>
>   * There are certain methods in which the name must resolve to a context
> @@ -137,7 +137,7 @@
>   * <code>NotContextException</code> is thrown.
>   * Aside from these methods, there is no requirement that the
>   * <em>named object</em> be a DirContext.
> - *<p>
> + *
>   *<h1>Parameters</h1>
>   *<p>
>   * An <tt>Attributes</tt>, <tt>SearchControls</tt>, or array object
> @@ -149,7 +149,7 @@
>   * An <tt>Attributes</tt> object returned by any method is owned by
>   * the caller.  The caller may subsequently modify it; the service
>   * provider will not.
> - *<p>
> + *
>   *<h1>Exceptions</h1>
>   *<p>
>   * All the methods in this interface can throw a NamingException or
> diff -r c1616a944d1c 
> src/share/classes/javax/naming/event/EventContext.java
> --- a/src/share/classes/javax/naming/event/EventContext.java Fri Oct 
> 18 08:57:52 2013 +0800
> +++ b/src/share/classes/javax/naming/event/EventContext.java Thu Oct 
> 17 19:43:25 2013 -0700
> @@ -33,7 +33,7 @@
>  /**
>   * Contains methods for registering/deregistering listeners to be 
> notified of
>   * events fired when objects named in a context changes.
> - *<p>
> + *
>   *<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
> @@ -58,7 +58,7 @@
>   * An application can use the method <tt>targetMustExist()</tt> to check
>   * whether a <tt>EventContext</tt> supports registration
>   * of nonexistent targets.
> - *<p>
> + *
>   *<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
> diff -r c1616a944d1c src/share/classes/javax/naming/ldap/LdapContext.java
> --- a/src/share/classes/javax/naming/ldap/LdapContext.java    Fri Oct 
> 18 08:57:52 2013 +0800
> +++ b/src/share/classes/javax/naming/ldap/LdapContext.java    Thu Oct 
> 17 19:43:25 2013 -0700
> @@ -338,7 +338,7 @@
>       * parameter, a system property, or one or more resource files.
>       *<p>
>       * The value of this constant is "java.naming.factory.control".
> -     *<p>
> +     *
>       * @see ControlFactory
>       * @see javax.naming.Context#addToEnvironment
>       * @see javax.naming.Context#removeFromEnvironment
> diff -r c1616a944d1c src/share/classes/javax/naming/ldap/Rdn.java
> --- a/src/share/classes/javax/naming/ldap/Rdn.java    Fri Oct 18 
> 08:57:52 2013 +0800
> +++ b/src/share/classes/javax/naming/ldap/Rdn.java    Thu Oct 17 
> 19:43:25 2013 -0700
> @@ -1,5 +1,5 @@
>  /*
> - * Copyright (c) 2003, 2011, Oracle and/or its affiliates. All rights 
> reserved.
> + * Copyright (c) 2003, 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
> @@ -315,7 +315,6 @@
>       * @return  A negative integer, zero, or a positive integer as 
> this Rdn
>       *          is less than, equal to, or greater than the given 
> Object.
>       * @exception ClassCastException if obj is null or not a Rdn.
> -     * <p>
>       */
>      public int compareTo(Object obj) {
>          if (!(obj instanceof Rdn)) {




More information about the core-libs-dev mailing list