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

Joe Darcy joe.darcy at oracle.com
Fri Jun 28 17:54:54 UTC 2013

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 @@ /*

@@ -137,14 +137,14 @@

-

+

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

- *

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 + *
      + *
    • 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:
          • ldapContext.newInstance(reqCtls)
          • ldapContext.setRequestControls(reqCtls)
          • ldapContext.newInstance(reqCtls)
          • ldapContext.setRequestControls(reqCtls)
          • 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:
            • new InitialLdapContext(env, connCtls)
            • refException.getReferralContext(env, connCtls)
            • ldapContext.reconnect(connCtls);
            • new InitialLdapContext(env, connCtls)
            • refException.getReferralContext(env, connCtls)
            • ldapContext.reconnect(connCtls);
            • where refException is an instance of
            • LdapReferralException, and ldapContext is an

          More information about the core-libs-dev mailing list