stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

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

Reviewed-by: aefimov
This commit is contained in:
Nizar Benalla 2024-07-04 12:29:32 +00:00 committed by Aleksei Efimov
parent 7e378fccd8
commit 6a472797a4
11 changed files with 717 additions and 714 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

86
src/java.naming/share/classes/javax/naming/directory/package-info.java Normal file
View File

@ -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;

90
src/java.naming/share/classes/javax/naming/directory/package.html
View File

@ -1,90 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!--
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
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.
-->
</head>
<body bgcolor="white">
Extends the <code>javax.naming</code> 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</code>
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()</code> to retrieve the attributes
associated with a directory object (for which you supply the name).
Attributes are modified using <code>modifyAttributes()</code>.
You can add, replace, or remove attributes and/or attribute values
using this operation.
<p>
<code>DirContext</code> also behaves as a naming context
by extending the <code>Context</code> interface in the <code>javax.naming</code> 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</code> 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()</code> method.
There are other overloaded forms of <code>search()</code>
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
</body>
</html>

118
src/java.naming/share/classes/javax/naming/event/package-info.java Normal file
View File

@ -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;

125
src/java.naming/share/classes/javax/naming/event/package.html
View File

@ -1,125 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!--
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
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.
-->
</head>
<body bgcolor="white">
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</code> class to represent an event
that is generated by a naming/directory service.
It also defines subinterfaces of <code>Context</code> and <code>DirContext</code>,
called <code>EventContext</code> and <code>EventDirContext</code>,
through which applications can register their interest in events
fired by the context.
<p>
<code>NamingEvent</code> 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>, <code>ObjectChangeListener</code>.
<p>
An application, for example, can register its interest in changes to
objects in a context as follows:
<blockquote>
<pre>
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());
}
}
</pre>
</blockquote>
<a id=THREADING></a>
<h3>Threading Issues</h3>
When an event is dispatched to a listener, the listener method (such
as <code>objectChanged()</code>) may be executed in a thread other than the
one in which the call to <code>addNamingListener()</code> 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()</code>,
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()</code>, 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</code>
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</code> is
fired to notify the listener. The listener's
<code>namingExceptionThrown()</code> 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
</body>
</html>

259
src/java.naming/share/classes/javax/naming/ldap/package-info.java Normal file
View File

@ -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.
*
* <p>
* This package extends 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 is for applications and service providers that deal with
* LDAPv3 extended operations and controls, as defined by
* <a href=http://www.ietf.org/rfc/rfc2251.txt>RFC 2251</a>.
* The core interface in this package is {@code LdapContext}, which defines
* methods on a context for performing extended operations and handling
* controls.
*
* <h2>Extended Operations</h2>
* <p>
* 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.
* <p>
* An application typically does not deal directly with these interfaces.
* Instead, it deals with classes that <em>implement</em> 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.
* <p>
* 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();
* }
* <p>
* 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;
* }
* }
* }
*
* <h2>Controls</h2>
*
* This package defines the interface {@code Control} to represent an LDAPv3
* control. It can be a control that is sent to an LDAP server
* (<em>request control</em>) or a control returned by an LDAP server
* (<em>response control</em>). 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.
* <p>
* An application typically does not deal directly with this interface.
* Instead, it deals with classes that <em>implement</em> 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.
* <p>
* 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
* }
* ...
* }
* }
* <p>
* When a service provider receives response controls, it uses
* the {@code ControlFactory} class to produce specific classes
* that implement the {@code Control} interface.
* <p>
* 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.
* <p>
* 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
* }
* }
* }
*
* <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.ldap;

266
src/java.naming/share/classes/javax/naming/ldap/package.html
View File

@ -1,266 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!--
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
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.
-->
</head>
<body bgcolor="white">
Provides support for LDAPv3 extended operations and controls.
<p>
This package extends 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 is for applications and service providers that deal with
LDAPv3 extended operations and controls, as defined by
<a href=http://www.ietf.org/rfc/rfc2251.txt>RFC 2251</a>.
The core interface in this package is <code>LdapContext</code>, which defines
methods on a context for performing extended operations and handling
controls.
<h2>Extended Operations</h2>
<p>
This package defines the interface <code>ExtendedRequest</code>
to represent the argument to an extended operation,
and the interface <code>ExtendedResponse</code> 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.
<p>
An application typically does not deal directly with these interfaces.
Instead, it deals with classes that <em>implement</em> 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.
<p>
For example, suppose an LDAP server supports a "get time" extended operation.
It would supply classes such as
<code>GetTimeRequest</code> and <code>GetTimeResponse</code>,
so that applications can use this feature.
An application would use these classes as follows:
<blockquote><pre>
GetTimeResponse resp =
(GetTimeResponse) ectx.extendedOperation(new GetTimeRequest());
long time = resp.getTime();
</pre></blockquote>
<p>
The <code>GetTimeRequest</code> and <code>GetTimeResponse</code> classes might
be defined as follows:
<blockquote><pre>
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;
}
}
</pre></blockquote>
<h2>Controls</h2>
This package defines the interface <code>Control</code> to represent an LDAPv3
control. It can be a control that is sent to an LDAP server
(<em>request control</em>) or a control returned by an LDAP server
(<em>response control</em>). 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.
<p>
An application typically does not deal directly with this interface.
Instead, it deals with classes that <em>implement</em> 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.
<p>
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</code> so that applications
can use this feature.
An application would use this class as follows:
<blockquote>
<pre>
Control[] reqCtls = new Control[] {new SignedResultsControl(Control.CRITICAL)};
ectx.setRequestControls(reqCtls);
NamingEnumeration enum = ectx.search(...);
</pre>
</blockquote>
The <code>SignedResultsControl</code> class might be defined as follows:
<blockquote><pre>
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
}
...
}
</pre></blockquote>
<p>
When a service provider receives response controls, it uses
the <code>ControlFactory</code> class to produce specific classes
that implement the <code>Control</code> interface.
<p>
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</code> provides a method (<code>getResponseControls()</code>)
for getting the response controls sent with an LDAP operation,
while the <code>HasControls</code> interface is used to retrieve
response controls associated with enumeration results.
<p>
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</code>
so that the application can use this feature.
An application would perform an update, and then try to get the change ID.
<blockquote><pre>
// 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 &lt; respCtls; i++) {
if(respCtls[i] instanceof ChangeIDControl) {
ChangeIDControl cctl = (ChangeIDControl)respCtls[i];
System.out.println(cctl.getChangeID());
}
}
}
</pre></blockquote>
The vendor might supply the following <code>ChangeIDControl</code> and
<code>VendorXControlFactory</code> classes. The <code>VendorXControlFactory</code>
will be used by the service provider when the provider receives response
controls from the LDAP server.
<blockquote><pre>
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
}
}
</pre></blockquote>
<h2>Package Specification</h2>
The JNDI API Specification and related documents can be found in the
{@extLink jndi_overview JNDI documentation}.
@since 1.3
</body>
</html>

33
src/java.naming/share/classes/javax/naming/ldap/spi/package-info.java Normal file
View File

@ -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;

136
src/java.naming/share/classes/javax/naming/package-info.java Normal file
View File

@ -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.
*
* <p>
* This package defines the naming 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>Context</h2>
* <p>
* This package defines the notion of a <em>context</em>, represented
* by the {@code Context} interface.
* A context consists of a set of name-to-object <em>bindings</em>.
* {@code Context} is the core interface for looking up, binding, unbinding,
* and renaming objects, and for creating and destroying subcontexts.
* <p>
* {@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);
* }
*
* <h2>Names</h2>
* <p>
* 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
* <em>composite name</em> ({@code CompositeName})
* so that you can name an object using a name which spans multiple namespaces.
* <p>
* 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.
*
* <h2>Bindings</h2>
*
* 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.
* <p>
* 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.
*
* <h2>References</h2>
* 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 <em>reference</em>, 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.
*
*
* <h2>The Initial Context</h2>
*
* In JNDI, all naming and directory operations are performed relative
* to a context. There are no absolute roots.
* Therefore JNDI defines an <em>initial context</em>,
* {@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.
*
* <h2>Exceptions</h2>
*
* 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}.
*
*
* <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;

143
src/java.naming/share/classes/javax/naming/package.html
View File

@ -1,143 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!--
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
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.
-->
</head>
<body bgcolor="white">
Provides the classes and interfaces for accessing naming services.
<p>
This package defines the naming 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>Context</h2>
<p>
This package defines the notion of a <em>context</em>, represented
by the <code>Context</code> interface.
A context consists of a set of name-to-object <em>bindings</em>.
<code>Context</code> is the core interface for looking up, binding, unbinding,
and renaming objects, and for creating and destroying subcontexts.
<p>
<code>lookup()</code> is the most commonly used operation.
You supply <code>lookup()</code>
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:
<blockquote>
<pre>
Printer printer = (Printer)ctx.lookup("treekiller");
printer.print(report);
</pre>
</blockquote>
<h2>Names</h2>
<p>
Every naming method in the <code>Context</code>
interface has two
overloads: one that accepts a
<code>Name</code> argument and one that accepts a string name.
<code>Name</code> is an interface that represents a generic
name--an ordered sequence of zero of more components.
For these methods, <code>Name</code> can be used to represent a
<em>composite name</em> (<code>CompositeName</code>)
so that you can name an object using a name which spans multiple namespaces.
<p>
The overloads that accept <code>Name</code>
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.
<h2>Bindings</h2>
The <code>Binding</code> 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.
<p>
The <code>Binding</code> class is actually a subclass of
<code>NameClassPair</code>, which consists
simply of the object's name and the object's class name.
The <code>NameClassPair</code> 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.
<h2>References</h2>
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 <em>reference</em>, represented by the <code>Reference</code>
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.
<h2>The Initial Context</h2>
In JNDI, all naming and directory operations are performed relative
to a context. There are no absolute roots.
Therefore JNDI defines an <em>initial context</em>,
<code>InitialContext</code>,
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.
<h2>Exceptions</h2>
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</code>.
Programs interested in dealing with a particular exception
can catch the corresponding subclass of the exception.
Otherwise, programs should catch <code>NamingException</code>.
<h2>Package Specification</h2>
The JNDI API Specification and related documents can be found in the
{@extLink jndi_overview JNDI documentation}.
@since 1.3
</body>
</html>

85
src/java.naming/share/classes/javax/naming/spi/package-info.java Normal file
View File

@ -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.
*
* <p>
* This package defines the service provider interface (SPI) 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>
* The JNDI SPI provides the means for creating JNDI service providers,
* through which JNDI applications access different naming and
* directory services.
*
*
* <h2>Plug-in Architecture</h2>
*
* The service provider package allows different implementations to be plugged in
* dynamically.
* These different implementations include those for the
* <em>initial context</em>,
* and implementations for contexts that can be reached
* from the initial context.
*
* <h2>Java Object Support</h2>
*
* 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.
*
*
* <h2>Multiple Naming Systems (Federation)</h2>
*
* 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.
*
*
* <h2>Package Specification</h2>
*
* The JNDI SPI Specification and related documents can be found in the
* {@extLink jndi_overview JNDI documentation}.
*
* @since 1.3
*/
package javax.naming.spi;

90
src/java.naming/share/classes/javax/naming/spi/package.html
View File

@ -1,90 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!--
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
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.
-->
</head>
<body bgcolor="white">
Provides the means for dynamically plugging in support for accessing
naming and directory services through the <code>javax.naming</code>
and related packages.
<p>
This package defines the service provider interface (SPI) 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>
The JNDI SPI provides the means for creating JNDI service providers,
through which JNDI applications access different naming and
directory services.
<h2>Plug-in Architecture</h2>
The service provider package allows different implementations to be plugged in
dynamically.
These different implementations include those for the
<em>initial context</em>,
and implementations for contexts that can be reached
from the initial context.
<h2>Java Object Support</h2>
The service provider package provides support
for implementors of the
<code>javax.naming.Context.lookup()</code>
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.
<h2>Multiple Naming Systems (Federation)</h2>
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.
<h2>Package Specification</h2>
The JNDI SPI Specification and related documents can be found in the
{@extLink jndi_overview JNDI documentation}.
@since 1.3
</body>
</html>