< prev index next >
src/java.naming/share/classes/javax/naming/ldap/LdapContext.java
Print this page
*** 1,7 ****
/*
! * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
--- 1,7 ----
/*
! * Copyright (c) 1999, 2019, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
*** 36,46 ****
*
* For applications that do not require such controls or extended
* operations, the more generic {@code javax.naming.directory.DirContext}
* should be used instead.
*
! * <h3>Usage Details About Controls</h3>
*
* This interface provides support for LDAP v3 controls.
* At a high level, this support allows a user
* program to set request controls for LDAP operations that are executed
* in the course of the user program's invocation of
--- 36,46 ----
*
* For applications that do not require such controls or extended
* operations, the more generic {@code javax.naming.directory.DirContext}
* should be used instead.
*
! * <h2>Usage Details About Controls</h2>
*
* This interface provides support for LDAP v3 controls.
* At a high level, this support allows a user
* program to set request controls for LDAP operations that are executed
* in the course of the user program's invocation of
*** 48,58 ****
* methods, and read response controls resulting from LDAP operations.
* At the implementation level, there are some details that developers of
* both the user program and service providers need to understand in order
* to correctly use request and response controls.
*
! * <h3>Request Controls</h3>
* <p>
* There are two types of request controls:
* <ul>
* <li>Request controls that affect how a connection is created
* <li>Request controls that affect context methods
--- 48,58 ----
* methods, and read response controls resulting from LDAP operations.
* At the implementation level, there are some details that developers of
* both the user program and service providers need to understand in order
* to correctly use request and response controls.
*
! * <h2>Request Controls</h2>
* <p>
* There are two types of request controls:
* <ul>
* <li>Request controls that affect how a connection is created
* <li>Request controls that affect context methods
*** 73,83 ****
* it uses the <em>connection request controls</em>, while for the normal
* LDAP operations, it uses the <em>context request controls</em>.
*<p>Unless explicitly qualified, the term "request controls" refers to
* context request controls.
*
! * <h4>Context Request Controls</h4>
* There are two ways in which a context instance gets its request controls:
* <ol>
* <li><code>ldapContext.newInstance(<strong>reqCtls</strong>)</code>
* <li><code>ldapContext.setRequestControls(<strong>reqCtls</strong>)</code>
* </ol>
--- 73,83 ----
* it uses the <em>connection request controls</em>, while for the normal
* LDAP operations, it uses the <em>context request controls</em>.
*<p>Unless explicitly qualified, the term "request controls" refers to
* context request controls.
*
! * <h2>Context Request Controls</h2>
* There are two ways in which a context instance gets its request controls:
* <ol>
* <li><code>ldapContext.newInstance(<strong>reqCtls</strong>)</code>
* <li><code>ldapContext.setRequestControls(<strong>reqCtls</strong>)</code>
* </ol>
*** 95,105 ****
* instance explicitly using {@code setRequestControls()}.
* <p>
* A context instance's request controls are retrieved using
* the method {@code getRequestControls()}.
*
! * <h4>Connection Request Controls</h4>
* There are three ways in which connection request controls are set:
* <ol>
* <li><code>
* new InitialLdapContext(env, <strong>connCtls</strong>)</code>
* <li><code>refException.getReferralContext(env, <strong>connCtls</strong>)</code>
--- 95,105 ----
* instance explicitly using {@code setRequestControls()}.
* <p>
* A context instance's request controls are retrieved using
* the method {@code getRequestControls()}.
*
! * <h2>Connection Request Controls</h2>
* There are three ways in which connection request controls are set:
* <ol>
* <li><code>
* new InitialLdapContext(env, <strong>connCtls</strong>)</code>
* <li><code>refException.getReferralContext(env, <strong>connCtls</strong>)</code>
*** 131,161 ****
* controls.
* <p>
* A context instance's connection request controls are retrieved using
* the method {@code getConnectControls()}.
*
! * <h4>Service Provider Requirements</h4>
*
* A service provider supports connection and context request controls
* in the following ways. Context request controls must be associated on
* a per context instance basis while connection request controls must be
* associated on a per connection instance basis. The service provider
* must look for the connection request controls in the environment
* property "java.naming.ldap.control.connect" and pass this environment
* property on to context instances that it creates.
*
! * <h3>Response Controls</h3>
*
* The method {@code LdapContext.getResponseControls()} is used to
* retrieve the response controls generated by LDAP operations executed
* as the result of invoking a {@code Context}/{@code DirContext}
* operation. The result is all of the responses controls generated
* by the underlying LDAP operations, including any implicit reconnection.
* To get only the reconnection response controls,
* use {@code reconnect()} followed by {@code getResponseControls()}.
*
! * <h3>Parameters</h3>
*
* A {@code Control[]} array
* passed as a parameter to any method is owned by the caller.
* The service provider will not modify the array or keep a reference to it,
* although it may keep references to the individual {@code Control} objects
--- 131,161 ----
* controls.
* <p>
* A context instance's connection request controls are retrieved using
* the method {@code getConnectControls()}.
*
! * <h2>Service Provider Requirements</h2>
*
* A service provider supports connection and context request controls
* in the following ways. Context request controls must be associated on
* a per context instance basis while connection request controls must be
* associated on a per connection instance basis. The service provider
* must look for the connection request controls in the environment
* property "java.naming.ldap.control.connect" and pass this environment
* property on to context instances that it creates.
*
! * <h2>Response Controls</h2>
*
* The method {@code LdapContext.getResponseControls()} is used to
* retrieve the response controls generated by LDAP operations executed
* as the result of invoking a {@code Context}/{@code DirContext}
* operation. The result is all of the responses controls generated
* by the underlying LDAP operations, including any implicit reconnection.
* To get only the reconnection response controls,
* use {@code reconnect()} followed by {@code getResponseControls()}.
*
! * <h2>Parameters</h2>
*
* A {@code Control[]} array
* passed as a parameter to any method is owned by the caller.
* The service provider will not modify the array or keep a reference to it,
* although it may keep references to the individual {@code Control} objects
< prev index next >