Package org.opends.server.types

Class Operation

    • Field Detail

      • requestContext

        protected final RequestContext requestContext
        The request context with which this operation is associated.

    • Constructor Detail

      • Operation

        protected Operation​(org.forgerock.services.context.Context context,
                    List<Control> requestControls)
        Creates a new operation with the provided information.
        Parameters:
        context - The context with which this operation is associated.
        requestControls - The set of controls included in the request.

    • Method Detail

      • getContext

        public org.forgerock.services.context.Context getContext()
        Returns the context associated to this operation.
        Returns:
        The context associated to this operation.

      • disconnectClient

        public void disconnectClient​(DisconnectReason disconnectReason,
                             boolean sendNotification,
                             LocalizableMessage message)
        Description copied from interface: PluginOperation
        Terminates the client connection being used to process this operation. The plugin must return a result indicating that the client connection has been terminated.
        Specified by:
        disconnectClient in interface PluginOperation
        Parameters:
        disconnectReason - The disconnect reason that provides the generic cause for the disconnect.
        sendNotification - Indicates whether to try to provide notification to the client that the connection will be closed.
        message - The message to send to the client. It may be null if no notification is to be sent.

      • getClientConnection

        public final ClientConnection getClientConnection()
        Description copied from interface: PluginOperation
        Retrieves the client connection with which this operation is associated.
        Specified by:
        getClientConnection in interface PluginOperation
        Returns:
        The client connection with which this operation is associated.

      • hasPrivilege

        public boolean hasPrivilege​(Privilege privilege)
        Returns whether the operation has the provided privilege.
        Parameters:
        privilege - the privilege to test
        Returns:
        true if the operation has the provided privilege,false otherwise

      • getConnectionID

        public final long getConnectionID()
        Description copied from interface: PluginOperation
        Retrieves the unique identifier that is assigned to the client connection that submitted this operation.
        Specified by:
        getConnectionID in interface PluginOperation
        Returns:
        The unique identifier that is assigned to the client connection that submitted this operation.

      • getOperationID

        public final long getOperationID()
        Description copied from interface: PluginOperation
        Retrieves the operation ID for this operation.
        Specified by:
        getOperationID in interface PluginOperation
        Returns:
        The operation ID for this operation.

      • getMessageID

        public final int getMessageID()
        Description copied from interface: PluginOperation
        Retrieves the message ID assigned to this operation.
        Specified by:
        getMessageID in interface PluginOperation
        Returns:
        The message ID assigned to this operation.

      • getRequestControls

        public final List<Control> getRequestControls()
        Description copied from interface: PluginOperation
        Retrieves the set of controls included in the request from the client. The returned this list must not be altered.
        Specified by:
        getRequestControls in interface PluginOperation
        Returns:
        The set of controls included in the request from the client.

      • getRequestControl

        public final <T extends Control> T getRequestControl​(ControlDecoder<T> d,
                                                     DecodeOptions options)
                                              throws LdapException
        Description copied from interface: PluginOperation
        Retrieves a control included in the request from the client.
        Specified by:
        getRequestControl in interface PluginOperation
        Type Parameters:
        T - The type of control requested.
        Parameters:
        d - The requested control's decoder.
        options - The decode options.
        Returns:
        The decoded form of the requested control included in the request from the client or null if the control was not found.
        Throws:
        LdapException - if an error occurs while decoding the control.

      • hasRequestControl

        public final boolean hasRequestControl​(String oid)
        Returns true if this operation contains the specified request control.
        Parameters:
        oid - The OID of the request control.
        Returns:
        true if this operation contains the specified request control.

      • addRequestControl

        public final void addRequestControl​(Control control)
        Adds the provided control to the set of request controls for this operation.

        This method may only be called by pre-parse plugins.

        Specified by:
        addRequestControl in interface PreParseOperation
        Parameters:
        control - The control to add to the set of request controls for this operation.

      • addResponseControl

        public abstract void addResponseControl​(Control control)
        Adds the provided control to the set of controls to include in the response to the client.

        This method may not be called by post-response plugins.

        Specified by:
        addResponseControl in interface PreParseOperation
        Parameters:
        control - The control to add to the set of controls to include in the response to the client.

      • removeResponseControl

        public abstract void removeResponseControl​(Control control)
        Removes the provided control from the set of controls to include in the response to the client.

        This method may not be called by post-response plugins.

        Specified by:
        removeResponseControl in interface PreParseOperation
        Parameters:
        control - The control to remove from the set of controls to include in the response to the client.

      • setResult

        public final void setResult​(Result result)
        Specifies the result for this operation. This method may not be called by post-response plugins.
        Parameters:
        result - The result for this operation.

      • setResultCode

        public final void setResultCode​(ResultCode resultCode)
        Specifies the result code for this operation. This method may not be called by post-response plugins.
        Parameters:
        resultCode - The result code for this operation.

      • setErrorMessage

        public final void setErrorMessage​(LocalizableMessageBuilder errorMessage)
        Specifies the error message for this operation.

        This method may not be called by post-response plugins.

        Specified by:
        setErrorMessage in interface PreParseOperation
        Parameters:
        errorMessage - The error message for this operation.

      • appendErrorMessage

        public final void appendErrorMessage​(LocalizableMessage message)
        Appends the provided message to the error message buffer. If the buffer has not yet been created, then this will create it first and then add the provided message.

        This method may not be called by post-response plugins.

        Specified by:
        appendErrorMessage in interface PreParseOperation
        Parameters:
        message - The message to append to the error message buffer.

      • appendMaskedErrorMessage

        public final void appendMaskedErrorMessage​(LocalizableMessage maskedMessage)
        Appends the provided message to the real, masked error message buffer. If the buffer has not yet been created, then this will create it first and then add the provided message. This method may not be called by post-response plugins.
        Parameters:
        maskedMessage - The message to append to the real, masked error message

      • addAdditionalLogItem

        public void addAdditionalLogItem​(AdditionalLogItem item)
        Description copied from interface: PreParseOperation
        Adds an additional log item to this operation, which should be written to the log but not included in the response to the client. This method may not be called by post-response plugins.
        Specified by:
        addAdditionalLogItem in interface PreParseOperation
        Parameters:
        item - The additional log item for this operation.

      • addPasswordPolicyWarningToLog

        public void addPasswordPolicyWarningToLog​(LocalizableMessage msg)
        Adds a password policy warning message in the Log additional items.
        Parameters:
        msg - the message to log.

      • setMatchedDN

        public final void setMatchedDN​(Dn matchedDN)
        Specifies the matched DN for this operation. This may not be called by post-response plugins.
        Parameters:
        matchedDN - The matched DN for this operation.

      • setReferralURLs

        public final void setReferralURLs​(List<String> referralURLs)
        Specifies the set of referral URLs for this operation. This may not be called by post-response plugins.
        Parameters:
        referralURLs - The set of referral URLs for this operation.

      • setResult

        public final void setResult​(LdapException e)
        Sets the response elements for this operation based on the information contained in the provided exception object. This method may not be called by post-response plugins.
        Parameters:
        e - The exception containing the information to use for the response elements.

      • isInternalOperation

        public final boolean isInternalOperation()
        Description copied from interface: PluginOperation
        Indicates whether this is an internal operation rather than one that was requested by an external client.
        Specified by:
        isInternalOperation in interface PluginOperation
        Returns:
        true if this is an internal operation, or false if it is not.

      • setInternalOperation

        public final void setInternalOperation​(boolean isInternalOperation)
        Specifies whether this is an internal operation rather than one that was requested by an external client. This may not be called from within a plugin.
        Parameters:
        isInternalOperation - Specifies whether this is an internal operation rather than one that was requested by an external client.

      • isInnerOperation

        public boolean isInnerOperation()
        Indicates whether this is an inner operation rather than one that was directly requested by an external client. Said otherwise, inner operations include internal operations, but also operations in the server indirectly mandated by external requests like Rest2LDAP for example. This may not be called from within a plugin.
        Returns:
        true if this is an inner operation, or false if it is not.

      • setInnerOperation

        public void setInnerOperation​(boolean isInnerOperation)
        Specifies whether this is an inner operation rather than one that was directly requested by an external client. Said otherwise, inner operations include internal operations, but also operations in the server indirectly mandated by external requests like Rest2LDAP for example. This may not be called from within a plugin.
        Parameters:
        isInnerOperation - Specifies whether this is an inner operation rather than one that was requested by an external client.

      • isSynchronizationOperation

        public final boolean isSynchronizationOperation()
        Description copied from interface: PluginOperation
        Indicates whether this is a synchronization operation rather than one that was requested by an external client.
        Specified by:
        isSynchronizationOperation in interface PluginOperation
        Returns:
        true if this is a data synchronization operation, or false if it is not.

      • setSynchronizationOperation

        public final void setSynchronizationOperation​(boolean isSynchronizationOperation)
        Specifies whether this operation must be synchronized to other copies of the data.
        Parameters:
        isSynchronizationOperation - Specifies whether this operation must be synchronized to other copies of the data.

      • dontSynchronize

        public boolean dontSynchronize()
        Indicates whether this operation needs to be synchronized to other copies of the data.
        Returns:
        true if this operation should not be synchronized, or false if it should be synchronized.

      • setDontSynchronize

        public final void setDontSynchronize​(boolean dontSynchronize)
        Specifies whether this operation must be synchronized to other copies of the data.
        Parameters:
        dontSynchronize - Specifies whether this operation must be synchronized to other copies of the data.

      • getAuthorizationEntry

        public final Entry getAuthorizationEntry()
        Retrieves the entry for the user that should be considered the authorization identity for this operation. In many cases, it will be the same as the authorization entry for the underlying client connection, or null if no authentication has been performed on that connection. However, it may be some other value if special processing has been requested (e.g., the operation included a proxied authorization control). This method should not be called by pre-parse plugins because the correct value may not yet have been determined.
        Returns:
        The entry for the user that should be considered the authorization identity for this operation, or null if the authorization identity should be the unauthenticated user.

      • setAuthorizationEntry

        public final void setAuthorizationEntry​(Entry authorizationEntry)
        Provides the entry for the user that should be considered the authorization identity for this operation. This must not be called from within a plugin.
        Parameters:
        authorizationEntry - The entry for the user that should be considered the authorization identity for this operation, or null if it should be the unauthenticated user.

      • getAuthorizationDN

        public final Dn getAuthorizationDN()
        Retrieves the authorization DN for this operation. In many cases, it will be the same as the DN of the authenticated user for the underlying connection, or the null DN if no authentication has been performed on that connection. However, it may be some other value if special processing has been requested (e.g., the operation included a proxied authorization control).

        This method should not be called by pre-parse plugins because the correct value may not have yet been determined.

        Specified by:
        getAuthorizationDN in interface PostCommitOperation
        Specified by:
        getAuthorizationDN in interface PostResponseOperation
        Returns:
        The authorization DN for this operation.

      • getAttachments

        public final Map<String,​Object> getAttachments()
        Description copied from interface: PluginOperation
        Retrieves the set of attachments defined for this operation, as a mapping between the attachment name and the associated object.
        Specified by:
        getAttachments in interface PluginOperation
        Returns:
        The set of attachments defined for this operation.

      • setAttachments

        public final void setAttachments​(Map<String,​Object> attachments)
        Set the attachments to the operation.
        Parameters:
        attachments - Attachments to register within the operation

      • getAttachment

        public final <T> T getAttachment​(String name)
        Description copied from interface: PluginOperation
        Retrieves the attachment with the specified name.
        Specified by:
        getAttachment in interface PluginOperation
        Type Parameters:
        T - the type of the attached object
        Parameters:
        name - The name for the attachment to retrieve. It will be treated in a case-sensitive manner.
        Returns:
        The requested attachment object, or null if it does not exist.

      • removeAttachment

        public final <T> T removeAttachment​(String name)
        Description copied from interface: PluginOperation
        Removes the attachment with the specified name.
        Specified by:
        removeAttachment in interface PluginOperation
        Type Parameters:
        T - the type of the attached object
        Parameters:
        name - The name for the attachment to remove. It will be treated in a case-sensitive manner.
        Returns:
        The attachment that was removed, or null if it does not exist.

      • setAttachment

        public final void setAttachment​(String name,
                                Object value)
        Description copied from interface: PluginOperation
        Sets the value of the specified attachment. If an attachment already exists with the same name, it will be replaced. Otherwise, a new attachment will be added.
        Specified by:
        setAttachment in interface PluginOperation
        Parameters:
        name - The name to use for the attachment.
        value - The value to use for the attachment.

      • operationCompleted

        public final void operationCompleted()
        Indicates that processing on this operation has completed successfully and that the client should perform any associated cleanup work.

      • toString

        public final String toString()
        Description copied from interface: PluginOperation
        Retrieves a string representation of this operation.
        Specified by:
        toString in interface PluginOperation
        Overrides:
        toString in class Object
        Returns:
        A string representation of this operation.

      • toString

        public abstract void toString​(StringBuilder buffer)
        Description copied from interface: PluginOperation
        Appends a string representation of this operation to the provided buffer.
        Specified by:
        toString in interface PluginOperation
        Parameters:
        buffer - The buffer into which a string representation of this operation should be appended.

      • registerPostResponseCallback

        public final void registerPostResponseCallback​(Runnable callback)
        Registers a callback which should be run once this operation has completed and the response sent back to the client.
        Parameters:
        callback - The callback to be run once this operation has completed and the response sent back to the client.

      • getProxiedAuthorizationDN

        public abstract Dn getProxiedAuthorizationDN()
        Retrieves the proxied authorization DN for this operation if proxied authorization has been requested.
        Returns:
        The proxied authorization DN for this operation if proxied authorization has been requested, or null if proxied authorization has not been requested.

      • setProxiedAuthorizationDN

        public abstract void setProxiedAuthorizationDN​(Dn proxiedAuthorizationDN)
        Set the proxied authorization DN for this operation if proxied authorization has been requested.
        Parameters:
        proxiedAuthorizationDN - The proxied authorization DN for this operation if proxied authorization has been requested, or null if proxied authorization has not been requested.

      • hashCode

        public final int hashCode()
        Overrides:
        hashCode in class Object

      • equals

        public final boolean equals​(Object obj)
        Overrides:
        equals in class Object

      • invokePostResponseCallbacks

        protected final void invokePostResponseCallbacks()
        Invokes the post response callbacks that were registered with this operation.

      • processOperationResult

        public boolean processOperationResult​(PluginResult.OperationResult operationResult)
        Processes the provided operation result for the current operation.
        Parameters:
        operationResult - the operation result
        Returns:
        true if processing can continue, false otherwise

      • processOperationResult

        public static boolean processOperationResult​(Operation op,
                                             PluginResult.OperationResult opResult)
        Processes the provided operation result for the provided operation.
        Parameters:
        op - the operation
        opResult - the operation result
        Returns:
        true if processing can continue, false otherwise

      • isProxyAuthzControl

        protected static boolean isProxyAuthzControl​(String oid)
        Check if an OID is for a proxy authorization control.
        Parameters:
        oid - The OID to check
        Returns:
        true if the OID is for a proxy auth v1 or v2 control, false otherwise.

      • removeAllDisallowedControls

        protected void removeAllDisallowedControls​(Dn targetDN)
                                    throws LdapException
        Removes all the disallowed request controls from this operation.

        As per RFC 4511 4.1.11, if a disallowed request control is critical, then a LdapException is thrown with unavailableCriticalExtension. Otherwise, if the disallowed request control is non critical, it is removed because we do not want the backend to process it.

        Parameters:
        targetDN - the target DN of the operation
        Throws:
        LdapException - If a disallowed request control is critical, thrown with unavailableCriticalExtension. If an error occurred while performing the access control check. For example, if an attribute could not be decoded. Care must be taken not to expose any potentially sensitive information in the exception.

      • evaluateProxyAuthControls

        public void evaluateProxyAuthControls()
                               throws LdapException
        Evaluate all aci and privilege checks for any proxy auth controls. This must be done before evaluating all other controls so that their aci can then be checked correctly.
        Throws:
        LdapException - if a proxy auth control is found but cannot be used.

      • createLdapException

        protected static LdapException createLdapException​(Operation operation,
                                                   Entry entry,
                                                   Dn entryDN,
                                                   Result result,
                                                   Result altResult)
                                            throws LdapException
        Returns a new LdapException built from the provided resultCodes and messages. Depending on whether ACIs prevent information disclosure, the provided resultCode and message will be masked and altResultCode and altMessage will be used instead.
        Parameters:
        operation - the operation for which to check if ACIs prevent information disclosure
        entry - the entry for which to check if ACIs prevent information disclosure, if null, then a fake entry will be created from the entryDN parameter
        entryDN - the entry dn for which to check if ACIs prevent information disclosure. Only used if entry is null.
        result - the result containing the result code and message to put on the LdapException if ACIs allow disclosure. Otherwise it will be put on the LdapException as a masked result code.
        altResult - the result contains the result code and message to put on the LdapException if ACIs do not allow disclosing the resultCode.
        Returns:
        a newLdapException containing the provided resultCodes and messages depending on ACI allowing disclosure or not
        Throws:
        LdapException - If an error occurred while performing the access control check.

      • setResultCodeAndMessageNoInfoDisclosure

        protected static void setResultCodeAndMessageNoInfoDisclosure​(Operation operation,
                                                              Entry entry,
                                                              Dn entryDN,
                                                              Result realResult,
                                                              Result altResult)
                                                       throws LdapException
        Sets the provided resultCodes and messages on the provided operation. Depending on whether ACIs prevent information disclosure, the provided resultCode and message will be masked and altResultCode and altMessage will be used instead.
        Parameters:
        operation - the operation for which to check if ACIs prevent information disclosure
        entry - the entry for which to check if ACIs prevent information disclosure, if null, then a fake entry will be created from the entryDN parameter
        entryDN - the entry dn for which to check if ACIs prevent information disclosure. Only used if entry is null.
        realResult - the result containing the result code and the message to put on the LdapException if ACIs allow disclosure. Otherwise it will be put on the LdapException as a masked result code.
        altResult - the result containing the result code and the message to put on the LdapException if ACIs do not allow disclosing the resultCode.
        Throws:
        LdapException - If an error occurred while performing the access control check.

      • filterNonDisclosableMatchedDN

        protected static void filterNonDisclosableMatchedDN​(Operation operation)
        Removes the matchedDN from the supplied operation if ACIs prevent its disclosure.
        Parameters:
        operation - where to filter the matchedDN from

      • addPostReadResponse

        protected static void addPostReadResponse​(Operation operation,
                                          PostReadRequestControl postReadRequest,
                                          Entry entry)
        Adds the post-read response control to the response if requested.
        Parameters:
        operation - The update operation.
        postReadRequest - The request control, if present.
        entry - The post-update entry.

      • addPreReadResponse

        protected static void addPreReadResponse​(Operation operation,
                                         PreReadRequestControl preReadRequest,
                                         Entry entry)
        Adds the pre-read response control to the response if requested.
        Parameters:
        operation - The update operation.
        preReadRequest - The request control, if present.
        entry - The pre-update entry.

      • checkIfBackendIsWritable

        protected static void checkIfBackendIsWritable​(LocalBackend<?> backend,
                                               Operation op,
                                               Dn entryDN,
                                               LocalizableMessageDescriptor.Arg1<Object> serverMsg,
                                               LocalizableMessageDescriptor.Arg1<Object> backendMsg)
                                        throws LdapException
        Checks if an update operation can be performed against a backend. The operation will be rejected based on the server and backend writability modes.
        Parameters:
        backend - The backend handling the update.
        op - The update operation.
        entryDN - The name of the entry being updated.
        serverMsg - The message to log if the update was rejected because the server is read-only.
        backendMsg - The message to log if the update was rejected because the backend is read-only.
        Throws:
        LdapException - If the update operation has been rejected.

      • getLocalBackend

        protected LocalBackend<?> getLocalBackend()
        Returns the local backend targeted by the provided operation.
        Returns:
        the local backend targeted by the provided operation

      • getLargestEntrySize

        public final long getLargestEntrySize()
        Returns the operation largest entry size, or zero if no size is available.
        Returns:
        the operation largest entry size, or zero if no size is available.

      • trySetLargestEntrySize

        public final void trySetLargestEntrySize​(long size)
        Try to update the size of the largest entry that has been accessed by the request.
        Parameters:
        size - The size of the latest entry that has been accessed by the request.

      • checkAttributeConformsToSyntax

        protected void checkAttributeConformsToSyntax​(Entry entry,
                                              Attribute attribute,
                                              LocalizableMessageDescriptor.Arg4<Object,​Object,​Object,​Object> invalidSyntaxErrorMsg,
                                              LocalizableMessageDescriptor.Arg3<Object,​Object,​Object> invalidSyntaxNoValueErrorMsg,
                                              LocalizableMessageDescriptor.Arg1<Object> rejectErrorMsg)
                                       throws LdapException
        Checks whether an attribute's values conform to its syntax. The server's syntax enforcement policy is applied if an invalid value is encountered.
        Parameters:
        entry - The entry being modified or renamed.
        attribute - The attribute whose values are to be checked.
        invalidSyntaxErrorMsg - The error message which should be used for human readable syntaxes.
        invalidSyntaxNoValueErrorMsg - The error message which should be used for binary syntaxes.
        rejectErrorMsg - The error message which should be used when the request is to be rejected.
        Throws:
        LdapException - If an invalid value is encountered and strict enforcement is enabled.

      • getServerContext

        protected static ServerContext getServerContext()
        Returns the server context.
        Returns:
        the server context

      • mustCheckSchema

        protected boolean mustCheckSchema()
        Returns true if a request must be validated according to the server's schema.
        Returns:
        true if a request must be validated according to the server's schema.

      • run

        public final void run()
        Performs the work of actually processing this operation. This should include all processing for the operation, including invoking pre-parse and post-response plugins, logging messages and any other work that might need to be done in the course of processing.
        Specified by:
        run in interface Runnable

      • run0

        protected abstract void run0()
        Performs the work of actually processing this operation.