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
029
030
031 /**
032 * This interface defines a set of methods that may be safely called in an LDAP
033 * request without altering its contents. This interface must not be
034 * implemented by any class outside of the LDAP SDK.
035 * <BR><BR>
036 * This interface does not inherently provide the assurance of thread safety for
037 * the methods that it exposes, because it is still possible for a thread
038 * referencing the object which implements this interface to alter the request
039 * using methods not included in this interface. However, if it can be
040 * guaranteed that no thread will alter the underlying object, then the methods
041 * exposed by this interface can be safely invoked concurrently by any number of
042 * threads.
043 */
044 public interface ReadOnlyLDAPRequest
045 extends Serializable
046 {
047 /**
048 * Retrieves a list containing the set of controls for this request.
049 *
050 * @return A list containing the set of controls for this request.
051 */
052 List<Control> getControlList();
053
054
055
056 /**
057 * Indicates whether this request contains at least one control.
058 *
059 * @return {@code true} if this request contains at least one control, or
060 * {@code false} if not.
061 */
062 boolean hasControl();
063
064
065
066 /**
067 * Indicates whether this request contains at least one control with the
068 * specified OID.
069 *
070 * @param oid The object identifier for which to make the determination. It
071 * must not be {@code null}.
072 *
073 * @return {@code true} if this request contains at least one control with
074 * the specified OID, or {@code false} if not.
075 */
076 boolean hasControl(final String oid);
077
078
079
080 /**
081 * Retrieves the control with the specified OID from this request. If this
082 * request has multiple controls with the specified OID, then the first will
083 * be returned.
084 *
085 * @param oid The object identifier for which to retrieve the corresponding
086 * control. It must not be {@code null}.
087 *
088 * @return The first control found with the specified OID, or {@code null} if
089 * no control with that OID is included in this request.
090 */
091 Control getControl(final String oid);
092
093
094
095 /**
096 * Retrieves the maximum length of time in milliseconds that processing on
097 * this operation should be allowed to block while waiting for a response from
098 * the server.
099 *
100 * @param connection The connection to use in order to retrieve the default
101 * value, if appropriate. It may be {@code null} to
102 * retrieve the request-specific timeout (which may be
103 * negative if no response-specific timeout has been set).
104 *
105 * @return The maximum length of time in milliseconds that processing on this
106 * operation should be allowed to block while waiting for a response
107 * from the server, or zero if no timeout should be enforced.
108 */
109 long getResponseTimeoutMillis(final LDAPConnection connection);
110
111
112
113 /**
114 * Indicates whether to automatically follow any referrals encountered while
115 * processing this request. If a value has been set for this request, then it
116 * will be returned. Otherwise, the default from the connection options for
117 * the provided connection will be used.
118 *
119 * @param connection The connection whose connection options may be used in
120 * the course of making the determination. It must not
121 * be {@code null}.
122 *
123 * @return {@code true} if any referrals encountered during processing should
124 * be automatically followed, or {@code false} if not.
125 */
126 boolean followReferrals(final LDAPConnection connection);
127
128
129
130 /**
131 * Creates a new instance of this LDAP request that may be modified without
132 * impacting this request.
133 *
134 * @return A new instance of this LDAP request that may be modified without
135 * impacting this request.
136 */
137 LDAPRequest duplicate();
138
139
140
141 /**
142 * Creates a new instance of this LDAP request that may be modified without
143 * impacting this request. The provided controls will be used for the new
144 * request instead of duplicating the controls from this request.
145 *
146 * @param controls The set of controls to include in the duplicate request.
147 *
148 * @return A new instance of this LDAP request that may be modified without
149 * impacting this request.
150 */
151 LDAPRequest duplicate(final Control[] controls);
152
153
154
155 /**
156 * Retrieves a string representation of this request.
157 *
158 * @return A string representation of this request.
159 */
160 @Override()
161 String toString();
162
163
164
165 /**
166 * Appends a string representation of this request to the provided buffer.
167 *
168 * @param buffer The buffer to which to append a string representation of
169 * this request.
170 */
171 void toString(final StringBuilder buffer);
172 }