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 }