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é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 }