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     * post-operation plugins for all types of operations.  Note that this
045     * interface is intended only to define an API for use by plugins and
046     * is not intended to be implemented by any custom classes.
047     */
048    @org.opends.server.types.PublicAPI(
049         stability=org.opends.server.types.StabilityLevel.UNCOMMITTED,
050         mayInstantiate=false,
051         mayExtend=false,
052         mayInvoke=true)
053    public interface PostOperationOperation
054           extends PluginOperation
055    {
056      /**
057       * Adds the provided control to the set of controls to include in
058       * the response to the client.
059       *
060       * @param  control  The control to add to the set of controls to
061       *                  include in the response to the client.
062       */
063      public void addResponseControl(Control control);
064    
065    
066    
067      /**
068       * Removes the provided control from the set of controls to include
069       * in the response to the client.
070       *
071       * @param  control  The control to remove from the set of controls
072       *                  to include in the response to the client.
073       */
074      public void removeResponseControl(Control control);
075    
076    
077    
078      /**
079       * Retrieves the result code for this operation.
080       *
081       * @return  The result code associated for this operation, or
082       *          <CODE>UNDEFINED</CODE> if the operation has not yet
083       *          completed.
084       */
085      public ResultCode getResultCode();
086    
087    
088    
089      /**
090       * Specifies the result code for this operation.
091       *
092       * @param  resultCode  The result code for this operation.
093       */
094      public void setResultCode(ResultCode resultCode);
095    
096    
097    
098      /**
099       * Retrieves the error message for this operation.  Its contents may
100       * be altered by the caller.
101       *
102       * @return  The error message for this operation.
103       */
104      public MessageBuilder getErrorMessage();
105    
106    
107    
108      /**
109       * Specifies the error message for this operation.
110       *
111       * @param  errorMessage  The error message for this operation.
112       */
113      public void setErrorMessage(MessageBuilder errorMessage);
114    
115    
116    
117      /**
118       * Appends the provided message to the error message buffer.  If the
119       * buffer has not yet been created, then this will create it first
120       * and then add the provided message.
121       *
122       * @param  message  The message to append to the error message
123       */
124      public void appendErrorMessage(Message message);
125    
126    
127    
128      /**
129       * Retrieves the additional log message for this operation, which
130       * should be written to the log but not included in the response to
131       * the client.  The contents of this buffer may be altered by the
132       * caller.
133       *
134       * @return  The additional log message for this operation.
135       */
136      public MessageBuilder getAdditionalLogMessage();
137    
138    
139    
140      /**
141       * Specifies the additional log message for this operation, which
142       * should be written to the log but not included in the response to
143       * the client.
144       *
145       * @param  additionalLogMessage  The additional log message for this
146       *                               operation.
147       */
148      public void setAdditionalLogMessage(
149                       MessageBuilder additionalLogMessage);
150    
151    
152    
153      /**
154       * Appends the provided message to the additional log information
155       * for this operation.
156       *
157       * @param  message  The message that should be appended to the
158       *                  additional log information for this operation.
159       */
160      public void appendAdditionalLogMessage(Message message);
161    
162    
163    
164      /**
165       * Retrieves the matched DN for this operation.
166       *
167       * @return  The matched DN for this operation, or <CODE>null</CODE>
168       *          if the operation has not yet completed or does not have
169       *          a matched DN.
170       */
171      public DN getMatchedDN();
172    
173    
174    
175      /**
176       * Specifies the matched DN for this operation.
177       *
178       * @param  matchedDN  The matched DN for this operation.
179       */
180      public void setMatchedDN(DN matchedDN);
181    
182    
183    
184      /**
185       * Retrieves the set of referral URLs for this operation.  Its
186       * contents must not be altered by the caller.
187       *
188       * @return  The set of referral URLs for this operation, or
189       *          <CODE>null</CODE> if the operation is not yet complete
190       *          or does not have a set of referral URLs.
191       */
192      public List<String> getReferralURLs();
193    
194    
195    
196      /**
197       * Specifies the set of referral URLs for this operation.
198       *
199       * @param  referralURLs  The set of referral URLs for this
200       *                       operation.
201       */
202      public void setReferralURLs(List<String> referralURLs);
203    
204    
205    
206      /**
207       * Sets the response elements for this operation based on the
208       * information contained in the provided
209       * <CODE>DirectoryException</CODE> object.
210       *
211       * @param  directoryException  The exception containing the
212       *                             information to use for the response
213       *                             elements.
214       */
215      public void setResponseData(DirectoryException directoryException);
216    
217    
218    
219      /**
220       * Retrieves the authorization DN for this operation.  In many
221       * cases, it will be the same as the DN of the authenticated user
222       * for the underlying connection, or the null DN if no
223       * authentication has been performed on that connection.  However,
224       * it may be some other value if special processing has been
225       * requested (e.g., the operation included a proxied authorization
226       * control).
227       *
228       * @return  The authorization DN for this operation.
229       */
230      public DN getAuthorizationDN();
231    }
232