001/*
002 * Copyright 2007-2019 Ping Identity Corporation
003 * All Rights Reserved.
004 */
005/*
006 * Copyright (C) 2008-2019 Ping Identity Corporation
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(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(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(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(LDAPConnection connection);
132
133
134
135  /**
136   * Retrieves the referral connector that should be used when establishing a
137   * connection for the purpose of automatically following a referral.
138   *
139   * @param  connection  The connection that may be used in the course of
140   *                     obtaining the appropriate referral connector.  It must
141   *                     not be {@code null}.
142   *
143   * @return  The referral connector that should be used for the purpose of
144   *          automatically following a referral.  It will not be {@code null}.
145   */
146  ReferralConnector getReferralConnector(LDAPConnection connection);
147
148
149
150  /**
151   * Creates a new instance of this LDAP request that may be modified without
152   * impacting this request.
153   *
154   * @return  A new instance of this LDAP request that may be modified without
155   *          impacting this request.
156   */
157  LDAPRequest duplicate();
158
159
160
161  /**
162   * Creates a new instance of this LDAP request that may be modified without
163   * impacting this request.  The provided controls will be used for the new
164   * request instead of duplicating the controls from this request.
165   *
166   * @param  controls  The set of controls to include in the duplicate request.
167   *
168   * @return  A new instance of this LDAP request that may be modified without
169   *          impacting this request.
170   */
171  LDAPRequest duplicate(Control[] controls);
172
173
174
175  /**
176   * Retrieves a string representation of this request.
177   *
178   * @return  A string representation of this request.
179   */
180  @Override()
181  String toString();
182
183
184
185  /**
186   * Appends a string representation of this request to the provided buffer.
187   *
188   * @param  buffer  The buffer to which to append a string representation of
189   *                 this request.
190   */
191  void toString(StringBuilder buffer);
192
193
194
195  /**
196   * Appends a number of lines comprising the Java source code that can be used
197   * to recreate this request to the given list.
198   *
199   * @param  lineList           The list to which the source code lines should
200   *                            be added.
201   * @param  requestID          The name that should be used as an identifier
202   *                            for the request.  If this is {@code null} or
203   *                            empty, then a generic ID will be used.
204   * @param  indentSpaces       The number of spaces that should be used to
205   *                            indent the generated code.  It must not be
206   *                            negative.
207   * @param  includeProcessing  Indicates whether the generated code should
208   *                            include code required to actually process the
209   *                            request and handle the result (if {@code true}),
210   *                            or just to generate the request (if
211   *                            {@code false}).
212   */
213  void toCode(List<String> lineList, String requestID,
214              int indentSpaces, boolean includeProcessing);
215}