001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017 package org.apache.commons.collections;
018
019 import org.apache.commons.collections.functors.ConstantFactory;
020 import org.apache.commons.collections.functors.InstantiateFactory;
021 import org.apache.commons.collections.functors.ExceptionFactory;
022 import org.apache.commons.collections.functors.PrototypeFactory;
023
024 /**
025 * <code>FactoryUtils</code> provides reference implementations and utilities
026 * for the Factory functor interface. The supplied factories are:
027 * <ul>
028 * <li>Prototype - clones a specified object
029 * <li>Reflection - creates objects using reflection
030 * <li>Constant - always returns the same object
031 * <li>Null - always returns null
032 * <li>Exception - always throws an exception
033 * </ul>
034 * All the supplied factories are Serializable.
035 *
036 * @since Commons Collections 3.0
037 * @version $Revision: 646777 $ $Date: 2008-04-10 13:33:15 +0100 (Thu, 10 Apr 2008) $
038 *
039 * @author Stephen Colebourne
040 */
041 public class FactoryUtils {
042
043 /**
044 * This class is not normally instantiated.
045 */
046 public FactoryUtils() {
047 super();
048 }
049
050 /**
051 * Gets a Factory that always throws an exception.
052 * This could be useful during testing as a placeholder.
053 *
054 * @see org.apache.commons.collections.functors.ExceptionFactory
055 *
056 * @return the factory
057 */
058 public static Factory exceptionFactory() {
059 return ExceptionFactory.INSTANCE;
060 }
061
062 /**
063 * Gets a Factory that will return null each time the factory is used.
064 * This could be useful during testing as a placeholder.
065 *
066 * @see org.apache.commons.collections.functors.ConstantFactory
067 *
068 * @return the factory
069 */
070 public static Factory nullFactory() {
071 return ConstantFactory.NULL_INSTANCE;
072 }
073
074 /**
075 * Creates a Factory that will return the same object each time the factory
076 * is used. No check is made that the object is immutable. In general, only
077 * immutable objects should use the constant factory. Mutable objects should
078 * use the prototype factory.
079 *
080 * @see org.apache.commons.collections.functors.ConstantFactory
081 *
082 * @param constantToReturn the constant object to return each time in the factory
083 * @return the <code>constant</code> factory.
084 */
085 public static Factory constantFactory(Object constantToReturn) {
086 return ConstantFactory.getInstance(constantToReturn);
087 }
088
089 /**
090 * Creates a Factory that will return a clone of the same prototype object
091 * each time the factory is used. The prototype will be cloned using one of these
092 * techniques (in order):
093 * <ul>
094 * <li>public clone method
095 * <li>public copy constructor
096 * <li>serialization clone
097 * <ul>
098 *
099 * @see org.apache.commons.collections.functors.PrototypeFactory
100 *
101 * @param prototype the object to clone each time in the factory
102 * @return the <code>prototype</code> factory
103 * @throws IllegalArgumentException if the prototype is null
104 * @throws IllegalArgumentException if the prototype cannot be cloned
105 */
106 public static Factory prototypeFactory(Object prototype) {
107 return PrototypeFactory.getInstance(prototype);
108 }
109
110 /**
111 * Creates a Factory that can create objects of a specific type using
112 * a no-args constructor.
113 *
114 * @see org.apache.commons.collections.functors.InstantiateFactory
115 *
116 * @param classToInstantiate the Class to instantiate each time in the factory
117 * @return the <code>reflection</code> factory
118 * @throws IllegalArgumentException if the classToInstantiate is null
119 */
120 public static Factory instantiateFactory(Class classToInstantiate) {
121 return InstantiateFactory.getInstance(classToInstantiate, null, null);
122 }
123
124 /**
125 * Creates a Factory that can create objects of a specific type using
126 * the arguments specified to this method.
127 *
128 * @see org.apache.commons.collections.functors.InstantiateFactory
129 *
130 * @param classToInstantiate the Class to instantiate each time in the factory
131 * @param paramTypes parameter types for the constructor, can be null
132 * @param args the arguments to pass to the constructor, can be null
133 * @return the <code>reflection</code> factory
134 * @throws IllegalArgumentException if the classToInstantiate is null
135 * @throws IllegalArgumentException if the paramTypes and args don't match
136 * @throws IllegalArgumentException if the constructor doesn't exist
137 */
138 public static Factory instantiateFactory(Class classToInstantiate, Class[] paramTypes, Object[] args) {
139 return InstantiateFactory.getInstance(classToInstantiate, paramTypes, args);
140 }
141
142 }