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 *****************************************************************************/
010package org.picocontainer;
011
012import org.picocontainer.ComponentAdapter;
013import org.picocontainer.Parameter;
014import org.picocontainer.PicoCompositionException;
015import org.picocontainer.ComponentMonitor;
016import org.picocontainer.LifecycleStrategy;
017
018import 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 */
033public 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}