/*
    *  Copyright 2002-2004 The Apache Software Foundation
    *
    *  Licensed 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 net.sf.collections15.functors.closure;
  
  import net.sf.collections15.Closure;
  import net.sf.collections15.Predicate;
  import net.sf.collections15.Transformer;
  import net.sf.collections15.functors.transformer.InvokerTransformer;
  
  import java.util.ArrayList;
  import java.util.Collection;
  import java.util.Map;
  
  /***
   * <code>ClosureUtils</code> provides reference implementations and utilities
   * for the <code>Closure</code> functor interface. The supplied
   * <code>Closures</code> are: <ul> <li>Invoker - invokes a method on the input
   * object.</li> <li>If - conditionally executes a <code>Closure</code> if a
   * <code>Predicate</code> holds <code>true</code>.</li> <li>IfElse -
   * conditionally executes one of two <code>Closure</code>s depending on the
   * outcome of a <code>Predicate</code>.</li> <li>For - repeatedly calls a
   * <code>Closure</code> for a fixed number of times.</li> <li>While - repeatedly
   * calls a <code>Closure</code> while a </code>Predicate</code> holds
   * <code>true</code>.</li> <li>DoWhile - repeatedly calls a <code>Closure</code>
   * while a <code>Predicate</code> holds <code>true</code>/</li> <li>Chained -
   * chains two or more <code>Closures</code> together.</li> <li>Switch - calls
   * one <code>Closure</code> based on one or more <code>Predicates</code>.</li>
   * <li>SwitchMap - calls one <code>Closure</code> looked up from a map.</li>
   * <li>Transformer - wraps a <code>Transformer</code> as a
   * <code>Closure</code>.</li> <li>NOP - does nothing.</li> <li>Exception -
   * always throws an exception.</li> </ul> All the supplied <code>Closures</code>
   * are <code>Serializable</code>.
   *
   * @author Stephen Colebourne
   * @author Chris Lambrou (port to Java 5.0)
   * @since Collections15 1.0
   */
  public class ClosureUtils
  {
  
      /***
       * Protected constructor prevents direct instantiation, but allows users to
       * extend this library to provide their own augmented static library class.
       */
      protected ClosureUtils()
      {
      }
  
      /***
       * Gets a <code>Closure</code> that always throws an exception. This could
       * be useful during testing as a placeholder.
       *
       * @return A <code>Closure</code> whose {@link Closure#execute execute}
       *         method always throws an exception.
       * @see ExceptionClosure
       */
      public static <T> Closure<T> exceptionClosure()
      {
          return ExceptionClosure.getInstance();
      }
  
      /***
       * Gets a <code>Closure</code> that will do nothing. This could be useful
       * during testing as a placeholder.
       *
       * @return A <code>Closure</code> whose {@link Closure#execute execute}
       *         method does nothing.
       * @see NOPClosure
       */
      public static <T> Closure<T> nopClosure()
      {
          return NOPClosure.getInstance();
      }
  
      /***
       * Creates a <code>Closure</code> that wraps a <code>Transformer</code>,
       * invoking its {@link Transformer#transform transform} method each time it
       * is executed. The <code>Transformer</code>'s output value is ignored.
       *
       * @param transformer The <code>Transformer</code> to wrap.
       * @return A <code>Closure</code> whose {@link Closure#execute execute}
       *         method invokes the {@link Transformer#transform transform} method
       *         of the wrapped <codeTransformer</code>, ignoring the output of
       *         the transform.
       * @throws IllegalArgumentException Thrown if the specified <code>Transformer</code>
       *                                  is <code>null</code>.
      * @see TransformerClosure
      */
     public static <T> Closure<T> asClosure(Transformer<? super T, ?> transformer)
     {
         return TransformerClosure.getInstance(transformer);
     }
 
     /***
      * Creates a decorator for an existing <code>Closure</code> that executes
      * the specified <code>Closure</code> the specified number of times.
      *
      * @param count   The number of times to execute the decorated
      *                <code>Closure</code>.
      * @param closure The <code>Closure</code> to execute.
      * @return A <code>Closure</code> whose {@link Closure#execute execute}
      *         method executes the <code>Closure</code> the specified number of
      *         times.
      * @throws IllegalArgumentException Thrown if <code>count</code> &lt; 0.
      * @throws IllegalArgumentException Thrown if <code>closure</code> is
      *                                  <code>null</code>.
      * @see ForClosure
      */
     public static <T> Closure<T> forClosure(int count, Closure<? super T> closure)
     {
         if (count < 0) {
             throw new IllegalArgumentException("negative count specified");
         }
         if (closure == null) {
             throw new IllegalArgumentException("null closure");
         }
         switch (count) {
             case 0:
                 return NOPClosure.getInstance();
             case 1:
                 return (Closure<T>) closure;
             default:
                 return ForClosure.decorate(count, closure);
         }
     }
 
     /***
      * Returns a <code>Closure</code> instance that decorates the specified
      * <code>Closure</code> using the specified <code>Predicate</code> condition
      * to effect a <code>while</code> loop. The <code>Predicate</code> is
      * evaluated at the start of the loop, and if it holds <code>false</code>
      * the loop is terminated.
      *
      * @param predicate The <code>Predicate</code> used to determine when the
      *                  loop should terminate.
      * @param closure   The <code>Closure</code> executed in the loop.
      * @return A <code>Closure</code> whose {@link Closure#execute execute}
      *         method repeatedly executes the specified <code>Closure</code> as
      *         long as the <code>Predicate</code> holds <code>true</code>.
      * @throws IllegalArgumentException Thrown if the <code>Predicate</code> or
      *                                  <code>Closure</code> is <code>null</code>.
      * @see WhileClosure
      */
     public static <T> Closure<T> whileClosure(Predicate<? super T> predicate, Closure<? super T> closure)
     {
         return WhileClosure.<T>decorate(predicate, closure, false);
     }
 
     /***
      * Returns a <code>Closure</code> instance that decorates the specified
      * <code>Closure</code> using the specified <code>Predicate</code> condition
      * to effect a <code>while</code> loop. The <code>Predicate</code> is
      * evaluated at the end of the loop, and if it holds <code>false</code> the
      * loop is terminated. This guarantees that the decorated
      * <code>Closure</code> is executed at least once.
      *
      * @param predicate The <code>Predicate</code> used to determine when the
      *                  loop should terminate.
      * @param closure   The <code>Closure</code> executed in the loop.
      * @return A <code>Closure</code> whose {@link Closure#execute execute}
      *         method repeatedly executes the specified <code>Closure</code>
      *         until the <code>Predicate</code> holds <code>false</code>.
      * @throws IllegalArgumentException Thrown if the <code>Predicate</code> or
      *                                  <code>Closure</code> is <code>null</code>.
      * @see WhileClosure
      */
     public static <T> Closure<T> doWhileClosure(Predicate<? super T> predicate, Closure<? super T> closure)
     {
         return WhileClosure.<T>decorate(predicate, closure, true);
     }
 
 
     /***
      * Creates a <code>Closure</code> that will invoke a specified method on the
      * <code>Closure</code>'s input object by reflection.
      *
      * @param methodName The name of the method to execute on the target
      *                   object.
      * @return A <code>Closure</code> whose {@link Closure#execute execute}
      *         method invokes the named method on the input object.
      * @throws IllegalArgumentException Thrown if the method name is null.
      * @see InvokerTransformer
      * @see TransformerClosure
      */
     public static <T> Closure<T> invokerClosure(String methodName)
     {
         // reuse transformer as it has caching - this is lazy really, should have inner class here
         Transformer<T, ?> transformer = InvokerTransformer.getInstance(methodName);
         return asClosure(transformer);
     }
 
     /***
      * Creates a <code>Closure</code> that will invoke a specified method on the
      * <code>Closure</code>'s input object by reflection, with the specified
      * arguments.
      *
      * @param methodName The name of the method to execute on the target
      *                   object.
      * @param paramTypes The parameter types of the invoked method.
      * @param args       The arguments passed to the invoked method.
      * @return A <code>Closure</code> whose {@link Closure#execute execute}
      *         method invokes the named method on the input object.
      * @throws IllegalArgumentException Thrown if the method name is null.
      * @throws IllegalArgumentException Thrown if parameter types and argument
      *                                  arrays are <code>null</code>, or do not
      *                                  otherwise match.
      * @see InvokerTransformer
      * @see TransformerClosure
      */
     public static <T> Closure<T> invokerClosure(String methodName, Class[] paramTypes, Object[] args)
     {
         // reuse transformer as it has caching - this is lazy really, should have inner class here
         Transformer<T, ?> transformer = InvokerTransformer.getInstance(methodName, paramTypes, args);
         return asClosure(transformer);
     }
 
     /***
      * Create a new <code>Closure</code> that decorates a collection of existing
      * <code>Closure</code>s. Each <code>Closure</code> is executed in turn on
      * an input object, in the order that the <code>Closure</code>s are returned
      * by the collection's iterator.
      *
      * @param closures A collection of <code>Closure</code>s to chain.
      * @return A <code>Closure</code> whose {@link Closure#execute execute}
      *         method executes each of the decorated <code>Closure</code>s in
      *         turn.
      * @throws IllegalArgumentException Thrown if the collection of
      *                                  <code>Closure</code>s is <code>null</code>
      *                                  or contains any <code>null</code>
      *                                  elements.
      * @see ChainedClosure
      */
     public static <T> Closure<T> chainedClosure(Collection<Closure<? super T>> closures)
     {
         if (closures == null) {
             throw new IllegalArgumentException("null closures collection");
         }
         switch (closures.size()) {
             case 0:
                 return NOPClosure.getInstance();
             case 1:
                 Closure<T> closure = (Closure<T>) closures.iterator().next();
                 if (closure == null) {
                     throw new IllegalArgumentException("null closure in specified collection");
                 }
                 return closure;
             default:
                 return ChainedClosure.getInstance(closures);
         }
     }
 
     /***
      * Create a new <code>Closure</code> that decorates a collection of existing
      * <code>Closure</code>s. Each <code>Closure</code> is executed in turn on
      * an input object, in the order that the <code>Closure</code>s are returned
      * by the collection's iterator.
      *
      * @param firstClosure  The first <code>Closure</code> in the chain.
      * @param secondClosure The second <code>Closure</code> in the chain.
      * @return A <code>Closure</code> whose {@link Closure#execute execute}
      *         method executes each of the decorated <code>Closure</code>s in
      *         turn.
      * @throws IllegalArgumentException Thrown if either <code>Closure</code>
      *                                  argument is <code>null</code>.
      * @see ChainedClosure
      */
     public static <T> Closure<T> chainedClosure(Closure<? super T> firstClosure, Closure<? super T> secondClosure)
     {
         if (firstClosure == null) {
             throw new IllegalArgumentException("null firstClosure not allowed");
         }
         if (secondClosure == null) {
             throw new IllegalArgumentException("null secondClosure not allowed");
         }
         Collection<Closure<? super T>> closures = new ArrayList<Closure<? super T>>(2);
         closures.add(firstClosure);
         closures.add(secondClosure);
         return ChainedClosure.getInstance(closures);
     }
 
     /***
      * Decorates an existing <code>Closure</code>, only executing it if a
      * specified <code>Predicate</code> holds <code>true</code>.
      *
      * @param predicate   The condition upon which execution of the
      *                    <code>Closure</code> is dependent.
      * @param trueClosure The <code>Closure</code> executed if the
      *                    <code>Predicate</code> holds <code>true</code>.
      * @return A <code>Closure</code> whose {@link Closure#execute execute}
      *         method only executes the decorated <code>Closure</code> if the
      *         <code>Predicate</code> evaluates to <code>true</code>.
      * @throws IllegalArgumentException Thrown if either argument is
      *                                  <code>null</code>.
      * @see IfClosure
      */
     public static <T> Closure<T> ifClosure(Predicate<? super T> predicate, Closure<? super T> trueClosure)
     {
         return IfClosure.<T>decorate(predicate, trueClosure);
     }
 
     /***
      * Creates a <code>Closure</code> executes one of two existing
      * <code>Closure</code>s depending upon the outcome of a specified
      * <code>Predicate</code>.
      *
      * @param predicate    The condition used to determine which
      *                     <code>Closure</code> is executed.
      * @param trueClosure  The <code>Closure</code> executed if the
      *                     <code>Predicate</code> holds <code>true</code>.
      * @param falseClosure The <code>Closure</code> executed if the
      *                     <code>Predicate</code> holds <code>false</code>.
      * @return A <code>Closure</code> whose {@link Closure#execute execute}
      *         method executes the <code>trueClosure</code> if the
      *         <code>Predicate</code> evaluates to <code>true</code>, or the
      *         <code>falseClosure</code> if the <code>Predicate</code> evaluates
      *         to <code>false</code>.
      * @throws IllegalArgumentException Thrown if any argument is <code>null</code>.
      * @see IfClosure
      */
     public static <T> Closure<T> ifElseClosure(Predicate<? super T> predicate,
                                                Closure<? super T> trueClosure, Closure<? super T> falseClosure)
     {
         return IfElseClosure.<T>getInstance(predicate, trueClosure, falseClosure);
     }
 
     /***
      * Create a new <code>Closure</code> that calls one of a number of
      * <code>Closures</code> in a map depending on whether or not the input
      * object satisfies any of the <code>Predicates</code> in the map.
      * <p/>
      * The map consists of <code>Predicate</code> keys and <code>Closure</code>
      * values. A <code>Closure</code> is executed on the input object if the
      * input matches its corresponding <code>Predicate</code>. A default
      * <code>Closure</code> can be specified in the map with a <code>null</code>
      * key, and is executed on an input object if it doesn't satisfy any of the
      * other non-null <code>Predicate</code> keys.
      *
      * @param predicatesAndClosures A map of <code>Predicate</code>s to
      *                              <code>Closure</code>s. An input object is
      *                              evaluated against the non-null
      *                              <code>Predicate</code> keys, in the order
      *                              defined by the entry set's iterator. For the
      *                              first <code>Predicate</code> to evaluate to
      *                              <code>true</code> against the key, the
      *                              corresponding <code>Closure</code> is
      *                              executed.
      *                              <p/>
      *                              If none of the non-null <code>Predicate</code>s
      *                              evaluates to <code>true</code>, and a
      *                              default <code>Closure</code> is defined, it
      *                              is executed against the key, othersize an
      *                              <code>IllegalArgumentException</code> will
      *                              be thrown.
      * @return The <code>switch</code> closure based on the contents of the
      *         specified map.
      * @throws IllegalArgumentException If the map is <code>null</code>.
      * @throws IllegalArgumentException If any <code>Closure</code> in the map
      *                                  is <code>null</code>.
      */
     public static <T> Closure<T> switchClosure(Map<Predicate<? super T>, Closure<? super T>> predicatesAndClosures)
     {
         if (predicatesAndClosures == null) {
             throw new IllegalArgumentException("null predicatesAndClosures not allowed");
         }
         if (predicatesAndClosures.size() == 0) {
             return NOPClosure.getInstance();
         }
         return SwitchClosure.<T>getInstance(predicatesAndClosures);
     }
 
     /***
      * Create a new <code>Closure</code> that calls one of a number of
      * <code>Closures</code> in a map depending on which key in the map matches
      * the input object.
      * <p/>
      * The map consists of <code>Object</code> keys and <code>Closure</code>
      * values. If the input object is mapped to a <code>Closure</code>, that
      * <code>Closure</code> is executed on the input object. If there is no matching
      * <code>Closure</code> present in the map, a
      * {@link net.sf.collections15.functors.FunctorException FunctorException} is thrown.
      *
      * @param objectsAndClosures A map of <code>Objects</code>s to
      *                           <code>Closure</code>s. If an input object is
      *                           mapped to a <code>Closure</code> in the map,
      *                           that <code>Closure</code> is executed.
      * @return The <code>switch</code> closure based on the contents of the
      *         specified map.
      * @throws IllegalArgumentException If the map is <code>null</code>.
      * @throws IllegalArgumentException If any <code>Closure</code> in the map
      *                                  is <code>null</code>.
      */
     public static <T> Closure<T> switchMapClosure(Map<T, Closure<? super T>> objectsAndClosures)
     {
         return SwitchMapClosure.<T>getInstance(objectsAndClosures);
     }
 
     /***
      * Create a new <code>Closure</code> that calls one of a number of
      * <code>Closures</code> in a map depending on which key in the map matches
      * the input object.
      * <p/>
      * The map consists of <code>Object</code> keys and <code>Closure</code>
      * values. If the input object is mapped to a <code>Closure</code>, that
      * <code>Closure</code> is executed on the input object. If the input object
      * doesn't map to any <code>Closure</code>, the specified <code>defaultClosure</code>
      * is executed.
      *
      * @param objectsAndClosures A map of <code>Objects</code>s to
      *                           <code>Closure</code>s. If an input object is
      *                           mapped to a <code>Closure</code> in the map,
      *                           that <code>Closure</code> is executed.
      * @param defaultClosure If an input object doesn't map to any of the <code>Closure</code>s
      * defined in <code>objectsAndClosures</code>, then this <code>Closure</code> is executed.
      * @return The <code>switch</code> closure based on the contents of the
      *         specified map.
      * @throws IllegalArgumentException If either argument is <code>null</code>.
      * @throws IllegalArgumentException If any <code>Closure</code> in the map
      *                                  is <code>null</code>.
      */
     public static <T> Closure<T> switchMapClosure(Map<T, Closure<? super T>> objectsAndClosures, Closure<? super T> defaultClosure)
     {
         return SwitchMapClosure.<T>getInstance(objectsAndClosures, defaultClosure);
     }
 }