How to use org.apache.commons.collections.functors

/**
 * Factory to create the predicate.
 *
 * @param predicates  the predicates to check, cloned, not null
 * @return the <code>one</code> predicate
 * @throws IllegalArgumentException if the predicates array is null
 * @throws IllegalArgumentException if any predicate in the array is null
 */
public static Predicate getInstance(Collection predicates) {
  Predicate[] preds = FunctorUtils.validate(predicates);
  return new OnePredicate(preds);
}

/**
 * Creates a Predicate that checks if the input object is equal to the
 * specified object by identity.
 * 
 * @see org.apache.commons.collections.functors.IdentityPredicate
 * 
 * @param value  the value to compare against
 * @return the predicate
 */
public static Predicate identityPredicate(Object value) {
  return IdentityPredicate.getInstance(value);
}

/**
 * Creates a Transformer that will return the same object each time the 
 * transformer is used.
 *
 * @see org.apache.commons.collections.functors.ConstantTransformer
 * 
 * @param constantToReturn  the constant object to return each time in the transformer
 * @return the transformer.
 */
public static Transformer constantTransformer(Object constantToReturn) {
  return ConstantTransformer.getInstance(constantToReturn);
}

/**
 * Transformer method that performs validation.
 *
 * @param constantToReturn  the constant object to return each time in the factory
 * @return the <code>constant</code> factory.
 */
public static Transformer getInstance(Object constantToReturn) {
  if (constantToReturn == null) {
    return NULL_INSTANCE;
  }
  return new ConstantTransformer(constantToReturn);
}

/**
 * Factory to create the identity predicate.
 * 
 * @param object  the object to compare to
 * @return the predicate
 * @throws IllegalArgumentException if the predicate is null
 */
public static Predicate getInstance(Object object) {
  if (object == null) {
    return NullPredicate.INSTANCE;
  }
  return new EqualPredicate(object);
}

/**
 * Create a new Predicate that returns true if the specified predicate
 * returns false and vice versa.
 * 
 * @see org.apache.commons.collections.functors.NotPredicate
 * 
 * @param predicate  the predicate to not
 * @return the <code>not</code> predicate
 * @throws IllegalArgumentException if the predicate is null
 */
public static Predicate notPredicate(Predicate predicate) {
  return NotPredicate.getInstance(predicate);
}

/**
 * Factory to create the predicate.
 * 
 * @return the predicate
 * @throws IllegalArgumentException if the predicate is null
 */
public static Predicate getInstance() {
  return new UniquePredicate();
}

/**
 * Create a new Predicate that returns true if either of the specified
 * predicates are true.
 * 
 * @see org.apache.commons.collections.functors.OrPredicate
 * 
 * @param predicate1  the first predicate, may not be null
 * @param predicate2  the second predicate, may not be null
 * @return the <code>or</code> predicate
 * @throws IllegalArgumentException if either predicate is null
 */
public static Predicate orPredicate(Predicate predicate1, Predicate predicate2) {
  return OrPredicate.getInstance(predicate1, predicate2);
}

/**
 * Factory method that performs validation.
 *
 * @param constantToReturn  the constant object to return each time in the factory
 * @return the <code>constant</code> factory.
 */
public static Factory getInstance(Object constantToReturn) {
  if (constantToReturn == null) {
    return NULL_INSTANCE;
  }
  return new ConstantFactory(constantToReturn);
}

/**
 * Creates a Predicate that checks if the input object is equal to the
 * specified object using equals().
 * 
 * @see org.apache.commons.collections.functors.EqualPredicate
 * 
 * @param value  the value to compare against
 * @return the predicate
 */
public static Predicate equalPredicate(Object value) {
  return EqualPredicate.getInstance(value);
}

/**
 *  Constructs a new <code>UniqueFilterIterator</code>.
 *
 *  @param iterator  the iterator to use
 */
public UniqueFilterIterator( Iterator iterator ) {
  super(iterator, UniquePredicate.getInstance());
}

/**
 * Creates a Transformer that calls a Factory each time the transformer is used.
 * The transformer will return the value returned by the factory.
 *
 * @see org.apache.commons.collections.functors.FactoryTransformer
 * 
 * @param factory  the factory to run each time in the transformer, not null
 * @return the transformer
 * @throws IllegalArgumentException if the factory is null
 */
public static Transformer asTransformer(Factory factory) {
  return FactoryTransformer.getInstance(factory);
}

/**
 * Creates a Factory that can create objects of a specific type using
 * a no-args constructor.
 *
 * @see org.apache.commons.collections.functors.InstantiateFactory
 * 
 * @param classToInstantiate  the Class to instantiate each time in the factory
 * @return the <code>reflection</code> factory
 * @throws IllegalArgumentException if the classToInstantiate is null
 */
public static Factory instantiateFactory(Class classToInstantiate) {
  return InstantiateFactory.getInstance(classToInstantiate, null, null);
}

/**
 * Creates a Transformer that calls a Predicate each time the transformer is used.
 * The transformer will return either Boolean.TRUE or Boolean.FALSE.
 *
 * @see org.apache.commons.collections.functors.PredicateTransformer
 * 
 * @param predicate  the predicate to run each time in the transformer, not null
 * @return the transformer
 * @throws IllegalArgumentException if the predicate is null
 */
public static Transformer asTransformer(Predicate predicate) {
  return PredicateTransformer.getInstance(predicate);
}

/**
 * Creates a Closure that will call the closure once and then repeatedly
 * until the predicate returns false.
 *
 * @see org.apache.commons.collections.functors.WhileClosure
 * 
 * @param closure  the closure to call repeatedly, not null
 * @param predicate  the predicate to use as an end of loop test, not null
 * @return the <code>do-while</code> closure
 * @throws IllegalArgumentException if either argument is null
 */
public static Closure doWhileClosure(Closure closure, Predicate predicate) {
  return WhileClosure.getInstance(predicate, closure, true);
}

/**
 * Create a new Transformer that calls two transformers, passing the result of
 * the first into the second.
 * 
 * @see org.apache.commons.collections.functors.ChainedTransformer
 * 
 * @param transformer1  the first transformer
 * @param transformer2  the second transformer
 * @return the transformer
 * @throws IllegalArgumentException if either transformer is null
 */
public static Transformer chainedTransformer(Transformer transformer1, Transformer transformer2) {
  return ChainedTransformer.getInstance(transformer1, transformer2);
}

/**
 * Factory method that performs validation.
 * <p>
 * A null transformer will return the <code>NOPClosure</code>.
 * 
 * @param transformer  the transformer to call, null means nop
 * @return the <code>transformer</code> closure
 */
public static Closure getInstance(Transformer transformer) {
  if (transformer == null) {
    return NOPClosure.INSTANCE;
  }
  return new TransformerClosure(transformer);
}

/**
 * Gets a Predicate that returns false if the input object is null, otherwise
 * it calls the specified Predicate. This allows null handling behaviour to
 * be added to Predicates that don't support nulls.
 * 
 * @see org.apache.commons.collections.functors.NullIsFalsePredicate
 * 
 * @param predicate  the predicate to wrap, may not be null
 * @return the predicate
 * @throws IllegalArgumentException if the predicate is null.
 */
public static Predicate nullIsFalsePredicate(Predicate predicate){
  return NullIsFalsePredicate.getInstance(predicate);
}

public static Test suite() {
  TestSuite suite = new TestSuite();
  suite.addTest(TestCloneTransformer.suite());
  suite.addTest(TestForClosure.suite());
  suite.addTest(TestInstantiateTransformer.suite());
  suite.addTest(TestInstantiateFactory.suite());
  suite.addTest(TestInvokerTransformer.suite());
  suite.addTest(TestPrototypeFactory.suite());
  suite.addTest(TestWhileClosure.suite());
  return suite;
}
  

/**
 * Factory to create the predicate.
 *
 * @param predicates  the predicates to check, cloned, not null
 * @return the <code>one</code> predicate
 * @throws IllegalArgumentException if the predicates array is null
 * @throws IllegalArgumentException if any predicate in the array is null
 */
public static Predicate getInstance(Collection predicates) {
  Predicate[] preds = FunctorUtils.validate(predicates);
  return new OnePredicate(preds);
}