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    import org.opends.server.types.Control;
032    import org.opends.server.types.DN;
033    
034    import org.opends.messages.MessageBuilder;
035    
036    
037    /**
038     * This class defines a set of methods that are available for use by
039     * pre-operation plugins for all types of operations.  Note that this
040     * interface is intended only to define an API for use by plugins and
041     * is not intended to be implemented by any custom classes.
042     */
043    @org.opends.server.types.PublicAPI(
044         stability=org.opends.server.types.StabilityLevel.UNCOMMITTED,
045         mayInstantiate=false,
046         mayExtend=false,
047         mayInvoke=true)
048    public interface PreOperationOperation
049           extends PluginOperation
050    {
051      /**
052       * Adds the provided control to the set of controls to include in
053       * the response to the client.
054       *
055       * @param  control  The control to add to the set of controls to
056       *                  include in the response to the client.
057       */
058      public void addResponseControl(Control control);
059    
060    
061    
062      /**
063       * Removes the provided control from the set of controls to include
064       * in the response to the client.
065       *
066       * @param  control  The control to remove from the set of controls
067       *                  to include in the response to the client.
068       */
069      public void removeResponseControl(Control control);
070    
071    
072    
073      /**
074       * Retrieves the error message for this operation.  Its contents may
075       * be altered by the caller.
076       *
077       * @return  The error message for this operation.
078       */
079      public MessageBuilder getErrorMessage();
080    
081    
082    
083      /**
084       * Specifies the error message for this operation.
085       *
086       * @param  errorMessage  The error message for this operation.
087       */
088      public void setErrorMessage(MessageBuilder errorMessage);
089    
090    
091    
092      /**
093       * Appends the provided message to the error message buffer.  If the
094       * buffer has not yet been created, then this will create it first
095       * and then add the provided message.
096       *
097       * @param  message  The message to append to the error message
098       *                  buffer.
099       */
100      public void appendErrorMessage(Message message);
101    
102    
103    
104      /**
105       * Retrieves the additional log message for this operation, which
106       * should be written to the log but not included in the response to
107       * the client.  The contents of this buffer may be altered by the
108       * caller.
109       *
110       * @return  The additional log message for this operation.
111       */
112      public MessageBuilder getAdditionalLogMessage();
113    
114    
115    
116      /**
117       * Specifies the additional log message for this operation, which
118       * should be written to the log but not included in the response to
119       * the client.
120       *
121       * @param  additionalLogMessage  The additional log message for this
122       */
123      public void setAdditionalLogMessage(
124                       MessageBuilder additionalLogMessage);
125    
126    
127    
128      /**
129       * Appends the provided message to the additional log information
130       * for this operation.
131       *
132       * @param  message  The message that should be appended to the
133       *                  additional log information for this operation.
134       */
135      public void appendAdditionalLogMessage(Message message);
136    
137    
138    
139      /**
140       * Retrieves the authorization DN for this operation.  In many
141       * cases, it will be the same as the DN of the authenticated user
142       * for the underlying connection, or the null DN if no
143       * authentication has been performed on that connection.  However,
144       * it may be some other value if special processing has been
145       * requested (e.g., the operation included a proxied authorization
146       * control).
147       *
148       * @return  The authorization DN for this operation.
149       */
150      public DN getAuthorizationDN();
151    }
152