net.sourceforge.stripes.controller.ObjectFactory Maven / Gradle / Ivy

Go to download
/* Copyright 2008 Ben Gunter
 *
 * 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.sourceforge.stripes.controller;

import java.lang.reflect.Constructor;

import net.sourceforge.stripes.config.ConfigurableComponent;

/**
 * Used throughout Stripes to instantiate classes. The default implementation is
 * {@link DefaultObjectFactory}. You can specify an alternate implementation to use by setting the
 * {@code ObjectFactory.Class} initialization parameter for {@link StripesFilter} or by placing your
 * implementation in one of the packages named in {@code Extension.Packages}.
 * 
 *  * <init-param>
 *  <param-name>ObjectFactory.Class</param-name>
 *  <param-value>com.mycompany.stripes.ext.MyObjectFactory</param-value>
 * </init-param>
 * 
 * 
 * @author Ben Gunter
 * @since Stripes 1.5.1
 */
public interface ObjectFactory extends ConfigurableComponent {
    /**
     * 
     * A wrapper for a {@link Constructor}. This interface provides a builder-style API for
     * instantiating classes by invoking a specific constructor. Typical usage might look like:
     * 
     * 
     * configuration.getObjectFactory().constructor(targetType, String.class).newInstance("FOO");
     * 
     */
    public static interface ConstructorWrapper {
        /** Get the {@link Constructor} object wrapped by this instance. */
        public Constructor getConstructor();

        /** Invoke the constructor with the specified arguments and return the new object. */
        public T newInstance(Object... args);
    }

    /**
     * Create a new instance of {@code clazz} and return it.
     * 
     * @param clazz The class to instantiate.
     * @return A new instances of the class.
     */
     T newInstance(Class clazz);

    /**
     * Create a new instances of {@code T} by invoking the given constructor.
     * 
     * @return A new object instantiated by invoking the constructor.
     */
     T newInstance(Constructor constructor, Object... args);

    /**
     * Create a new instance of {@code clazz} by calling a specific constructor.
     * 
     * @param clazz The class to instantiate.
     * @param constructorArgTypes The type arguments of the constructor to be invoked. (See
     *            {@link Class#getConstructor(Class...)}.)
     * @param constructorArgs The arguments to pass to the constructor. (See
     *            {@link Constructor#newInstance(Object...)}.)
     * @return A new instance of the class.
     */
     T newInstance(Class clazz, Class[] constructorArgTypes, Object[] constructorArgs);

    /**
     * 
     * Provides a builder-style interface for instantiating objects by calling specific
     * constructors. Typical usage might look like:
     * 
     * 
     * configuration.getObjectFactory().constructor(targetType, String.class).newInstance("FOO");
     * 
     * 
     * @param clazz The class whose constructor is to be looked up.
     * @param parameterTypes The types of the parameters to the constructor.
     * @return A {@link ConstructorWrapper} that allows for invoking the constructor.
     */
     ConstructorWrapper constructor(Class clazz, Class... parameterTypes);
}