package listFW;

/**
 * Represents an abstract algorithm to be executed by a host IList.
 * Plays the role of a "visitor" in the design pattern language.
 

 * In non OO programming paradigms, an algorithm on lists is expressed as a
 * function or procedure that takes in a list as parameter.  In particular,
 * our Comp 210 Scheme class prescribes a 'template' for writing functions that
 * operates on lists as follows.

 * (define f (lst)
 *   (cond
 *     [(empty? lst) ...]
 *     [(cons? lst) ...(first lst) ...(f (rest lst)...]))
 *     
 * In our OO formulation, an alogrithm on lists is an interface that has two
 * methods, each takes in a list as a parameter: 

 
One method, called emptyCase, operates specifically on an empty list
    (IEmptyList) and is to be called exclusively by an IEmptyList.
 
The other method, called nonEmptyCase, operates specifically on a
    non-empty list (INEList) and is to be called exclusively by an INEList.
 

 * When we want to perform an alogrithm (IListAlgo) on a list (IList), we asks
 * the IList to 'execute' the algorithm with a given input.  An IEmptyList knows
 * instrinsically that is empty and calls the emptyCase method of the IListAlgo.
 * Analogously, a non-empty list (INEList) will correctly call the nonEmptyCase
 * method of the IListAlgo.
 

 * One need not (and should not) check for the type of a list before applying
 * an algorithm to it.  THERE IS NO cond!
 

 * @author Dung X. Nguyen
 * @author Stephen B. Wong
 * @since Copyright 2002 - DXN, SBW All rights reserved
 */
public interface IListAlgo {
    /**
     * Operates on IEmptyList, the empty list.  Since
     * IEmptyList has only one method, execute(),
     * there is not much the host list can do here.  So the code for the empty
     * case usually involves:

     
inp, and perhaps
     
host.execute(..., ...).

     * This corresponds to the [(empty? lst) ...] part of the
     * (Comp 210) Scheme function template.
     * @param host the IEmptyList that is executing this algorithm.
     * @param inp generic input parameter that can be used for any purpose.
     * @return result from calling this method.  The type of the result is
     * problem-specific and may be null.
     */
    public abstract Object emptyCase(IEmptyList host, Object inp);

    /**
     * Operates on INEList, a non-empty list. The host list now has
     * a first and a rest.  So the code here usually involves what
     * host.getFirst() and host.getRest() can do to
     * accomplish the task at hand.

       
host.getFirst() is simply a data Object
       that the host list holds.  It is problem-specific, and thus what it can
       do depends on the problem the current algorithm is trying to solve.
       
host.getRest() in contrast is an IList!
       What can an IList do? execute an alogrithm
       IListAlgo with some input. What IListAlgo can
       that be? The current algorithm that is being executed is as good a
       candidate as any other IListAlgo. In Java, we use the key
       word this to reference the current receiver of the
       method call.  Having the rest of host (recursively) execute the current
       algorithm is expressed in Java as:
        host.getRest().execute(this, ...).

     * To summarize, the code for the non-empty case usually involves:

       
host.getFirst(), and the recursive call
       
host.getRest().execute(this, something involving inp).

     * This corresponds to the
     * [(cons? lst) ...(first lst) ...(f (rest lst))...]
     * part of the (Comp 210) Scheme function template.

     * @param host the INEList that is executing this algorithm
     * @param inp generic input parameter that can be used for any purpose.
     * @return result from calling this method.  The type of the result is
     * problem-specific and may be null.
     */
    public abstract Object nonEmptyCase(INEList host, Object inp);
}