/*
 *  Licensed to the Apache Software Foundation (ASF) under one or more
 *  contributor license agreements.  See the NOTICE file distributed with
 *  this work for additional information regarding copyright ownership.
 *  The ASF licenses this file to You 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 org.apache.commons.collections;

import org.apache.commons.collections.functors.ConstantFactory;
import org.apache.commons.collections.functors.InstantiateFactory;
import org.apache.commons.collections.functors.ExceptionFactory;
import org.apache.commons.collections.functors.PrototypeFactory;

FactoryUtils provides reference implementations and utilities
for the Factory functor interface. The supplied factories are:

Prototype - clones a specified object
Reflection - creates objects using reflection
Constant - always returns the same object
Null - always returns null
Exception - always throws an exception

All the supplied factories are Serializable.
Author:
Stephen Colebourne
Since:
Commons Collections 3.0
Version:
$Revision: 646777 $ $Date: 2008-04-10 14:33:15 +0200 (Thu, 10 Apr 2008) $/**
 * <code>FactoryUtils</code> provides reference implementations and utilities
 * for the Factory functor interface. The supplied factories are:
 * <ul>
 * <li>Prototype - clones a specified object
 * <li>Reflection - creates objects using reflection
 * <li>Constant - always returns the same object
 * <li>Null - always returns null
 * <li>Exception - always throws an exception
 * </ul>
 * All the supplied factories are Serializable.
 * 
 * @since Commons Collections 3.0
 * @version $Revision: 646777 $ $Date: 2008-04-10 14:33:15 +0200 (Thu, 10 Apr 2008) $
 *
 * @author Stephen Colebourne
 */
public class FactoryUtils {

    
This class is not normally instantiated.
/**
     * This class is not normally instantiated.
     */
    public FactoryUtils() {
        super();
    }

    
Gets a Factory that always throws an exception.
This could be useful during testing as a placeholder.
See Also:
ExceptionFactory
Returns:
the factory/**
     * Gets a Factory that always throws an exception.
     * This could be useful during testing as a placeholder.
     *
     * @see org.apache.commons.collections.functors.ExceptionFactory
     * 
     * @return the factory
     */
    public static Factory exceptionFactory() {
        return ExceptionFactory.INSTANCE;
    }

    
Gets a Factory that will return null each time the factory is used.
This could be useful during testing as a placeholder.
See Also:
ConstantFactory
Returns:
the factory/**
     * Gets a Factory that will return null each time the factory is used.
     * This could be useful during testing as a placeholder.
     *
     * @see org.apache.commons.collections.functors.ConstantFactory
     * 
     * @return the factory
     */
    public static Factory nullFactory() {
        return ConstantFactory.NULL_INSTANCE;
    }

    
Creates a Factory that will return the same object each time the factory
is used. No check is made that the object is immutable. In general, only
immutable objects should use the constant factory. Mutable objects should
use the prototype factory.
Params:
constantToReturn –  the constant object to return each time in the factory
See Also:
ConstantFactory
Returns:
the constant factory./**
     * Creates a Factory that will return the same object each time the factory
     * is used. No check is made that the object is immutable. In general, only
     * immutable objects should use the constant factory. Mutable objects should
     * use the prototype factory.
     *
     * @see org.apache.commons.collections.functors.ConstantFactory
     * 
     * @param constantToReturn  the constant object to return each time in the factory
     * @return the <code>constant</code> factory.
     */
    public static Factory constantFactory(Object constantToReturn) {
        return ConstantFactory.getInstance(constantToReturn);
    }

    
Creates a Factory that will return a clone of the same prototype object
each time the factory is used. The prototype will be cloned using one of these
techniques (in order):

public clone method
public copy constructor
serialization clone

Params:
prototype –  the object to clone each time in the factory
Throws:
IllegalArgumentException – if the prototype is null
IllegalArgumentException – if the prototype cannot be cloned
See Also:
PrototypeFactory
Returns:
the prototype factory/**
     * Creates a Factory that will return a clone of the same prototype object
     * each time the factory is used. The prototype will be cloned using one of these
     * techniques (in order):
     * <ul>
     * <li>public clone method
     * <li>public copy constructor
     * <li>serialization clone
     * <ul>
     *
     * @see org.apache.commons.collections.functors.PrototypeFactory
     * 
     * @param prototype  the object to clone each time in the factory
     * @return the <code>prototype</code> factory
     * @throws IllegalArgumentException if the prototype is null
     * @throws IllegalArgumentException if the prototype cannot be cloned
     */
    public static Factory prototypeFactory(Object prototype) {
        return PrototypeFactory.getInstance(prototype);
    }

    
Creates a Factory that can create objects of a specific type using
a no-args constructor.
Params:
classToInstantiate –  the Class to instantiate each time in the factory
Throws:
IllegalArgumentException – if the classToInstantiate is null
See Also:
InstantiateFactory
Returns:
the reflection 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 Factory that can create objects of a specific type using
the arguments specified to this method.
Params:
classToInstantiate –  the Class to instantiate each time in the factory
paramTypes –  parameter types for the constructor, can be null
args –  the arguments to pass to the constructor, can be null
Throws:
IllegalArgumentException – if the classToInstantiate is null
IllegalArgumentException – if the paramTypes and args don't match
IllegalArgumentException – if the constructor doesn't exist
See Also:
InstantiateFactory
Returns:
the reflection factory/**
     * Creates a Factory that can create objects of a specific type using
     * the arguments specified to this method.
     *
     * @see org.apache.commons.collections.functors.InstantiateFactory
     * 
     * @param classToInstantiate  the Class to instantiate each time in the factory
     * @param paramTypes  parameter types for the constructor, can be null
     * @param args  the arguments to pass to the constructor, can be null
     * @return the <code>reflection</code> factory
     * @throws IllegalArgumentException if the classToInstantiate is null
     * @throws IllegalArgumentException if the paramTypes and args don't match
     * @throws IllegalArgumentException if the constructor doesn't exist
     */
    public static Factory instantiateFactory(Class classToInstantiate, Class[] paramTypes, Object[] args) {
        return InstantiateFactory.getInstance(classToInstantiate, paramTypes, args);
    }

}