001 /*
002 * CDDL HEADER START
003 *
004 * The contents of this file are subject to the terms of the
005 * Common Development and Distribution License, Version 1.0 only
006 * (the "License"). You may not use this file except in compliance
007 * with the License.
008 *
009 * You can obtain a copy of the license at
010 * trunk/opends/resource/legal-notices/OpenDS.LICENSE
011 * or https://OpenDS.dev.java.net/OpenDS.LICENSE.
012 * See the License for the specific language governing permissions
013 * and limitations under the License.
014 *
015 * When distributing Covered Code, include this CDDL HEADER in each
016 * file and include the License file at
017 * trunk/opends/resource/legal-notices/OpenDS.LICENSE. If applicable,
018 * add the following below this CDDL HEADER, with the fields enclosed
019 * by brackets "[]" replaced with your own identifying information:
020 * Portions Copyright [yyyy] [name of copyright owner]
021 *
022 * CDDL HEADER END
023 *
024 *
025 * Copyright 2006-2008 Sun Microsystems, Inc.
026 */
027 package org.opends.server.types.operation;
028 import org.opends.messages.Message;
029
030
031
032 import java.util.List;
033
034 import org.opends.server.types.Control;
035 import org.opends.server.types.DirectoryException;
036 import org.opends.server.types.DN;
037 import org.opends.server.types.ResultCode;
038
039 import org.opends.messages.MessageBuilder;
040
041
042 /**
043 * This class defines a set of methods that are available for use by
044 * plugins for operations that are currently in the middle of their
045 * "core" processing (e.g., for examining search result entries or
046 * references before they are sent to the client). Note that this
047 * interface is intended only to define an API for use by plugins and
048 * is not intended to be implemented by any custom classes.
049 */
050 @org.opends.server.types.PublicAPI(
051 stability=org.opends.server.types.StabilityLevel.UNCOMMITTED,
052 mayInstantiate=false,
053 mayExtend=false,
054 mayInvoke=true)
055 public interface InProgressOperation
056 extends PluginOperation
057 {
058 /**
059 * Adds the provided control to the set of controls to include in
060 * the response to the client.
061 *
062 * @param control The control to add to the set of controls to
063 * include in the response to the client.
064 */
065 public void addResponseControl(Control control);
066
067
068
069 /**
070 * Removes the provided control from the set of controls to include
071 * in the response to the client.
072 *
073 * @param control The control to remove from the set of controls
074 * to include in the response to the client.
075 */
076 public void removeResponseControl(Control control);
077
078
079
080 /**
081 * Retrieves the result code for this operation.
082 *
083 * @return The result code associated for this operation, or
084 * <CODE>UNDEFINED</CODE> if the operation has not yet
085 * completed.
086 */
087 public ResultCode getResultCode();
088
089
090
091 /**
092 * Specifies the result code for this operation.
093 *
094 * @param resultCode The result code for this operation.
095 */
096 public void setResultCode(ResultCode resultCode);
097
098
099
100 /**
101 * Retrieves the error message for this operation. Its contents may
102 * be altered by the caller.
103 *
104 * @return The error message for this operation.
105 */
106 public MessageBuilder getErrorMessage();
107
108
109
110 /**
111 * Specifies the error message for this operation.
112 *
113 * @param errorMessage The error message for this operation.
114 */
115 public void setErrorMessage(MessageBuilder errorMessage);
116
117
118
119 /**
120 * Appends the provided message to the error message buffer. If the
121 * buffer has not yet been created, then this will create it first
122 * and then add the provided message.
123 *
124 * @param message The message to append to the error message
125 */
126 public void appendErrorMessage(Message message);
127
128
129
130 /**
131 * Retrieves the additional log message for this operation, which
132 * should be written to the log but not included in the response to
133 * the client. The contents of this buffer may be altered by the
134 * caller.
135 *
136 * @return The additional log message for this operation.
137 */
138 public MessageBuilder getAdditionalLogMessage();
139
140
141
142 /**
143 * Specifies the additional log message for this operation, which
144 * should be written to the log but not included in the response to
145 * the client.
146 *
147 * @param additionalLogMessage The additional log message for this
148 * operation.
149 */
150 public void setAdditionalLogMessage(
151 MessageBuilder additionalLogMessage);
152
153
154
155 /**
156 * Appends the provided message to the additional log information
157 * for this operation.
158 *
159 * @param message The message that should be appended to the
160 * additional log information for this operation.
161 */
162 public void appendAdditionalLogMessage(Message message);
163
164
165
166 /**
167 * Retrieves the matched DN for this operation.
168 *
169 * @return The matched DN for this operation, or <CODE>null</CODE>
170 * if the operation has not yet completed or does not have
171 * a matched DN.
172 */
173 public DN getMatchedDN();
174
175
176
177 /**
178 * Specifies the matched DN for this operation.
179 *
180 * @param matchedDN The matched DN for this operation.
181 */
182 public void setMatchedDN(DN matchedDN);
183
184
185
186 /**
187 * Retrieves the set of referral URLs for this operation. Its
188 * contents must not be altered by the caller.
189 *
190 * @return The set of referral URLs for this operation, or
191 * <CODE>null</CODE> if the operation is not yet complete
192 * or does not have a set of referral URLs.
193 */
194 public List<String> getReferralURLs();
195
196
197
198 /**
199 * Specifies the set of referral URLs for this operation.
200 *
201 * @param referralURLs The set of referral URLs for this
202 * operation.
203 */
204 public void setReferralURLs(List<String> referralURLs);
205
206
207
208 /**
209 * Sets the response elements for this operation based on the
210 * information contained in the provided
211 * <CODE>DirectoryException</CODE> object.
212 *
213 * @param directoryException The exception containing the
214 * information to use for the response
215 * elements.
216 */
217 public void setResponseData(DirectoryException directoryException);
218
219
220
221 /**
222 * Retrieves the authorization DN for this operation. In many
223 * cases, it will be the same as the DN of the authenticated user
224 * for the underlying connection, or the null DN if no
225 * authentication has been performed on that connection. However,
226 * it may be some other value if special processing has been
227 * requested (e.g., the operation included a proxied authorization
228 * control).
229 *
230 * @return The authorization DN for this operation.
231 */
232 public DN getAuthorizationDN();
233 }
234