/*
 * @(#)StringableFilter.java    1.0  2 February 2001
 *
 * Copyright 2004
 * College of Computer and Information Science
 * Northeastern University
 * Boston, MA  02115
 *
 * The Java Power Tools software may be used for educational
 * purposes as long as this copyright notice is retained intact
 * at the top of all source files.
 *
 * To discuss possible commercial use of this software, 
 * contact Richard Rasala at Northeastern University, 
 * College of Computer and Information Science,
 * 617-373-2462 or rasala@ccs.neu.edu.
 *
 * The Java Power Tools software has been designed and built
 * in collaboration with Viera Proulx and Jeff Raab.
 *
 * Should this software be modified, the words "Modified from 
 * Original" must be included as a comment below this notice.
 *
 * All publication rights are retained.  This software or its 
 * documentation may not be published in any media either
 * in whole or in part without explicit permission.
 *
 * This software was created with support from Northeastern 
 * University and from NSF grant DUE-9950829.
 */

package edu.neu.ccs.filter;

import edu.neu.ccs.*;
import java.text.ParseException;

/**
 * <P>Interface to be implemented by classes of objects 
 * that have the capability of filtering 
 * <CODE>Stringable</CODE> objects that are generated
 * by user input or created internally for computation.
 *
 * This interface defines the specification for filtering
 * <CODE>Stringable</CODE> objects, but does not specify
 * what form of filtering procedure will be applied.</P>
 *
 * <P>A filter should have specific locally defined criteria,
 * inherited criteria, or both.
 *
 * When a <CODE>Stringable</CODE> object is given to a filter,
 * the filter should throw a <CODE>FilterException</CODE>
 * if the object does not meet the filter criteria.
 *
 * If the given object meets the criteria,
 * the filter should apply its procedure
 * and return the resulting object.</P>
 *
 * <P>The intention of the signature for the single method
 * in this specification is that a new object
 * should be returned by the filter
 * if the filter procedure desires to change the state
 * of the given object;
 * A filter should not change the state of a mutable object
 * unless it is absolutely necessary to do so
 * and is documented in the class definition
 * for the filter.
 *
 * If the filter does not change the state
 * of the given object, it is acceptable to return
 * the same object instance given to the filter.</P>
 *
 * @author  Jeff Raab
 * @version 2.2
 * @since   1.0
 */
public interface StringableFilter {

    /**
     * Filters the given object.
     *
     * @param obj the object to be filtered
     * @throws FilterException if the object does not meet the
     *      criteria for the filter, or cannot be filtered
     */
    public Stringable filterStringable(Stringable obj) 
        throws FilterException;
}