Package org.opends.server.core

Class PersistentSearch

  • public final class PersistentSearch
extends Object
    This class defines a data structure that will be used to hold the information necessary for processing a persistent search.

    Work flow element implementations are responsible for managing the persistent searches that they are currently handling.

    Typically, a work flow element search operation will first decode the persistent search control and construct a new PersistentSearch.

    Once the initial search result set has been returned and no errors encountered, the work flow element implementation should register a cancellation callback which will be invoked when the persistent search is cancelled. This is achieved using registerCancellationCallback(CancellationCallback). The callback should make sure that any resources associated with the PersistentSearch are released. This may included removing the PersistentSearch from a list, or abandoning a persistent search operation that has been sent to a remote server.

    Finally, the PersistentSearch should be enabled using enable(). This method will register the PersistentSearch with the client connection and notify the underlying search operation that no result should be sent to the client.

    Work flow element implementations should cancel() active persistent searches when the work flow element fails or is shut down.

    • Constructor Detail

      • PersistentSearch

        public PersistentSearch​(SearchOperation searchOperation,
                        Set<PersistentSearchChangeType> changeTypes,
                        boolean changesOnly,
                        boolean returnECs)
        Creates a new persistent search object with the provided information.
        Parameters:
        searchOperation - The search operation for this persistent search.
        changeTypes - The change types for which changes should be examined.
        changesOnly - whether to only return entries that have been updated since the beginning of the search
        returnECs - Indicates whether to include entry change notification controls in search result entries sent to the client.

    • Method Detail

      • cancel

        public CancelResult cancel()
        Cancels this persistent search operation. On exit this persistent search will no longer be valid and any resources associated with it will have been released. In addition, any other persistent searches that are associated with this persistent search will also be canceled.
        Returns:
        The result of the cancellation.

      • cancelAndNotifyClient

        public CancelResult cancelAndNotifyClient​(org.forgerock.i18n.LocalizableMessage reason)
        Cancels this persistent search and tells the client that no more changes will be reported for it. Contrary to cancel(), which leaves the search open as far as the client can tell, this is meant for cancellations decided by the server: without a search result done, the client waits forever for changes on a search which no longer exists.
        Parameters:
        reason - The reason why this persistent search is terminated, reported to the client.
        Returns:
        The result of the cancellation.

      • getMessageID

        public int getMessageID()
        Gets the message ID associated with this persistent search.
        Returns:
        The message ID associated with this persistent search.

      • getSearchOperation

        public SearchOperation getSearchOperation()
        Get the search operation associated with this persistent search.
        Returns:
        The search operation associated with this persistent search.

      • isChangesOnly

        public boolean isChangesOnly()
        Returns whether only entries updated after the beginning of this persistent search should be returned.
        Returns:
        true if only entries updated after the beginning of this search should be returned, false otherwise

      • processAdd

        public void processAdd​(Entry entry)
        Notifies the persistent searches that an entry has been added.
        Parameters:
        entry - The entry that was added.

      • processDelete

        public void processDelete​(Entry entry)
        Notifies the persistent searches that an entry has been deleted.
        Parameters:
        entry - The entry that was deleted.

      • processModify

        public void processModify​(Entry entry)
        Notifies the persistent searches that an entry has been modified.
        Parameters:
        entry - The entry after it was modified.

      • processModify

        public void processModify​(Entry entry,
                          Entry oldEntry)
        Notifies persistent searches that an entry has been modified.
        Parameters:
        entry - The entry after it was modified.
        oldEntry - The entry before it was modified.

      • processModifyDN

        public void processModifyDN​(Entry entry,
                            DN oldDN)
        Notifies the persistent searches that an entry has been renamed.
        Parameters:
        entry - The entry after it was modified.
        oldDN - The DN of the entry before it was renamed.

      • registerCancellationCallback

        public void registerCancellationCallback​(PersistentSearch.CancellationCallback callback)
        Registers a cancellation callback with this persistent search. The cancellation callback will be notified when this persistent search has been cancelled.
        Parameters:
        callback - The cancellation callback.

      • enable

        public void enable()
        Enable this persistent search. The persistent search will be registered with the client connection and will be prevented from sending responses to the client.

      • toString

        public String toString()
        Retrieves a string representation of this persistent search.
        Overrides:
        toString in class Object
        Returns:
        A string representation of this persistent search.

      • toString

        public void toString​(StringBuilder buffer)
        Appends a string representation of this persistent search to the provided buffer.
        Parameters:
        buffer - The buffer to which the information should be appended.