001/*
002 * The contents of this file are subject to the terms of the Common Development and
003 * Distribution License (the License). You may not use this file except in compliance with the
004 * License.
005 *
006 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
007 * specific language governing permission and limitations under the License.
008 *
009 * When distributing Covered Software, include this CDDL Header Notice in each file and include
010 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
011 * Header, with the fields enclosed by brackets [] replaced by your own identifying
012 * information: "Portions Copyright [year] [name of copyright owner]".
013 *
014 * Copyright 2006-2008 Sun Microsystems, Inc.
015 * Portions Copyright 2011-2016 ForgeRock AS.
016 */
017package org.opends.server.types.operation;
018import java.util.List;
019
020import org.forgerock.i18n.LocalizableMessage;
021
022
023import org.opends.server.types.AdditionalLogItem;
024import org.opends.server.types.Control;
025import org.forgerock.opendj.ldap.DN;
026
027import org.forgerock.i18n.LocalizableMessageBuilder;
028
029
030/**
031 * This class defines a set of methods that are available for use by
032 * pre-operation plugins for all types of operations.  Note that this
033 * interface is intended only to define an API for use by plugins and
034 * is not intended to be implemented by any custom classes.
035 */
036@org.opends.server.types.PublicAPI(
037     stability=org.opends.server.types.StabilityLevel.UNCOMMITTED,
038     mayInstantiate=false,
039     mayExtend=false,
040     mayInvoke=true)
041public interface PreOperationOperation
042       extends PluginOperation
043{
044  /**
045   * Adds the provided control to the set of controls to include in
046   * the response to the client.
047   *
048   * @param  control  The control to add to the set of controls to
049   *                  include in the response to the client.
050   */
051  void addResponseControl(Control control);
052
053
054
055  /**
056   * Removes the provided control from the set of controls to include
057   * in the response to the client.
058   *
059   * @param  control  The control to remove from the set of controls
060   *                  to include in the response to the client.
061   */
062  void removeResponseControl(Control control);
063
064
065
066  /**
067   * Retrieves the error message for this operation.  Its contents may
068   * be altered by the caller.
069   *
070   * @return  The error message for this operation.
071   */
072  LocalizableMessageBuilder getErrorMessage();
073
074
075
076  /**
077   * Specifies the error message for this operation.
078   *
079   * @param  errorMessage  The error message for this operation.
080   */
081  void setErrorMessage(LocalizableMessageBuilder errorMessage);
082
083
084
085  /**
086   * Appends the provided message to the error message buffer.  If the
087   * buffer has not yet been created, then this will create it first
088   * and then add the provided message.
089   *
090   * @param  message  The message to append to the error message
091   *                  buffer.
092   */
093  void appendErrorMessage(LocalizableMessage message);
094
095
096
097  /**
098   * Retrieves the authorization DN for this operation.  In many
099   * cases, it will be the same as the DN of the authenticated user
100   * for the underlying connection, or the null DN if no
101   * authentication has been performed on that connection.  However,
102   * it may be some other value if special processing has been
103   * requested (e.g., the operation included a proxied authorization
104   * control).
105   *
106   * @return  The authorization DN for this operation.
107   */
108  DN getAuthorizationDN();
109
110
111
112  /**
113   * Returns an unmodifiable list containing the additional log items for this
114   * operation, which should be written to the log but not included in the
115   * response to the client.
116   *
117   * @return An unmodifiable list containing the additional log items for this
118   *         operation.
119   */
120  List<AdditionalLogItem> getAdditionalLogItems();
121
122
123
124  /**
125   * Adds an additional log item to this operation, which should be written to
126   * the log but not included in the response to the client. This method may not
127   * be called by post-response plugins.
128   *
129   * @param item
130   *          The additional log item for this operation.
131   */
132  void addAdditionalLogItem(AdditionalLogItem item);
133}
134