001    package edu.nrao.sss.util;
002    
003    //import java.util.Collection;
004    
005    /**
006     * A filter that either blocks a particle or allows it to pass through.
007     * This filter merely blocks or allows passage -- it is not a
008     * transformer.  The particles to which the filter is applied remain
009     * unchanged by their passage.
010     * <p>
011     * <b>Version Info:</b>
012     * <table style="margin-left:2em">
013     *   <tr><td>$Revision: 696 $</td></tr>
014     *   <tr><td>$Date: 2007-06-06 17:27:00 -0600 (Wed, 06 Jun 2007) $</td></tr>
015     *   <tr><td>$Author: dharland $ (last person to modify)</td></tr>
016     * </table></p>
017     * 
018     * @author David M. Harland
019     * @since 2006-12-20
020     */
021    public interface Filter<T>
022    {
023      /**
024       * Returns <i>true</i> if this filter allows {@code particle}
025       * to pass through.
026       * @param particle an object attempting to pass through this filter.
027       * @return <i>true</i> if this filter passes {@code particle}.
028       */
029      public boolean allows(T particle);
030      
031      /**
032       * Returns <i>true</i> if this filter blocks {@code particle}
033       * from passing through.
034       * @param particle an object attempting to pass through this filter.
035       * @return <i>true</i> if this filter blocks {@code particle}.
036       */
037      public boolean blocks(T particle);
038      
039      /**
040       * Modifies {@code flow} so that only those particles
041       * that pass through this filter remain in the flow.
042       * 
043       * @param flow a collection of particles upon which this filter operates.
044       */
045      //TODO add this method once all implementing classes have it
046      //public Collection<? extends T> 
047      //  removeAllBlockedParticlesFrom(Collection<? extends T> flow);
048    }