    001    /*****************************************************************************
    002     * Copyright (C) PicoContainer Organization. All rights reserved.            *
    003     * ------------------------------------------------------------------------- *
    004     * The software in this package is published under the terms of the BSD      *
    005     * style license a copy of which has been included with this distribution in *
    006     * the LICENSE.txt file.                                                     *
    007     *                                                                           *
    008     * Original code by                                                          *
    009     *****************************************************************************/
    010    package org.picocontainer;
    011
    012    import org.picocontainer.ComponentAdapter;
    013    import org.picocontainer.Parameter;
    014    import org.picocontainer.PicoCompositionException;
    015    import org.picocontainer.ComponentMonitor;
    016    import org.picocontainer.LifecycleStrategy;
    017
    018    import java.util.Properties;
    019
    020    /**
    021     * <p/>
    022     * A component factory is responsible for creating
    023     * {@link ComponentAdapter} component adapters. The main use of the component factory is
    024     * inside {@link DefaultPicoContainer#DefaultPicoContainer(ComponentFactory)}, where it can
    025     * be used to customize the default component adapter that is used when none is specified
    026     * explicitly.
    027     * </p>
    028     *
    029     * @author Paul Hammant
    030     * @author Mauro Talevi
    031     * @author Jon Tirs&eacute;n
    032     */
    033    public interface ComponentFactory {
    034
    035        /**
    036         * Create a new component adapter based on the specified arguments.
    037         *
    038         * @param componentMonitor the component monitor
    039         * @param lifecycleStrategy te lifecycle strategy
    040         * @param componentProperties the component properties
    041         * @param componentKey the key to be associated with this adapter. This
    042         *            value should be returned from a call to
    043         *            {@link ComponentAdapter#getComponentKey()} on the created
    044         *            adapter.
    045         * @param componentImplementation the implementation class to be associated
    046         *            with this adapter. This value should be returned from a call
    047         *            to {@link ComponentAdapter#getComponentImplementation()} on
    048         *            the created adapter. Should not be null.
    049         * @param parameters additional parameters to use by the component adapter
    050         *            in constructing component instances. These may be used, for
    051         *            example, to make decisions about the arguments passed into the
    052         *            component constructor. These should be considered hints; they
    053         *            may be ignored by some implementations. May be null, and may
    054         *            be of zero length.
    055         * @return a new component adapter based on the specified arguments. Should
    056         *         not return null.
    057         * @throws PicoCompositionException if the creation of the component adapter
    058         *             results in a {@link PicoCompositionException}.
    059         * @return The component adapter
    060         */
    061        <T> ComponentAdapter<T> createComponentAdapter(ComponentMonitor componentMonitor,
    062                                                LifecycleStrategy lifecycleStrategy,
    063                                                Properties componentProperties,
    064                                                Object componentKey,
    065                                                Class<T> componentImplementation,
    066                                                Parameter... parameters) throws PicoCompositionException;
    067
    068        /**
    069         * Verification for the ComponentFactory - subject to implementation.
    070         *
    071         * @param container the {@link PicoContainer}, that is used for verification.
    072         * @throws PicoCompositionException if one or more dependencies cannot be resolved.
    073         */
    074        void verify(PicoContainer container);
    075
    076        /**
    077         * Accepts a visitor for this ComponentFactory. The method is normally called by visiting a {@link PicoContainer}, that
    078         * cascades the visitor also down to all its ComponentFactory instances.
    079         *
    080         * @param visitor the visitor.
    081         */
    082        void accept(PicoVisitor visitor);
    083    }