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 */
021 package com.unboundid.ldap.sdk;
022
023
024
025 import java.io.Serializable;
026 import java.util.List;
027
028 import com.unboundid.util.NotExtensible;
029 import com.unboundid.util.ThreadSafety;
030 import 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)
049 public 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 }