/**
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements. See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership. The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License. You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied. See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */
package org.apache.cxf.jaxrs.ext.search;

import java.util.Collection;
import java.util.List;

//CHECKSTYLE:OFF
/**
 * Can be used to build plain or complex/composite search conditions.
 * <p>
 * Google Collections <a href="http://google-collections.googlecode.com/svn/trunk/javadoc/com/google/common/base/Predicate.html">Predicate</a>
 * might've been used instead, but it is a too generic and its apply method is not quite needed here
 * </p>
 *  
 * @param <T> Type of the object which will be checked by SearchCondition instance
 *  
 */
//CHECKSTYLE:ON
public interface SearchCondition<T> {
    
    /**
     * Checks if the given pojo instance meets this search condition
     * 
     * @param pojo the object which will be checked
     * @return true if the pojo meets this search condition, false - otherwise
     */
    boolean isMet(T pojo);
    
    /**
     * Returns a list of pojos matching the condition
     * @param pojos list of pojos
     * @return list of the matching pojos or null if none have been found
     */
    List<T> findAll(Collection<T> pojos);
    
    /**
     * Some SearchConditions may use instance of T to capture the actual search criteria
     * thus making it simpler to implement isMet(T). In some cases, the code which is given
     * SearchCondition may find it more efficient to directly deal with the captured state
     * for a more efficient lookup of matching data/records as opposed to calling
     * SearchCondition.isMet for every instance of T it knows about.
     * 
     *  
     * @return T the captured search criteria, can be null 
     */
    T getCondition();

    
    /**
     * Primitive statement such a > b, i < 5, etc
     * this condition may represent. Complex conditions will return null.  
     *  
     * @return primitive search statement, can be null 
     */
    PrimitiveStatement getStatement();
    
    /**
     * List of conditions this SearchCondition may represent.
     * Composite SearchConditions will return a list of conditions they are
     * composed from, primitive ones will return null  
     * @return list of conditions, can be null
     */
    List<SearchCondition<T>> getSearchConditions();
    
    /**
     * Returns the type of the condition this SearchCondition represents
     * @return condition type
     */
    ConditionType getConditionType();

    /**
     * Provides a visitor which will convert this SearchCondition into
     * a custom expression, for example, into the SQL statement, etc 
     * @param visitor
     */
    void accept(SearchConditionVisitor<T> visitor);
    
    /**
     * 
     * This method is now deprecated and will be removed soon.
     * 
     * Utility method for converting this condition into an SQL expression
     * @param table table name
     * @param columns column names, a wildcard as in 'SELECT * from table' will be used
     *                if names are not provided 
     * @return SQL expression
     */    
    @Deprecated
    String toSQL(String table, String... columns);
    
    
}
