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     */
020    package org.apache.directory.server.xdbm.search;
021    
022    
023    import org.apache.directory.shared.ldap.filter.ExprNode;
024    import org.apache.directory.server.xdbm.IndexEntry;
025    
026    
027    /**
028     * Evaluates candidate entries to see if they match a filter expression.
029     *
030     * Evaluators contain various overloads to the evaluate method.  Often a
031     * developer working in this region of the code may wonder when to use one
032     * override verses another.  The overload taking an IndexEntry argument is
033     * specifically suited for use when there is the possibility of multiple entry
034     * lookups from the master table.  If the same candidate in the form of an
035     * IndexEntry is evaluated more then this overload is more efficient since it
036     * stores the looked up entry in the IndexEntry preventing multiple lookups.
037     *
038     * If the index entry is already populated with an entry object, and some
039     * evaluation is required then it is preferrable to use the overload that
040     * takes a Long id instead.  Likewise if it is known in advance that the
041     * expression is a leaf node built on an indexed attribute then the overload
042     * with the Long id argument is also preferrable unless an IndexEntry already
043     * exists in which case it makes no difference.
044     *
045     * The overload taking the ServerEntry itself is a last resort option and ok
046     * to use when it is known that no index exists for the attributes of
047     * Evaluators based on leaf expressions.
048     * 
049     * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
050     * @version $Rev: 917312 $
051     */
052    public interface Evaluator<N extends ExprNode, E, ID>
053    {
054        /**
055         * Evaluates a candidate to determine if a filter expression selects it.
056         * If an IndexEntry does has a null reference to the entry object, this
057         * Evaluator may set it if it has to access the full entry within the
058         * master table of the store.  Subsequent evaluations on the IndexEntry
059         * then need not access the store to retreive the entry if they need to
060         * access it's attributes.
061         * 
062         * @param entry the index record of the entry to evaluate
063         * @return true if filter selects the candidate false otherwise
064         * @throws Exception if there are faults during evaluation
065         */
066        boolean evaluate( IndexEntry<?, E, ID> entry ) throws Exception;
067    
068    
069        /**
070         * Evaluates whether or not a candidate, specified by an id, satisfies the
071         * expression associated with this Evaluator .
072         *
073         * @param id the identifier for the candidate entry
074         * @return true if filter selects the candidate false otherwise
075         * @throws Exception if there are faults during evaluation
076         */
077        boolean evaluateId( ID id ) throws Exception;
078    
079    
080        /**
081         * Evaluates whether or not a candidate, satisfies the expression
082         * associated with this Evaluator .
083         *
084         * @param entry the candidate entry
085         * @return true if filter selects the candidate false otherwise
086         * @throws Exception if there are faults during evaluation
087         */
088        boolean evaluateEntry( E entry ) throws Exception;
089    
090    
091        /**
092         * Gets the expression used by this expression Evaluator.
093         *
094         * @return the AST for the expression
095         */
096        N getExpression();
097    }