001/*
002 *  Licensed to the Apache Software Foundation (ASF) under one
003 *  or more contributor license agreements.  See the NOTICE file
004 *  distributed with this work for additional information
005 *  regarding copyright ownership.  The ASF licenses this file
006 *  to you under the Apache License, Version 2.0 (the
007 *  "License"); you may not use this file except in compliance
008 *  with the License.  You may obtain a copy of the License at
009 *  
010 *    http://www.apache.org/licenses/LICENSE-2.0
011 *  
012 *  Unless required by applicable law or agreed to in writing,
013 *  software distributed under the License is distributed on an
014 *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 *  KIND, either express or implied.  See the License for the
016 *  specific language governing permissions and limitations
017 *  under the License. 
018 *  
019 */
020package org.apache.directory.server.core.api.filtering;
021
022
023import org.apache.directory.api.ldap.model.entry.Entry;
024import org.apache.directory.api.ldap.model.exception.LdapException;
025import org.apache.directory.server.core.api.interceptor.context.SearchOperationContext;
026
027
028/**
029 * An entry filter is used to modify search results while they are being 
030 * returned from Cursors over ServerEntry objects.  These filters are used in
031 * conjunction with a FilteringCursor.  Multiple filters can be 
032 * applied one after the other and hence they are stack-able and applied in
033 * order.
034 *
035 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
036 */
037public interface EntryFilter
038{
039    /**
040     * Filters the contents of search entries on the way out the door to 
041     * client callers.  These filters can and do produce side-effects on the 
042     * entry results if need be.  These entries, their attributes and values
043     * should be cloned when alterations are made to avoid altering cached
044     * entries.
045     *
046     * @param operation The SeachOperationContext instance
047     * @param result the result to accept or reject possibly modifying it
048     * @return true if the entry is to be returned, false if it is rejected
049     * @throws LdapException if there are failures during evaluation
050     */
051    boolean accept( SearchOperationContext operation, Entry result ) throws LdapException;
052    
053    
054    /**
055     * The pretty-printer for this class
056     * @param tabs The tabs to add before each line
057     * @return The pretty-printed instance
058     */
059    String toString( String tabs );
060}