package com.onaro.util.jfc.tables.filter;

import com.onaro.util.jfc.tables.filter.matcher.*;

/**
 * Used by {@link com.onaro.util.jfc.tables.FilterTable} to maintain the "filter by" expression and to actually
 * decide if a value should be displayed or not.<p>
 * A filter can be set to be "active" or "inactive", where only active filters are being used by the  {@link com.onaro.util.jfc.tables.FilterTable}
 * to determine if a row should be displayed. As a rule, a filter should be "active" if a "filter by" expression is set
 * regardless if it's valid or not. This state is used to provide proper indication to the user that there is a filter
 * set for some column.
 */
public interface Filter extends FilterMatcher, Cloneable {
    /**
     * Sets the expression to "filter by". The actual syntax of the expression depends on the filter implementation.
     * @param pattern the "filter by" expression
     */
    public void setPattern(Object pattern);

    /**
     * Gets the "filter by" expression.
     * @return the "filter by" expression, <code>null</code> represents "no filter/pattern"
     */
    public Object getPattern();
    
    /**
     * Return a string representation of the given pattern, for display in a tooltip
     * @param pattern the pattern to format
     * @return the formatted representation
     */
    public String formatPatternForTooltip(Object pattern);

    /**
     * Returns usage text to be used for tooltips when the filter's editor it active/open.
     * 
     * @return usage text to be used for tooltips when the filter's editor it active/open. 
     */
    public String getUsageTooltip();
    
    /**
     * Tells if the syntax of the "filter by" expression is valid.
     * @return true if the "filter by" expression is valid
     */
    public boolean isValid();

    /**
     * Tells if this filter is active. As a rule, a filter should be active if there is a non empty "filter by" expression
     * set.
     * @return true if the filter is active
     */
    public boolean isActive();
    
    /**
     * Ensure that the Filter implementations are cloneable
     * @return clone of the filter instance
     */
    public Filter clone();
}