< prev index next >
src/java.naming/share/classes/javax/naming/ReferralException.java
Print this page
*** 31,46 ****
* This abstract class is used to represent a referral exception,
* which is generated in response to a <em>referral</em>
* such as that returned by LDAP v3 servers.
* <p>
* A service provider provides
! * a subclass of <tt>ReferralException</tt> by providing implementations
! * for <tt>getReferralInfo()</tt> and <tt>getReferralContext()</tt> (and appropriate
* constructors and/or corresponding "set" methods).
* <p>
! * The following code sample shows how <tt>ReferralException</tt> can be used.
! * <blockquote>{@code
* while (true) {
* try {
* bindings = ctx.listBindings(name);
* while (bindings.hasMore()) {
* b = bindings.next();
--- 31,46 ----
* This abstract class is used to represent a referral exception,
* which is generated in response to a <em>referral</em>
* such as that returned by LDAP v3 servers.
* <p>
* A service provider provides
! * a subclass of {@code ReferralException} by providing implementations
! * for {@code getReferralInfo()} and {@code getReferralContext()} (and appropriate
* constructors and/or corresponding "set" methods).
* <p>
! * The following code sample shows how {@code ReferralException} can be used.
! * <blockquote><pre>{@code
* while (true) {
* try {
* bindings = ctx.listBindings(name);
* while (bindings.hasMore()) {
* b = bindings.next();
*** 49,64 ****
* break;
* } catch (ReferralException e) {
* ctx = e.getReferralContext();
* }
* }
! * }</blockquote>
*<p>
! * <tt>ReferralException</tt> is an abstract class. Concrete implementations
* determine its synchronization and serialization properties.
*<p>
! * An environment parameter passed to the <tt>getReferralContext()</tt>
* method is owned by the caller.
* The service provider will not modify the object or keep a reference to it,
* but may keep a reference to a clone of it.
*
* @author Rosanna Lee
--- 49,64 ----
* break;
* } catch (ReferralException e) {
* ctx = e.getReferralContext();
* }
* }
! * }</pre></blockquote>
*<p>
! * {@code ReferralException} is an abstract class. Concrete implementations
* determine its synchronization and serialization properties.
*<p>
! * An environment parameter passed to the {@code getReferralContext()}
* method is owned by the caller.
* The service provider will not modify the object or keep a reference to it,
* but may keep a reference to a clone of it.
*
* @author Rosanna Lee
*** 112,122 ****
* To continue the operation, the client program should re-invoke
* the method using the same arguments as the original invocation.
*
* @return The non-null context at which to continue the method.
* @exception NamingException If a naming exception was encountered.
! * Call either <tt>retryReferral()</tt> or <tt>skipReferral()</tt>
* to continue processing referrals.
*/
public abstract Context getReferralContext() throws NamingException;
/**
--- 112,122 ----
* To continue the operation, the client program should re-invoke
* the method using the same arguments as the original invocation.
*
* @return The non-null context at which to continue the method.
* @exception NamingException If a naming exception was encountered.
! * Call either {@code retryReferral()} or {@code skipReferral()}
* to continue processing referrals.
*/
public abstract Context getReferralContext() throws NamingException;
/**
*** 125,135 ****
* Regardless of whether a referral is encountered directly during a
* context operation, or indirectly, for example, during a search
* enumeration, the referral exception should provide a context
* at which to continue the operation.
*<p>
! * The referral context is created using <tt>env</tt> as its environment
* properties.
* This method should be used instead of the no-arg overloaded form
* when the caller needs to use different environment properties for
* the referral context. It might need to do this, for example, when
* it needs to supply different authentication information to the referred
--- 125,135 ----
* Regardless of whether a referral is encountered directly during a
* context operation, or indirectly, for example, during a search
* enumeration, the referral exception should provide a context
* at which to continue the operation.
*<p>
! * The referral context is created using {@code env} as its environment
* properties.
* This method should be used instead of the no-arg overloaded form
* when the caller needs to use different environment properties for
* the referral context. It might need to do this, for example, when
* it needs to supply different authentication information to the referred
*** 141,185 ****
* @param env The possibly null environment to use when retrieving the
* referral context. If null, no environment properties will be used.
*
* @return The non-null context at which to continue the method.
* @exception NamingException If a naming exception was encountered.
! * Call either <tt>retryReferral()</tt> or <tt>skipReferral()</tt>
* to continue processing referrals.
*/
public abstract Context
getReferralContext(Hashtable<?,?> env)
throws NamingException;
/**
* Discards the referral about to be processed.
* A call to this method should be followed by a call to
! * <code>getReferralContext</code> to allow the processing of
* other referrals to continue.
* The following code fragment shows a typical usage pattern.
! * <blockquote><pre>
* } catch (ReferralException e) {
* if (!shallIFollow(e.getReferralInfo())) {
* if (!e.skipReferral()) {
* return;
* }
* }
* ctx = e.getReferralContext();
* }
! * </pre></blockquote>
*
* @return true If more referral processing is pending; false otherwise.
*/
public abstract boolean skipReferral();
/**
* Retries the referral currently being processed.
* A call to this method should be followed by a call to
! * <code>getReferralContext</code> to allow the current
* referral to be retried.
* The following code fragment shows a typical usage pattern.
! * <blockquote><pre>
* } catch (ReferralException e) {
* while (true) {
* try {
* ctx = e.getReferralContext(env);
* break;
--- 141,185 ----
* @param env The possibly null environment to use when retrieving the
* referral context. If null, no environment properties will be used.
*
* @return The non-null context at which to continue the method.
* @exception NamingException If a naming exception was encountered.
! * Call either {@code retryReferral()} or {@code skipReferral()}
* to continue processing referrals.
*/
public abstract Context
getReferralContext(Hashtable<?,?> env)
throws NamingException;
/**
* Discards the referral about to be processed.
* A call to this method should be followed by a call to
! * {@code getReferralContext} to allow the processing of
* other referrals to continue.
* The following code fragment shows a typical usage pattern.
! * <blockquote><pre>{@code
* } catch (ReferralException e) {
* if (!shallIFollow(e.getReferralInfo())) {
* if (!e.skipReferral()) {
* return;
* }
* }
* ctx = e.getReferralContext();
* }
! * }</pre></blockquote>
*
* @return true If more referral processing is pending; false otherwise.
*/
public abstract boolean skipReferral();
/**
* Retries the referral currently being processed.
* A call to this method should be followed by a call to
! * {@code getReferralContext} to allow the current
* referral to be retried.
* The following code fragment shows a typical usage pattern.
! * <blockquote><pre>{@code
* } catch (ReferralException e) {
* while (true) {
* try {
* ctx = e.getReferralContext(env);
* break;
*** 190,200 ****
* // modify environment properties (env), if necessary
* e.retryReferral();
* }
* }
* }
! * </pre></blockquote>
*
*/
public abstract void retryReferral();
/**
--- 190,200 ----
* // modify environment properties (env), if necessary
* e.retryReferral();
* }
* }
* }
! * }</pre></blockquote>
*
*/
public abstract void retryReferral();
/**
< prev index next >