JDK 8 code review request for doclint cleanup of javax.naming.* (original) (raw)

Lance Andersen - Oracle Lance.Andersen at oracle.com
Fri Jun 28 18:13:36 UTC 2013

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. *

- *

JNDI Composite Name Syntax

 + *

JNDI Composite Name Syntax

 * 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. *

 - *

Composite Name Examples

 + *

Composite Name Examples

 *This table shows examples of some composite names. Each row shows *the string form of a composite name and its corresponding structural form *(CompositeName). *

 -
 +
 String Name @@ -137,14 +137,14 @@ *

- *

Composition Examples

 + *

Composition Examples

 * Here are some composition examples. The right column shows composing * string composite names while the left column shows composing the * corresponding CompositeNames. Notice that composing the * string forms of two composite names simply involves concatenating * their string forms together. -

 +

 String Names @@ -189,7 +189,7 @@ *

 - *

Multithreaded Access

 + *

Multithreaded Access

 * A CompositeName instance is not synchronized against concurrent * multithreaded access. Multiple threads trying to access and modify a * CompositeName 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. *

 - *

Compound Name Syntax

 + *

Compound Name Syntax

 * The syntax of a compound name is specified using a set of properties: *
 *
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. *

 - *

Multithreaded Access

 + *

Multithreaded Access

 * A CompoundName instance is not synchronized against concurrent * multithreaded access. Multiple threads trying to access and modify a * CompoundName 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. *

- *

Names

 + *

Names

 * Each name passed as an argument to a Context 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. *

 - *

Exceptions

 + *

Exceptions

 * All the methods in this interface can throw a NamingException or * any of its subclasses. See NamingException and their subclasses * for details on each exception. *

 - *

Concurrent Access

 + *

Concurrent Access

 * 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. * *

 - *

Parameters

 + *

Parameters

 * A Name parameter passed to any method of the * Context 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. * *

 - *

Environment Properties

 + *

Environment Properties

 *

 * JNDI applications need a way to communicate various preferences * and properties that define the environment in which naming and @@ -138,7 +138,7 @@ * *

 * - *

Resource Files

 + *

Resource Files

 *

 * 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: * - * 

+ * 
{@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
- * 

+ * }

*
* 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:
* provider and application.
*
- * 
Provider Resource Files

+ * 
Provider Resource Files

*
* 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.
*
- * 
Application Resource Files

+ * 
Application Resource Files

*
* 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.
*
- * 
Search Algorithm for Properties

+ * 
Search Algorithm for Properties

*
* 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  the type of the returned object
* @param name
*          the name of the object to look up
* @return  the object bound to name
@@ -276,11 +277,12 @@
/**
* A static method to retrieve the named object.
* See {@link #doLookup(Name)} for details.
+     * @param  the type of the returned object
* @param name
*          the name of the object to look up
* @return  the object bound to name
* @throws  NamingException if a naming exception is encountered
-      * @since 1.6
+     * @since 1.6
*/
@SuppressWarnings("unchecked")
public static  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.
*

* obj is equal to this RefAddr all of these conditions are true
-      *
+      *
+      *
  •  non-null
    • 
*
  •  instance of RefAddr
    • 
*
  •  obj has the same address type as this RefAddr (using String.compareTo())
    • 
*
  •  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).
* 
    
* The following code sample shows how ReferralException can be used.
- * 
    
+ * 
    {@code
    
*      while (true) {
*          try {
*              bindings = ctx.listBindings(name);
@@ -51,7 +51,7 @@
*              ctx = e.getReferralContext();
*          }
*      }
- * 
    
+ * }
*
    
* ReferralException 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.
* 
    
- * 
    Names
    
+ * 
    Names
    
* Each name passed as an argument to a DirContext 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 Context methods. These same rules
* apply to the name argument to the DirContext methods.
* 
    
- * 
    Attribute Models
    
+ * 
    Attribute Models
    
* 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.
* 
    
- * 
    Attribute Type Names
    
+ * 
    Attribute Type Names
    
* In the getAttributes() and search() methods,
* you can supply the attributes to return by supplying a list of
* attribute names (strings).
@@ -113,7 +113,7 @@
* 
*
* 
    
- *
    Operational Attributes
    
+ *
    Operational Attributes
    
*
    
* 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.
*
* 
    
- * 
    Named Context
    
+ * 
    Named Context
    
* 
    
* 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
* named object be a DirContext.
*
    
- *
    Parameters
    
+ *
    Parameters
    
*
    
* An Attributes, SearchControls, 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.
*
    
- *
    Exceptions
    
+ *
    Exceptions
    
*
    
* 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.
*
    
- *
    Target
    
+ *
    Target
    
* The name parameter in the addNamingListener() methods is referred
* to as the target. The target, along with the scope, identify
* the object(s) that the listener is interested in.
@@ -59,7 +59,7 @@
* whether a EventContext supports registration
* of nonexistent targets.
*
    
- *
    Event Source
    
+ *
    Event Source
    
* The EventContext instance on which you invoke the
* registration methods is the event source 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 lookup() and get another instance of
* a EventContext on which to perform the deregistration.
- *
    Lifetime of Registration
    
+ *
    Lifetime of Registration
    
* A registered listener becomes deregistered when:
*
*
  • It is removed using removeNamingListener().
    • 
@@ -105,7 +105,7 @@
* Until that point, a EventContext instance that has outstanding
* listeners will continue to exist and be maintained by the service provider.
*
- *
    Listener Implementations
    
+ *
    Listener Implementations
    
* The registration/deregistration methods accept an instance of
* NamingListener. There are subinterfaces of NamingListener
* for different of event types of NamingEvent.
@@ -118,7 +118,7 @@
* of the listeners, this allows some service providers to optimize the
* registration.
*
- *
    Threading Issues
    
+ *
    Threading Issues
    
*
* Like Context instances in general, instances of
* EventContext 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 @@
* javax.naming.InitialDirContext for details on synchronization,
* and the policy for how an initial context is created.
*
-  * 
    Request Controls
    
+  * 
    Request Controls
    
* When you create an initial context (InitialLdapContext),
* 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 @@
* 
    Context Request Controls
    
* There are two ways in which a context instance gets its request controls:
* 
      
- * 
- * 
    1. ldapContext.newInstance(reqCtls)
      2. 
- * 
    2. ldapContext.setRequestControls(reqCtls)
      3. 
- * 
+ * 
    3. ldapContext.newInstance(reqCtls)
      4. 
+ * 
    4. ldapContext.setRequestControls(reqCtls)
      5. 
* 
* where ldapContext is an instance of LdapContext.
* Specifying null or an empty array for reqCtls
@@ -102,12 +100,10 @@
* 
      Connection Request Controls
      
* There are three ways in which connection request controls are set:
* 
        
- * 
- * 
      1. 
- * new InitialLdapContext(env, connCtls)
- * 
      2. refException.getReferralContext(env, connCtls)
        3. 
- * 
      3. ldapContext.reconnect(connCtls);
        4. 
- * 
+ * 
      4. 
+ * new InitialLdapContext(env, connCtls)
+ * 
      5. refException.getReferralContext(env, connCtls)
        6. 
+ * 
      6. ldapContext.reconnect(connCtls);
        7. 
* 
* where refException is an instance of
* LdapReferralException, and ldapContext is an
        



        -------------- next part --------------
        

        Lance Andersen| Principal Member of Technical Staff | +1.781.442.2037
Oracle Java Engineering 
1 Network Drive 
Burlington, MA 01803
Lance.Andersen at oracle.com
        

        


        

        More information about the core-libs-dev mailing list