From 6a472797a410a6fa27f50371b255054af0cd3c99 Mon Sep 17 00:00:00 2001 From: Nizar Benalla Date: Thu, 4 Jul 2024 12:29:32 +0000 Subject: [PATCH] 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 --- .../javax/naming/directory/package-info.java | 86 ++++++ .../javax/naming/directory/package.html | 90 ------ .../javax/naming/event/package-info.java | 118 ++++++++ .../classes/javax/naming/event/package.html | 125 -------- .../javax/naming/ldap/package-info.java | 259 +++++++++++++++++ .../classes/javax/naming/ldap/package.html | 266 ------------------ .../javax/naming/ldap/spi/package-info.java | 33 +++ .../classes/javax/naming/package-info.java | 136 +++++++++ .../share/classes/javax/naming/package.html | 143 ---------- .../javax/naming/spi/package-info.java | 85 ++++++ .../classes/javax/naming/spi/package.html | 90 ------ 11 files changed, 717 insertions(+), 714 deletions(-) create mode 100644 src/java.naming/share/classes/javax/naming/directory/package-info.java delete mode 100644 src/java.naming/share/classes/javax/naming/directory/package.html create mode 100644 src/java.naming/share/classes/javax/naming/event/package-info.java delete mode 100644 src/java.naming/share/classes/javax/naming/event/package.html create mode 100644 src/java.naming/share/classes/javax/naming/ldap/package-info.java delete mode 100644 src/java.naming/share/classes/javax/naming/ldap/package.html create mode 100644 src/java.naming/share/classes/javax/naming/ldap/spi/package-info.java create mode 100644 src/java.naming/share/classes/javax/naming/package-info.java delete mode 100644 src/java.naming/share/classes/javax/naming/package.html create mode 100644 src/java.naming/share/classes/javax/naming/spi/package-info.java delete mode 100644 src/java.naming/share/classes/javax/naming/spi/package.html diff --git a/src/java.naming/share/classes/javax/naming/directory/package-info.java b/src/java.naming/share/classes/javax/naming/directory/package-info.java new file mode 100644 index 00000000000..3f32a95c31e --- /dev/null +++ b/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. + * + *

+ * This package defines the directory operations of the Java Naming and + * Directory Interface (JNDI).   + * 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. + * + *

+ * This package allows applications to retrieve and update attributes + * associated with objects stored in a directory, and to search for + * objects using specified attributes. + * + *

The Directory Context

+ * + * The {@code DirContext} + * interface represents a directory context. + * It defines methods for examining and updating attributes associated with a + * directory object, or directory entry as it is sometimes + * called. + *

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

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

Searches

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

Package Specification

+ * + * The JNDI API Specification and related documents can be found in the + * {@extLink jndi_overview JNDI documentation}. + * + * @since 1.3 + */ +package javax.naming.directory; diff --git a/src/java.naming/share/classes/javax/naming/directory/package.html b/src/java.naming/share/classes/javax/naming/directory/package.html deleted file mode 100644 index ff4a83b4ce0..00000000000 --- a/src/java.naming/share/classes/javax/naming/directory/package.html +++ /dev/null @@ -1,90 +0,0 @@ - - - - - - - -Extends the javax.naming package to provide functionality -for accessing directory services. - -

-This package defines the directory operations of the Java Naming and -Directory Interface (JNDI).   -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. - -

-This package allows applications to retrieve and update attributes -associated with objects stored in a directory, and to search for -objects using specified attributes. - -

The Directory Context

- -The DirContext -interface represents a directory context. -It defines methods for examining and updating attributes associated with a -directory object, or directory entry as it is sometimes -called. -

-You use getAttributes() to retrieve the attributes -associated with a directory object (for which you supply the name). -Attributes are modified using modifyAttributes(). -You can add, replace, or remove attributes and/or attribute values -using this operation. -

-DirContext also behaves as a naming context -by extending the Context interface in the 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. - -

Searches

-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 -search() method. -There are other overloaded forms of search() -that support more sophisticated search filters. - - -

Package Specification

- -The JNDI API Specification and related documents can be found in the -{@extLink jndi_overview JNDI documentation}. - -@since 1.3 - - - diff --git a/src/java.naming/share/classes/javax/naming/event/package-info.java b/src/java.naming/share/classes/javax/naming/event/package-info.java new file mode 100644 index 00000000000..4214ee85973 --- /dev/null +++ b/src/java.naming/share/classes/javax/naming/event/package-info.java @@ -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. + * + *

+ * This package defines the event notification operations of the Java Naming + * and Directory Interface (JNDI).   + * 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. + * + *

Naming Events

+ *

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

+ * {@code NamingEvent} represents an event that occurs in a + * naming or directory service. There are two categories of naming events: + *

+ * Each category of events is handled by a corresponding listener: + * {@code NamespaceChangeListener}, {@code ObjectChangeListener}. + *

+ * 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()); + * } + * } + * } + * + * + *

Threading Issues

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

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

Exception Handling

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

Package Specification

+ * + * The JNDI API Specification and related documents can be found in the + * {@extLink jndi_overview JNDI documentation}. + * + * @since 1.3 + */ +package javax.naming.event; diff --git a/src/java.naming/share/classes/javax/naming/event/package.html b/src/java.naming/share/classes/javax/naming/event/package.html deleted file mode 100644 index 087e7c869a4..00000000000 --- a/src/java.naming/share/classes/javax/naming/event/package.html +++ /dev/null @@ -1,125 +0,0 @@ - - - - - - - -Provides support for event notification when accessing naming and -directory services. - -

-This package defines the event notification operations of the Java Naming -and Directory Interface (JNDI).   -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. - -

Naming Events

-

-This package defines a NamingEvent class to represent an event -that is generated by a naming/directory service. -It also defines subinterfaces of Context and DirContext, -called EventContext and EventDirContext, -through which applications can register their interest in events -fired by the context. -

-NamingEvent represents an event that occurs in a -naming or directory service. There are two categories of naming events: -

-Each category of events is handled by a corresponding listener: -NamespaceChangeListener, ObjectChangeListener. -

-An application, for example, can register its interest in changes to -objects in a context as follows: -

-
-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());
-    }
-}
-
-
- - -

Threading Issues

- -When an event is dispatched to a listener, the listener method (such -as objectChanged()) may be executed in a thread other than the -one in which the call to 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. -

-When a listener instance invokes 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 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 Context -instances are not guaranteed to be thread-safe in general, all context -operations must be synchronized as needed. - -

Exception Handling

- -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 NamingExceptionEvent is -fired to notify the listener. The listener's -namingExceptionThrown() method is invoked, as shown in the -sample code above, -and the listener is automatically deregistered. - -

Package Specification

- - -The JNDI API Specification and related documents can be found in the -{@extLink jndi_overview JNDI documentation}. - -@since 1.3 - - - diff --git a/src/java.naming/share/classes/javax/naming/ldap/package-info.java b/src/java.naming/share/classes/javax/naming/ldap/package-info.java new file mode 100644 index 00000000000..f5ba4906fd7 --- /dev/null +++ b/src/java.naming/share/classes/javax/naming/ldap/package-info.java @@ -0,0 +1,259 @@ +/* + * 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 LDAPv3 extended operations and controls. + * + *

+ * This package extends the directory operations of the Java Naming and + * Directory Interface (JNDI).   + * 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. + * + *

+ * This package is for applications and service providers that deal with + * LDAPv3 extended operations and controls, as defined by + * RFC 2251. + * The core interface in this package is {@code LdapContext}, which defines + * methods on a context for performing extended operations and handling + * controls. + * + *

Extended Operations

+ *

+ * This package defines the interface {@code ExtendedRequest} + * to represent the argument to an extended operation, + * and the interface {@code ExtendedResponse} to represent the result + * of the extended operation. + * An extended response is always paired with an extended request + * but not necessarily vice versa. That is, you can have an extended request + * that has no corresponding extended response. + *

+ * An application typically does not deal directly with these interfaces. + * Instead, it deals with classes that implement these + * interfaces. + * The application gets these classes either as part of a + * repertoire of extended operations standardized through the IETF, or + * from directory vendors for vendor-specific extended operations. + * The request classes should have constructors that accept + * arguments in a type-safe and user-friendly manner, while the + * response classes should have access methods for getting the data + * of the response in a type-safe and user-friendly manner. + * Internally, the request/response classes deal with encoding and decoding + * BER values. + *

+ * For example, suppose an LDAP server supports a "get time" extended operation. + * It would supply classes such as + * {@code GetTimeRequest} and {@code GetTimeResponse}, + * so that applications can use this feature. + * An application would use these classes as follows: + * {@snippet : + * GetTimeResponse resp = + * (GetTimeResponse) ectx.extendedOperation(new GetTimeRequest()); + * long time = resp.getTime(); + * } + *

+ * The {@code GetTimeRequest} and {@code GetTimeResponse} classes might + * be defined as follows: + * {@snippet : + * public class GetTimeRequest implements ExtendedRequest { + * // User-friendly constructor + * public GetTimeRequest() { + * }; + * + * // Methods used by service providers + * public String getID() { + * return GETTIME_REQ_OID; + * } + * public byte[] getEncodedValue() { + * return null; // no value needed for get time request + * } + * public ExtendedResponse createExtendedResponse( + * String id, byte[] berValue, int offset, int length) throws NamingException { + * return new GetTimeResponse(id, berValue, offset, length); + * } + * } + * public class GetTimeResponse implements ExtendedResponse { + * long time; + * // called by GetTimeRequest.createExtendedResponse() + * public GetTimeResponse(String id, byte[] berValue, int offset, int length) + * throws NamingException { + * // check validity of id + * long time = ... // decode berValue to get time + * } + * + * // Type-safe and User-friendly methods + * public java.util.Date getDate() { return new java.util.Date(time); } + * public long getTime() { return time; } + * + * // Low level methods + * public byte[] getEncodedValue() { + * return // berValue saved; + * } + * public String getID() { + * return GETTIME_RESP_OID; + * } + * } + * } + * + *

Controls

+ * + * This package defines the interface {@code Control} to represent an LDAPv3 + * control. It can be a control that is sent to an LDAP server + * (request control) or a control returned by an LDAP server + * (response control). Unlike extended requests and responses, + * there is not necessarily any pairing between request controls and + * response controls. You can send request controls and expect no + * response controls back, or receive response controls without sending + * any request controls. + *

+ * An application typically does not deal directly with this interface. + * Instead, it deals with classes that implement this interface. + * The application gets control classes either as part of a repertoire of + * controls standardized through the IETF, or from directory vendors for + * vendor-specific controls. The request control classes should have + * constructors that accept arguments in a type-safe and user-friendly + * manner, while the response control classes should have access methods + * for getting the data of the response in a type-safe and user-friendly + * manner. Internally, the request/response control classes deal with + * encoding and decoding BER values. + *

+ * For example, suppose an LDAP server supports a "signed results" + * request control, which when sent with a request, asks the + * server to digitally sign the results of an operation. + * It would supply a class {@code SignedResultsControl} so that applications + * can use this feature. + * An application would use this class as follows: + * {@snippet : + * Control[] reqCtls = new Control[] {new SignedResultsControl(Control.CRITICAL)}; + * ectx.setRequestControls(reqCtls); + * NamingEnumeration enum = ectx.search(...); + * } + * The {@code SignedResultsControl} class might be defined as follows: + * {@snippet : + * public class SignedResultsControl implements Control { + * // User-friendly constructor + * public SignedResultsControl(boolean criticality) { + * // assemble the components of the request control + * }; + * + * // Methods used by service providers + * public String getID() { + * return // control's object identifier + * } + * public byte[] getEncodedValue() { + * return // ASN.1 BER encoded control value + * } + * ... + * } + * } + *

+ * When a service provider receives response controls, it uses + * the {@code ControlFactory} class to produce specific classes + * that implement the {@code Control} interface. + *

+ * An LDAP server can send back response controls with an LDAP operation + * and also with enumeration results, such as those returned + * by a list or search operation. + * The {@code LdapContext} provides a method ({@code getResponseControls()}) + * for getting the response controls sent with an LDAP operation, + * while the {@code HasControls} interface is used to retrieve + * response controls associated with enumeration results. + *

+ * For example, suppose an LDAP server sends back a "change ID" control in response + * to a successful modification. It would supply a class {@code ChangeIDControl} + * so that the application can use this feature. + * An application would perform an update, and then try to get the change ID. + * {@snippet : + * // Perform update + * Context ctx = ectx.createSubsubcontext("cn=newobj"); + * + * // Get response controls + * Control[] respCtls = ectx.getResponseControls(); + * if (respCtls != null) { + * // Find the one we want + * for (int i = 0; i < respCtls.length; i++) { + * if(respCtls[i] instanceof ChangeIDControl) { + * ChangeIDControl cctl = (ChangeIDControl)respCtls[i]; + * System.out.println(cctl.getChangeID()); + * } + * } + * } + * } + * The vendor might supply the following {@code ChangeIDControl} and + * {@code VendorXControlFactory} classes. The {@code VendorXControlFactory} + * will be used by the service provider when the provider receives response + * controls from the LDAP server. + * {@snippet : + * public class ChangeIDControl implements Control { + * long id; + * + * // Constructor used by ControlFactory + * public ChangeIDControl(String OID, byte[] berVal) throws NamingException { + * // check validity of OID + * id = // extract change ID from berVal + * }; + * + * // Type-safe and User-friendly method + * public long getChangeID() { + * return id; + * } + * + * // Low-level methods + * public String getID() { + * return CHANGEID_OID; + * } + * public byte[] getEncodedValue() { + * return // original berVal + * } + * ... + * } + * public class VendorXControlFactory extends ControlFactory { + * public VendorXControlFactory () { + * } + * + * public Control getControlInstance(Control orig) throws NamingException { + * if (isOneOfMyControls(orig.getID())) { + * ... + * + * // determine which of ours it is and call its constructor + * return (new ChangeIDControl(orig.getID(), orig.getEncodedValue())); + * } + * return null; // not one of ours + * } + * } + * } + * + *

Package Specification

+ * + * The JNDI API Specification and related documents can be found in the + * {@extLink jndi_overview JNDI documentation}. + * + * @since 1.3 + */ +package javax.naming.ldap; diff --git a/src/java.naming/share/classes/javax/naming/ldap/package.html b/src/java.naming/share/classes/javax/naming/ldap/package.html deleted file mode 100644 index 6bd2f78e789..00000000000 --- a/src/java.naming/share/classes/javax/naming/ldap/package.html +++ /dev/null @@ -1,266 +0,0 @@ - - - - - - - -Provides support for LDAPv3 extended operations and controls. - -

-This package extends the directory operations of the Java Naming and -Directory Interface (JNDI).   -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. - -

-This package is for applications and service providers that deal with -LDAPv3 extended operations and controls, as defined by -RFC 2251. -The core interface in this package is LdapContext, which defines -methods on a context for performing extended operations and handling -controls. - -

Extended Operations

-

-This package defines the interface ExtendedRequest -to represent the argument to an extended operation, -and the interface ExtendedResponse to represent the result -of the extended operation. -An extended response is always paired with an extended request -but not necessarily vice versa. That is, you can have an extended request -that has no corresponding extended response. -

-An application typically does not deal directly with these interfaces. -Instead, it deals with classes that implement these -interfaces. -The application gets these classes either as part of a -repertoire of extended operations standardized through the IETF, or -from directory vendors for vendor-specific extended operations. -The request classes should have constructors that accept -arguments in a type-safe and user-friendly manner, while the -response classes should have access methods for getting the data -of the response in a type-safe and user-friendly manner. -Internally, the request/response classes deal with encoding and decoding -BER values. -

-For example, suppose an LDAP server supports a "get time" extended operation. -It would supply classes such as -GetTimeRequest and GetTimeResponse, -so that applications can use this feature. -An application would use these classes as follows: -

-GetTimeResponse resp =
-    (GetTimeResponse) ectx.extendedOperation(new GetTimeRequest());
-long time = resp.getTime();
-
-

-The GetTimeRequest and GetTimeResponse classes might -be defined as follows: -

-public class GetTimeRequest implements ExtendedRequest {
-    // User-friendly constructor 
-    public GetTimeRequest() {
-    };
-
-    // Methods used by service providers
-    public String getID() {
-        return GETTIME_REQ_OID;
-    }
-    public byte[] getEncodedValue() {
-        return null;  // no value needed for get time request
-    }
-    public ExtendedResponse createExtendedResponse(
-        String id, byte[] berValue, int offset, int length) throws NamingException {
-        return new GetTimeResponse(id, berValue, offset, length);
-    }
-}
-public class GetTimeResponse() implements ExtendedResponse {
-    long time;
-    // called by GetTimeRequest.createExtendedResponse()
-    public GetTimeResponse(String id, byte[] berValue, int offset, int length)
-        throws NamingException {
-        // check validity of id
-        long time =  ... // decode berValue to get time
-    }
-
-    // Type-safe and User-friendly methods
-    public java.util.Date getDate() { return new java.util.Date(time); }
-    public long getTime() { return time; }
-
-    // Low level methods
-    public byte[] getEncodedValue() {
-        return // berValue saved;
-    }
-    public String getID() {
-        return GETTIME_RESP_OID;
-    }
-}
-
- -

Controls

- -This package defines the interface Control to represent an LDAPv3 -control. It can be a control that is sent to an LDAP server -(request control) or a control returned by an LDAP server -(response control). Unlike extended requests and responses, -there is not necessarily any pairing between request controls and -response controls. You can send request controls and expect no -response controls back, or receive response controls without sending -any request controls. -

-An application typically does not deal directly with this interface. -Instead, it deals with classes that implement this interface. -The application gets control classes either as part of a repertoire of -controls standardized through the IETF, or from directory vendors for -vendor-specific controls. The request control classes should have -constructors that accept arguments in a type-safe and user-friendly -manner, while the response control classes should have access methods -for getting the data of the response in a type-safe and user-friendly -manner. Internally, the request/response control classes deal with -encoding and decoding BER values. -

-For example, suppose an LDAP server supports a "signed results" -request control, which when sent with a request, asks the -server to digitally sign the results of an operation. -It would supply a class SignedResultsControl so that applications -can use this feature. -An application would use this class as follows: -

-
-Control[] reqCtls = new Control[] {new SignedResultsControl(Control.CRITICAL)};
-ectx.setRequestControls(reqCtls);
-NamingEnumeration enum = ectx.search(...);
-
-
-The SignedResultsControl class might be defined as follows: -
-public class SignedResultsControl implements Control {
-    // User-friendly constructor 
-    public SignedResultsControl(boolean criticality) {
-	// assemble the components of the request control
-    };
-
-    // Methods used by service providers
-    public String getID() {
-        return // control's object identifier
-    }
-    public byte[] getEncodedValue() {
-        return // ASN.1 BER encoded control value
-    }
-    ...
-}
-
-

-When a service provider receives response controls, it uses -the ControlFactory class to produce specific classes -that implement the Control interface. -

-An LDAP server can send back response controls with an LDAP operation -and also with enumeration results, such as those returned -by a list or search operation. -The LdapContext provides a method (getResponseControls()) -for getting the response controls sent with an LDAP operation, -while the HasControls interface is used to retrieve -response controls associated with enumeration results. -

-For example, suppose an LDAP server sends back a "change ID" control in response -to a successful modification. It would supply a class ChangeIDControl -so that the application can use this feature. -An application would perform an update, and then try to get the change ID. -

-// Perform update
-Context ctx = ectx.createSubsubcontext("cn=newobj");
-
-// Get response controls
-Control[] respCtls = ectx.getResponseControls();
-if (respCtls != null) {
-    // Find the one we want
-    for (int i = 0; i < respCtls; i++) {
-        if(respCtls[i] instanceof ChangeIDControl) {
-	    ChangeIDControl cctl = (ChangeIDControl)respCtls[i];
-	    System.out.println(cctl.getChangeID());
-        }
-    }
-}
-
-The vendor might supply the following ChangeIDControl and -VendorXControlFactory classes. The VendorXControlFactory -will be used by the service provider when the provider receives response -controls from the LDAP server. -
-public class ChangeIDControl implements Control {
-    long id;
-
-    // Constructor used by ControlFactory
-    public ChangeIDControl(String OID, byte[] berVal) throws NamingException {
-        // check validity of OID
-        id = // extract change ID from berVal
-    };
-
-    // Type-safe and User-friendly method
-    public long getChangeID() {
-        return id;
-    }
-
-    // Low-level methods
-    public String getID() {
-        return CHANGEID_OID;
-    }
-    public byte[] getEncodedValue() {
-        return // original berVal
-    }
-    ...
-}
-public class VendorXControlFactory extends ControlFactory {
-    public VendorXControlFactory () {
-    }
-
-    public Control getControlInstance(Control orig) throws NamingException {
-        if (isOneOfMyControls(orig.getID())) {
-	    ...
-
-	    // determine which of ours it is and call its constructor
-	    return (new ChangeIDControl(orig.getID(), orig.getEncodedValue()));
-	}
-        return null;  // not one of ours
-    }
-}
-
- -

Package Specification

- -The JNDI API Specification and related documents can be found in the -{@extLink jndi_overview JNDI documentation}. - -@since 1.3 - - - diff --git a/src/java.naming/share/classes/javax/naming/ldap/spi/package-info.java b/src/java.naming/share/classes/javax/naming/ldap/spi/package-info.java new file mode 100644 index 00000000000..20f3ea258ef --- /dev/null +++ b/src/java.naming/share/classes/javax/naming/ldap/spi/package-info.java @@ -0,0 +1,33 @@ +/* + * Copyright (c) 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 the Service Provider Interface for DNS lookups when + * performing LDAP operations. + * + * @since 12 + */ +package javax.naming.ldap.spi; diff --git a/src/java.naming/share/classes/javax/naming/package-info.java b/src/java.naming/share/classes/javax/naming/package-info.java new file mode 100644 index 00000000000..edcc76506ef --- /dev/null +++ b/src/java.naming/share/classes/javax/naming/package-info.java @@ -0,0 +1,136 @@ +/* + * 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 the classes and interfaces for accessing naming services. + * + *

+ * This package defines the naming operations of the Java Naming and + * Directory Interface (JNDI).   + * 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. + * + * + *

Context

+ *

+ * This package defines the notion of a context, represented + * by the {@code Context} interface. + * A context consists of a set of name-to-object bindings. + * {@code Context} is the core interface for looking up, binding, unbinding, + * and renaming objects, and for creating and destroying subcontexts. + *

+ * {@code lookup()} is the most commonly used operation. + * You supply {@code lookup()} + * the name of the object you want + * to look up, and it returns the object bound to that name. + * For example, the following code fragment looks up + * a printer and sends a document to the printer object + * to be printed: + * + * {@snippet : + * Printer printer = (Printer)ctx.lookup("treekiller"); + * printer.print(report); + * } + * + *

Names

+ *

+ * Every naming method in the {@code Context} + * interface has two + * overloads: one that accepts a + * {@code Name} argument and one that accepts a string name. + * {@code Name} is an interface that represents a generic + * name--an ordered sequence of zero of more components. + * For these methods, {@code Name} can be used to represent a + * composite name ({@code CompositeName}) + * so that you can name an object using a name which spans multiple namespaces. + *

+ * The overloads that accept {@code Name} + * are useful for applications that need to manipulate names: composing + * them, comparing components, and so on. + * The overloads that accept string names are likely to be more useful + * for simple applications, such as those that simply read in a name + * and look up the corresponding object. + * + *

Bindings

+ * + * The {@code Binding} class represents a name-to-object binding. + * It is a tuple containing the name of the bound object, + * the name of the object's class, and the object itself. + *

+ * The {@code Binding} class is actually a subclass of + * {@code NameClassPair}, which consists + * simply of the object's name and the object's class name. + * The {@code NameClassPair} is useful when you only want + * information about the object's class and do not want to + * pay the extra cost of getting the object. + * + *

References

+ * Objects are stored in naming and directory services in different ways. + * If an object store supports storing Java objects, + * it might support storing an object in its serialized form. + * However, some naming and directory services do not support the + * storing of Java objects. Furthermore, for some + * objects in the directory, Java programs are but one group of applications + * that access them. In this case, a serialized Java object might + * not be the most appropriate representation. + * JNDI defines a reference, represented by the {@code Reference} + * class, which contains information on how to construct a copy of the object. + * JNDI will attempt to turn references looked up from the directory + * into the Java objects they represent, so that + * JNDI clients have the illusion that what + * is stored in the directory are Java objects. + * + * + *

The Initial Context

+ * + * In JNDI, all naming and directory operations are performed relative + * to a context. There are no absolute roots. + * Therefore JNDI defines an initial context, + * {@code InitialContext}, + * which provides a starting point for naming and directory operations. + * Once you have an initial context, you can use it to + * look up other contexts and objects. + * + *

Exceptions

+ * + * JNDI defines a class hierarchy for exceptions that can be thrown in + * the course of performing naming and directory operations. The root of + * this class hierarchy is {@code NamingException}. + * Programs interested in dealing with a particular exception + * can catch the corresponding subclass of the exception. + * Otherwise, programs should catch {@code NamingException}. + * + * + *

Package Specification

+ * + * The JNDI API Specification and related documents can be found in the + * {@extLink jndi_overview JNDI documentation}. + * + * @since 1.3 + */ +package javax.naming; diff --git a/src/java.naming/share/classes/javax/naming/package.html b/src/java.naming/share/classes/javax/naming/package.html deleted file mode 100644 index 67e046f84c6..00000000000 --- a/src/java.naming/share/classes/javax/naming/package.html +++ /dev/null @@ -1,143 +0,0 @@ - - - - - - - -Provides the classes and interfaces for accessing naming services. - -

-This package defines the naming operations of the Java Naming and -Directory Interface (JNDI).   -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. - - -

Context

-

-This package defines the notion of a context, represented -by the Context interface. -A context consists of a set of name-to-object bindings. -Context is the core interface for looking up, binding, unbinding, -and renaming objects, and for creating and destroying subcontexts. -

-lookup() is the most commonly used operation. -You supply lookup() -the name of the object you want -to look up, and it returns the object bound to that name. -For example, the following code fragment looks up -a printer and sends a document to the printer object -to be printed: - -

-
-Printer printer = (Printer)ctx.lookup("treekiller");
-printer.print(report);
-
-
- -

Names

-

-Every naming method in the Context -interface has two -overloads: one that accepts a -Name argument and one that accepts a string name. -Name is an interface that represents a generic -name--an ordered sequence of zero of more components. -For these methods, Name can be used to represent a -composite name (CompositeName) -so that you can name an object using a name which spans multiple namespaces. -

-The overloads that accept Name -are useful for applications that need to manipulate names: composing -them, comparing components, and so on. -The overloads that accept string names are likely to be more useful -for simple applications, such as those that simply read in a name -and look up the corresponding object. - -

Bindings

- -The Binding class represents a name-to-object binding. -It is a tuple containing the name of the bound object, -the name of the object's class, and the object itself. -

-The Binding class is actually a subclass of -NameClassPair, which consists -simply of the object's name and the object's class name. -The NameClassPair is useful when you only want -information about the object's class and do not want to -pay the extra cost of getting the object. - -

References

-Objects are stored in naming and directory services in different ways. -If an object store supports storing Java objects, -it might support storing an object in its serialized form. -However, some naming and directory services do not support the -storing of Java objects. Furthermore, for some -objects in the directory, Java programs are but one group of applications -that access them. In this case, a serialized Java object might -not be the most appropriate representation. -JNDI defines a reference, represented by the Reference -class, which contains information on how to construct a copy of the object. -JNDI will attempt to turn references looked up from the directory -into the Java objects they represent, so that -JNDI clients have the illusion that what -is stored in the directory are Java objects. - - -

The Initial Context

- -In JNDI, all naming and directory operations are performed relative -to a context. There are no absolute roots. -Therefore JNDI defines an initial context, -InitialContext, -which provides a starting point for naming and directory operations. -Once you have an initial context, you can use it to -look up other contexts and objects. - -

Exceptions

- -JNDI defines a class hierarchy for exceptions that can be thrown in -the course of performing naming and directory operations. The root of -this class hierarchy is NamingException. -Programs interested in dealing with a particular exception -can catch the corresponding subclass of the exception. -Otherwise, programs should catch NamingException. - - -

Package Specification

- -The JNDI API Specification and related documents can be found in the -{@extLink jndi_overview JNDI documentation}. - -@since 1.3 - - - diff --git a/src/java.naming/share/classes/javax/naming/spi/package-info.java b/src/java.naming/share/classes/javax/naming/spi/package-info.java new file mode 100644 index 00000000000..382a35a17e8 --- /dev/null +++ b/src/java.naming/share/classes/javax/naming/spi/package-info.java @@ -0,0 +1,85 @@ +/* + * 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 the means for dynamically plugging in support for accessing + * naming and directory services through the {@code javax.naming} + * and related packages. + * + *

+ * This package defines the service provider interface (SPI) of the Java Naming + * and Directory Interface (JNDI).   + * 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. + * + *

+ * The JNDI SPI provides the means for creating JNDI service providers, + * through which JNDI applications access different naming and + * directory services. + * + * + *

Plug-in Architecture

+ * + * The service provider package allows different implementations to be plugged in + * dynamically. + * These different implementations include those for the + * initial context, + * and implementations for contexts that can be reached + * from the initial context. + * + *

Java Object Support

+ * + * The service provider package provides support + * for implementors of the + * {@code javax.naming.Context.lookup()} + * method and related methods to return Java objects that are natural + * and intuitive for the Java programmer. + * For example, when looking up a printer name from the directory, + * it is natural for you to expect to get + * back a printer object on which to operate. + * + * + *

Multiple Naming Systems (Federation)

+ * + * JNDI operations allow applications to supply names that span multiple + * naming systems. So in the process of completing + * an operation, one service provider might need to interact + * with another service provider, for example, to pass on + * the operation to be continued in the next naming system. + * The service provider package provides support for + * different providers to cooperate to complete JNDI operations. + * + * + *

Package Specification

+ * + * The JNDI SPI Specification and related documents can be found in the + * {@extLink jndi_overview JNDI documentation}. + * + * @since 1.3 + */ +package javax.naming.spi; diff --git a/src/java.naming/share/classes/javax/naming/spi/package.html b/src/java.naming/share/classes/javax/naming/spi/package.html deleted file mode 100644 index f523c76deb4..00000000000 --- a/src/java.naming/share/classes/javax/naming/spi/package.html +++ /dev/null @@ -1,90 +0,0 @@ - - - - - - - -Provides the means for dynamically plugging in support for accessing -naming and directory services through the javax.naming -and related packages. - -

-This package defines the service provider interface (SPI) of the Java Naming -and Directory Interface (JNDI).   -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. - -

-The JNDI SPI provides the means for creating JNDI service providers, -through which JNDI applications access different naming and -directory services. - - -

Plug-in Architecture

- -The service provider package allows different implementations to be plugged in -dynamically. -These different implementations include those for the -initial context, -and implementations for contexts that can be reached -from the initial context. - -

Java Object Support

- -The service provider package provides support -for implementors of the -javax.naming.Context.lookup() -method and related methods to return Java objects that are natural -and intuitive for the Java programmer. -For example, when looking up a printer name from the directory, -it is natural for you to expect to get -back a printer object on which to operate. - - -

Multiple Naming Systems (Federation)

- -JNDI operations allow applications to supply names that span multiple -naming systems. So in the process of completing -an operation, one service provider might need to interact -with another service provider, for example, to pass on -the operation to be continued in the next naming system. -The service provider package provides support for -different providers to cooperate to complete JNDI operations. - - -

Package Specification

- -The JNDI SPI Specification and related documents can be found in the -{@extLink jndi_overview JNDI documentation}. - -@since 1.3 - - -