8332072: Convert package.html files in java.naming to package-info.java

8335213: Code snippet in javax.naming.ldap package summary does not compile

Reviewed-by: aefimov

Author: nizarbenalla

src/java.naming/share/classes/javax/naming/directory/package-info.java

@@ -0,0 +1,86 @@
+/*
+ * Copyright (c) 1999, 2024, 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
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+/**
+ *
+ * Extends the {@code javax.naming} package to provide functionality
+ * for accessing directory services.
+ *
+ * <p>
+ * This package defines the directory operations of the Java Naming and
+ * Directory Interface (JNDI). &nbsp;
+ * JNDI provides naming and directory functionality to applications
+ * written in the Java programming language. It is designed to be
+ * independent of any specific naming or directory service
+ * implementation. Thus a variety of services--new, emerging, and
+ * already deployed ones--can be accessed in a common way.
+ *
+ * <p>
+ * This package allows applications to retrieve and update attributes
+ * associated with objects stored in a directory, and to search for
+ * objects using specified attributes.
+ *
+ * <h2>The Directory Context</h2>
+ *
+ * The {@code DirContext}
+ * interface represents a <em>directory context</em>.
+ * It defines methods for examining and updating attributes associated with a
+ * <em>directory object</em>, or <em>directory entry</em> as it is sometimes
+ * called.
+ * <p>
+ * You use {@code getAttributes()} to retrieve the attributes
+ * associated with a directory object (for which you supply the name).
+ * Attributes are modified using {@code modifyAttributes()}.
+ * You can add, replace, or remove attributes and/or attribute values
+ * using this operation.
+ * <p>
+ * {@code DirContext} also behaves as a naming context
+ * by extending the {@code Context} interface in the {@code javax.naming} package.
+ * This means that any directory object can also provide
+ * a naming context.
+ * For example, the directory object for a person might contain
+ * the attributes of that person, and at the same time provide
+ * a context for naming objects relative to that person
+ * such as his printers and home directory.
+ *
+ * <h3>Searches</h3>
+ * {@code DirContext} contains methods for
+ * performing content-based searching of the directory.
+ * In the simplest and most common form of usage, the application
+ * specifies a set of attributes--possibly with specific
+ * values--to match, and submits this attribute set, to the
+ * {@code search()} method.
+ * There are other overloaded forms of {@code search()}
+ * that support more sophisticated <em>search filters</em>.
+ *
+ *
+ * <h2>Package Specification</h2>
+ *
+ * The JNDI API Specification and related documents can be found in the
+ * {@extLink jndi_overview JNDI documentation}.
+ *
+ * @since 1.3
+ */
+package javax.naming.directory;

src/java.naming/share/classes/javax/naming/directory/package.html

@@ -0,0 +1,118 @@
+/*
+ * Copyright (c) 1999, 2024, 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
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+/**
+ *
+ * Provides support for event notification when accessing naming and
+ * directory services.
+ *
+ * <p>
+ * This package defines the event notification operations of the Java Naming
+ * and Directory Interface (JNDI). &nbsp;
+ * JNDI provides naming and directory functionality to applications
+ * written in the Java programming language. It is designed to be
+ * independent of any specific naming or directory service
+ * implementation. Thus a variety of services--new, emerging, and
+ * already deployed ones--can be accessed in a common way.
+ *
+ * <h2>Naming Events</h2>
+ * <p>
+ * This package defines a {@code NamingEvent} class to represent an event
+ * that is generated by a naming/directory service.
+ * It also defines subinterfaces of {@code Context} and {@code DirContext},
+ * called {@code EventContext} and {@code EventDirContext},
+ * through which applications can register their interest in events
+ * fired by the context.
+ * <p>
+ * {@code NamingEvent} represents an event that occurs in a
+ * naming or directory service. There are two categories of naming events:
+ * <ul>
+ * <li>Those that affect the namespace (add/remove/rename an object)
+ * <li>Those that affect the objects' contents.
+ * </ul>
+ * Each category of events is handled by a corresponding listener:
+ * {@code NamespaceChangeListener}, {@code ObjectChangeListener}.
+ * <p>
+ * An application, for example, can register its interest in changes to
+ * objects in a context as follows:
+ * {@snippet :
+ * EventContext src =
+ *     (EventContext)(new InitialContext()).lookup("o=wiz,c=us");
+ * src.addNamingListener("ou=users", EventContext.ONELEVEL_SCOPE,
+ *     new ChangeHandler());
+ * ...
+ * class ChangeHandler implements ObjectChangeListener {
+ *     public void objectChanged(NamingEvent evt) {
+ *         System.out.println(evt.getNewBinding());
+ *     }
+ *     public void namingExceptionThrown(NamingExceptionEvent evt) {
+ *         System.out.println(evt.getException());
+ *     }
+ * }
+ * }
+ *
+ * <a id=THREADING></a>
+ * <h3>Threading Issues</h3>
+ *
+ * When an event is dispatched to a listener, the listener method (such
+ * as {@code objectChanged()}) may be executed in a thread other than the
+ * one in which the call to {@code addNamingListener()} was executed.
+ * The choice of which thread to use is made by the service provider.
+ * When an event is dispatched to multiple listeners, the service provider
+ * may choose (and is generally encouraged) to execute the listener methods
+ * concurrently in separate threads.
+ * <p>
+ * When a listener instance invokes {@code NamingEvent.getEventContext()},
+ * it must take into account the possibility that other threads will be
+ * working with that context concurrently. Likewise, when a listener is
+ * registered via {@code addNamingListener()}, the registering thread
+ * must take into account the likely possibility that the service provider
+ * will later invoke the listeners in newly-created threads. As {@code Context}
+ * instances are not guaranteed to be thread-safe in general, all context
+ * operations must be synchronized as needed.
+ *
+ * <h3>Exception Handling</h3>
+ *
+ * When a listener registers for events with a context, the context might
+ * need to do some internal processing in order to collect information
+ * required to generate the events. The context, for example, might need
+ * to make a request to the server to register interest in changes
+ * on the server that will eventually be translated into events.
+ * If an exception occurs that prevents information about the events from
+ * being collected, the listener will never be notified of the events.
+ * When such an exception occurs, a {@code NamingExceptionEvent} is
+ * fired to notify the listener. The listener's
+ * {@code namingExceptionThrown()} method is invoked, as shown in the
+ * sample code above,
+ * and the listener is automatically deregistered.
+ *
+ * <h2>Package Specification</h2>
+ *
+ * The JNDI API Specification and related documents can be found in the
+ * {@extLink jndi_overview JNDI documentation}.
+ *
+ * @since 1.3
+ */
+package javax.naming.event;