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