src/java.naming/share/classes/javax/naming/directory/DirContext.java

*** 1,7 ****
  /*
!  * 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
   * under the terms of the GNU General Public License version 2 only, as
   * published by the Free Software Foundation.  Oracle designates this
--- 1,7 ----
  /*
!  * Copyright (c) 1999, 2019, 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
   * under the terms of the GNU General Public License version 2 only, as
   * published by the Free Software Foundation.  Oracle designates this
*** 30,40 ****
  /**
   * The directory service interface, containing
   * methods for examining and updating attributes
   * associated with objects, and for searching the directory.
   *
!  * <h1>Names</h1>
   * 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>
   * Most of the methods have overloaded versions with one taking a
--- 30,40 ----
  /**
   * The directory service interface, containing
   * methods for examining and updating attributes
   * associated with objects, and for searching the directory.
   *
!  * <h2>Names</h2>
   * 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>
   * Most of the methods have overloaded versions with one taking a
*** 49,59 ****
   * <p>
   * 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
   * associated with.  First, attributes may be directly associated with a
   * DirContext object.
   * In this model, an attribute operation on the named object is
   * roughly equivalent
--- 49,59 ----
   * <p>
   * 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.
   *
!  * <h2>Attribute Models</h2>
   * There are two basic models of what attributes should be
   * associated with.  First, attributes may be directly associated with a
   * DirContext object.
   * In this model, an attribute operation on the named object is
   * roughly equivalent
*** 79,89 ****
   * "store" attributes.
   * 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.
   *
!  * <h1>Attribute Type Names</h1>
   * 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
   * attribute names you have specified. This is because some directories
--- 79,89 ----
   * "store" attributes.
   * 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.
   *
!  * <h2>Attribute Type Names</h2>
   * 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
   * attribute names you have specified. This is because some directories
*** 111,121 ****
   * <li>description;lang-de
   * <li>description;lang-fr
   * </ul>
   *
   *
!  *<h1>Operational Attributes</h1>
   *<p>
   * Some directories have the notion of "operational attributes" which are
   * attributes associated with a directory object for administrative
   * purposes. An example of operational attributes is the access control
   * list for an object.
--- 111,121 ----
   * <li>description;lang-de
   * <li>description;lang-fr
   * </ul>
   *
   *
!  *<h2>Operational Attributes</h2>
   *<p>
   * Some directories have the notion of "operational attributes" which are
   * attributes associated with a directory object for administrative
   * purposes. An example of operational attributes is the access control
   * list for an object.
*** 125,146 ****
   * 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.
   *
   *
!  * <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
   * of such methods
   * use the term <em>named context</em> to describe their name parameter.
   * For these methods, if the named object is not a DirContext,
   * <code>NotContextException</code> is thrown.
   * Aside from these methods, there is no requirement that the
   * <em>named object</em> be a DirContext.
   *
!  *<h1>Parameters</h1>
   *<p>
   * 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
--- 125,146 ----
   * 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.
   *
   *
!  * <h2>Named Context</h2>
   * <p>
   * There are certain methods in which the name must resolve to a context
   * (for example, when searching a single level context). The documentation
   * of such methods
   * use the term <em>named context</em> to describe their name parameter.
   * For these methods, if the named object is not a DirContext,
   * <code>NotContextException</code> is thrown.
   * Aside from these methods, there is no requirement that the
   * <em>named object</em> be a DirContext.
   *
!  *<h2>Parameters</h2>
   *<p>
   * 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
*** 148,158 ****
   * The caller should not modify the object during this time.
   * An {@code Attributes} object returned by any method is owned by
   * the caller.  The caller may subsequently modify it; the service
   * provider will not.
   *
!  *<h1>Exceptions</h1>
   *<p>
   * 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.
   *
--- 148,158 ----
   * The caller should not modify the object during this time.
   * An {@code Attributes} object returned by any method is owned by
   * the caller.  The caller may subsequently modify it; the service
   * provider will not.
   *
!  *<h2>Exceptions</h2>
   *<p>
   * 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.
   *