001/*
002 * Copyright 2007-2014 UnboundID Corp.
003 * All Rights Reserved.
004 */
005/*
006 * Copyright (C) 2008-2014 UnboundID Corp.
007 *
008 * This program is free software; you can redistribute it and/or modify
009 * it under the terms of the GNU General Public License (GPLv2 only)
010 * or the terms of the GNU Lesser General Public License (LGPLv2.1 only)
011 * as published by the Free Software Foundation.
012 *
013 * This program is distributed in the hope that it will be useful,
014 * but WITHOUT ANY WARRANTY; without even the implied warranty of
015 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
016 * GNU General Public License for more details.
017 *
018 * You should have received a copy of the GNU General Public License
019 * along with this program; if not, see <http://www.gnu.org/licenses>.
020 */
021package com.unboundid.ldap.sdk;
022
023
024
025import java.io.Serializable;
026import java.util.List;
027
028import com.unboundid.util.NotExtensible;
029import com.unboundid.util.ThreadSafety;
030import com.unboundid.util.ThreadSafetyLevel;
031
032
033
034/**
035 * This interface defines a set of methods that may be safely called in an LDAP
036 * request without altering its contents.  This interface must not be
037 * implemented by any class outside of the LDAP SDK.
038 * <BR><BR>
039 * This interface does not inherently provide the assurance of thread safety for
040 * the methods that it exposes, because it is still possible for a thread
041 * referencing the object which implements this interface to alter the request
042 * using methods not included in this interface.  However, if it can be
043 * guaranteed that no thread will alter the underlying object, then the methods
044 * exposed by this interface can be safely invoked concurrently by any number of
045 * threads.
046 */
047@NotExtensible()
048@ThreadSafety(level=ThreadSafetyLevel.INTERFACE_NOT_THREADSAFE)
049public interface ReadOnlyLDAPRequest
050       extends Serializable
051{
052  /**
053   * Retrieves a list containing the set of controls for this request.
054   *
055   * @return  A list containing the set of controls for this request.
056   */
057  List<Control> getControlList();
058
059
060
061  /**
062   * Indicates whether this request contains at least one control.
063   *
064   * @return  {@code true} if this request contains at least one control, or
065   *          {@code false} if not.
066   */
067  boolean hasControl();
068
069
070
071  /**
072   * Indicates whether this request contains at least one control with the
073   * specified OID.
074   *
075   * @param  oid  The object identifier for which to make the determination.  It
076   *              must not be {@code null}.
077   *
078   * @return  {@code true} if this request contains at least one control with
079   *          the specified OID, or {@code false} if not.
080   */
081  boolean hasControl(final String oid);
082
083
084
085  /**
086   * Retrieves the control with the specified OID from this request.  If this
087   * request has multiple controls with the specified OID, then the first will
088   * be returned.
089   *
090   * @param  oid  The object identifier for which to retrieve the corresponding
091   *              control.  It must not be {@code null}.
092   *
093   * @return  The first control found with the specified OID, or {@code null} if
094   *          no control with that OID is included in this request.
095   */
096  Control getControl(final String oid);
097
098
099
100  /**
101   * Retrieves the maximum length of time in milliseconds that processing on
102   * this operation should be allowed to block while waiting for a response from
103   * the server.
104   *
105   * @param  connection  The connection to use in order to retrieve the default
106   *                     value, if appropriate.  It may be {@code null} to
107   *                     retrieve the request-specific timeout (which may be
108   *                     negative if no response-specific timeout has been set).
109   *
110   * @return  The maximum length of time in milliseconds that processing on this
111   *          operation should be allowed to block while waiting for a response
112   *          from the server, or zero if no timeout should be enforced.
113   */
114  long getResponseTimeoutMillis(final LDAPConnection connection);
115
116
117
118  /**
119   * Indicates whether to automatically follow any referrals encountered while
120   * processing this request.  If a value has been set for this request, then it
121   * will be returned.  Otherwise, the default from the connection options for
122   * the provided connection will be used.
123   *
124   * @param  connection  The connection whose connection options may be used in
125   *                     the course of making the determination.  It must not
126   *                     be {@code null}.
127   *
128   * @return  {@code true} if any referrals encountered during processing should
129   *          be automatically followed, or {@code false} if not.
130   */
131  boolean followReferrals(final LDAPConnection connection);
132
133
134
135  /**
136   * Creates a new instance of this LDAP request that may be modified without
137   * impacting this request.
138   *
139   * @return  A new instance of this LDAP request that may be modified without
140   *          impacting this request.
141   */
142  LDAPRequest duplicate();
143
144
145
146  /**
147   * Creates a new instance of this LDAP request that may be modified without
148   * impacting this request.  The provided controls will be used for the new
149   * request instead of duplicating the controls from this request.
150   *
151   * @param  controls  The set of controls to include in the duplicate request.
152   *
153   * @return  A new instance of this LDAP request that may be modified without
154   *          impacting this request.
155   */
156  LDAPRequest duplicate(final Control[] controls);
157
158
159
160  /**
161   * Retrieves a string representation of this request.
162   *
163   * @return  A string representation of this request.
164   */
165  @Override()
166  String toString();
167
168
169
170  /**
171   * Appends a string representation of this request to the provided buffer.
172   *
173   * @param  buffer  The buffer to which to append a string representation of
174   *                 this request.
175   */
176  void toString(final StringBuilder buffer);
177}