001/*
002 * Copyright 2014-2017 UnboundID Corp.
003 * All Rights Reserved.
004 */
005/*
006 * Copyright (C) 2014-2017 UnboundID Corp.
007 *
008 * This program is free software; you can redistribute it and/or modify
009 * it under the terms of the GNU General Public License (GPLv2 only)
010 * or the terms of the GNU Lesser General Public License (LGPLv2.1 only)
011 * as published by the Free Software Foundation.
012 *
013 * This program is distributed in the hope that it will be useful,
014 * but WITHOUT ANY WARRANTY; without even the implied warranty of
015 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
016 * GNU General Public License for more details.
017 *
018 * You should have received a copy of the GNU General Public License
019 * along with this program; if not, see <http://www.gnu.org/licenses>.
020 */
021package com.unboundid.ldap.listener.interceptor;
022
023
024
025import com.unboundid.ldap.sdk.Entry;
026import com.unboundid.ldap.sdk.IntermediateResponse;
027import com.unboundid.ldap.sdk.LDAPException;
028import com.unboundid.ldap.sdk.LDAPResult;
029import com.unboundid.ldap.sdk.ReadOnlySearchRequest;
030import com.unboundid.ldap.sdk.SearchResultReference;
031import com.unboundid.util.NotExtensible;
032import com.unboundid.util.ThreadSafety;
033import com.unboundid.util.ThreadSafetyLevel;
034
035
036
037/**
038 * This class provides an API that can be used in the course of processing a
039 * search request via the {@link InMemoryOperationInterceptor} API.
040 */
041@NotExtensible()
042@ThreadSafety(level=ThreadSafetyLevel.INTERFACE_NOT_THREADSAFE)
043public interface InMemoryInterceptedSearchResult
044       extends InMemoryInterceptedResult
045{
046  /**
047   * Retrieves the search request that was processed.  If the request was
048   * altered between the time it was received from the client and the time it
049   * was actually processed by the in-memory directory server, then this will be
050   * the most recently altered version.
051   *
052   * @return  The search request that was processed.
053   */
054  ReadOnlySearchRequest getRequest();
055
056
057
058  /**
059   * Retrieves the search result to be returned to the client.
060   *
061   * @return  The search result to be returned to the client.
062   */
063  LDAPResult getResult();
064
065
066
067  /**
068   * Replaces the search result to be returned to the client.
069   *
070   * @param  searchResult  The search result that should be returned to the
071   *                       client instead of the result originally generated by
072   *                       the in-memory directory server.  It must not be
073   *                       {@code null}.
074   */
075  void setResult(final LDAPResult searchResult);
076
077
078
079  /**
080   * Sends the provided search result entry to the client.  It will be processed
081   * by the {@link InMemoryOperationInterceptor#processSearchEntry} method of
082   * all registered operation interceptors.
083   *
084   * @param  entry  The search result entry to be returned to the client.  It
085   *                must not be {@code null}.  If the provided entry is a
086   *                {@code SearchResultEntry}, then it may optionally include
087   *                one or more controls to provide to the client.  If it is any
088   *                other type of {@code Entry}, then it will not include any
089   *                controls.
090   *
091   * @throws  LDAPException  If a problem is encountered while trying to send
092   *                         the search result entry.
093   */
094  void sendSearchEntry(final Entry entry)
095       throws LDAPException;
096
097
098
099  /**
100   * Sends the provided search result reference to the client.  It will be
101   * processed by the
102   * {@link InMemoryOperationInterceptor#processSearchReference} method of all
103   * registered operation interceptors.
104   *
105   * @param  reference  The search result reference to be returned to the
106   *                    client.  It must not be {@code null}.
107   *
108   * @throws  LDAPException  If a problem is encountered while trying to send
109   *                         the search result reference.
110   */
111  void sendSearchReference(final SearchResultReference reference)
112       throws LDAPException;
113
114
115
116  /**
117   * Sends the provided intermediate response message to the client.  It will
118   * be processed by the
119   * {@link InMemoryOperationInterceptor#processIntermediateResponse} method of
120   * all registered operation interceptors.
121   *
122   * @param  intermediateResponse  The intermediate response to send to the
123   *                               client.  It must not be {@code null}.
124   *
125   * @throws  LDAPException  If a problem is encountered while trying to send
126   *                         the intermediate response.
127   */
128  void sendIntermediateResponse(final IntermediateResponse intermediateResponse)
129         throws LDAPException;
130}