Clover coverage report - picocontainer - 1.2-beta-1
Coverage timestamp: Sun May 29 2005 14:29:04 BST
file stats: LOC: 164   Methods: 0
NCLOC: 14   Classes: 1
 
 Source file Conditionals Statements Methods TOTAL
MutablePicoContainer.java - - - -
coverage
 1    /*****************************************************************************
 2    * Copyright (c) PicoContainer Organization. All rights reserved. *
 3    * ------------------------------------------------------------------------- *
 4    * The software in this package is published under the terms of the BSD *
 5    * style license a copy of which has been included with this distribution in *
 6    * the LICENSE.txt file. *
 7    * *
 8    * Idea by Rachel Davies, Original code by various *
 9    *****************************************************************************/
 10    package org.picocontainer;
 11   
 12   
 13   
 14    /**
 15    * This is the core interface used for registration of components with a container. It is possible to register {@link
 16    * #registerComponentImplementation(Object,Class) an implementation class}, {@link #registerComponentInstance(Object) an
 17    * instance} or {@link #registerComponent(ComponentAdapter) a ComponentAdapter}.
 18    *
 19    * @author Paul Hammant
 20    * @author Aslak Hellesøy
 21    * @author Jon Tirsén
 22    * @version $Revision: 1800 $
 23    * @see <a href="package-summary.html#package_description">See package description for basic overview how to use PicoContainer.</a>
 24    * @since 1.0
 25    */
 26    public interface MutablePicoContainer extends PicoContainer {
 27   
 28    /**
 29    * Register a component.
 30    *
 31    * @param componentKey a key that identifies the component. Must be unique within the container. The type
 32    * of the key object has no semantic significance unless explicitly specified in the
 33    * documentation of the implementing container.
 34    * @param componentImplementation the component's implementation class. This must be a concrete class (ie, a
 35    * class that can be instantiated).
 36    * @return the ComponentAdapter that has been associated with this component. In the majority of cases, this return
 37    * value can be safely ignored, as one of the <code>getXXX()</code> methods of the
 38    * {@link PicoContainer} interface can be used to retrieve a reference to the component later on.
 39    * @throws PicoRegistrationException if registration of the component fails.
 40    * @see #registerComponentImplementation(Object,Class,Parameter[]) a variant of this method that allows more control
 41    * over the parameters passed into the componentImplementation constructor when constructing an instance.
 42    */
 43    ComponentAdapter registerComponentImplementation(Object componentKey, Class componentImplementation) throws PicoRegistrationException;
 44   
 45    /**
 46    * Register a component.
 47    *
 48    * @param componentKey a key that identifies the component. Must be unique within the container. The type
 49    * of the key object has no semantic significance unless explicitly specified in the
 50    * documentation of the implementing container.
 51    * @param componentImplementation the component's implementation class. This must be a concrete class (ie, a
 52    * class that can be instantiated).
 53    * @param parameters an array of parameters that gives the container hints about what arguments to pass
 54    * to the constructor when it is instantiated. Container implementations may ignore
 55    * one or more of these hints.
 56    * @return the ComponentAdapter that has been associated with this component. In the majority of cases, this return
 57    * value can be safely ignored, as one of the <code>getXXX()</code> methods of the
 58    * {@link PicoContainer} interface can be used to retrieve a reference to the component later on.
 59    * @throws PicoRegistrationException if registration of the component fails.
 60    */
 61    ComponentAdapter registerComponentImplementation(Object componentKey, Class componentImplementation, Parameter[] parameters) throws PicoRegistrationException;
 62   
 63    /**
 64    * Register a component using the componentImplementation as key. Calling this method is equivalent to calling
 65    * <code>registerComponentImplementation(componentImplementation, componentImplementation)</code>.
 66    *
 67    * @param componentImplementation the concrete component class.
 68    * @return the ComponentAdapter that has been associated with this component. In the majority of cases, this return
 69    * value can be safely ignored, as one of the <code>getXXX()</code> methods of the
 70    * {@link PicoContainer} interface can be used to retrieve a reference to the component later on.
 71    * @throws PicoRegistrationException if registration fails.
 72    */
 73    ComponentAdapter registerComponentImplementation(Class componentImplementation) throws PicoRegistrationException;
 74   
 75    /**
 76    * Register an arbitrary object. The class of the object will be used as a key. Calling this method is equivalent to
 77    * calling * <code>registerComponentImplementation(componentImplementation, componentImplementation)</code>.
 78    *
 79    * @param componentInstance
 80    * @return the ComponentAdapter that has been associated with this component. In the majority of cases, this return
 81    * value can be safely ignored, as one of the <code>getXXX()</code> methods of the
 82    * {@link PicoContainer} interface can be used to retrieve a reference to the component later on.
 83    * @throws PicoRegistrationException if registration fails.
 84    */
 85    ComponentAdapter registerComponentInstance(Object componentInstance) throws PicoRegistrationException;
 86   
 87    /**
 88    * Register an arbitrary object as a component in the container. This is handy when other components in the same
 89    * container have dependencies on this kind of object, but where letting the container manage and instantiate it is
 90    * impossible.
 91    * <p/>
 92    * Beware that too much use of this method is an <a href="http://docs.codehaus.org/display/PICO/Instance+Registration">antipattern</a>.
 93    *
 94    * @param componentKey a key that identifies the component. Must be unique within the conainer. The type of the
 95    * key object has no semantic significance unless explicitly specified in the implementing
 96    * container.
 97    * @param componentInstance an arbitrary object.
 98    * @return the ComponentAdapter that has been associated with this component. In the majority of cases, this return
 99    * value can be safely ignored, as one of the <code>getXXX()</code> methods of the
 100    * {@link PicoContainer} interface can be used to retrieve a reference to the component later on.
 101    * @throws PicoRegistrationException if registration fails.
 102    */
 103    ComponentAdapter registerComponentInstance(Object componentKey, Object componentInstance) throws PicoRegistrationException;
 104   
 105    /**
 106    * Register a component via a ComponentAdapter. Use this if you need fine grained control over what
 107    * ComponentAdapter to use for a specific component.
 108    *
 109    * @param componentAdapter the adapter
 110    * @return the same adapter that was passed as an argument.
 111    * @throws PicoRegistrationException if registration fails.
 112    */
 113    ComponentAdapter registerComponent(ComponentAdapter componentAdapter) throws PicoRegistrationException;
 114   
 115    /**
 116    * Unregister a component by key.
 117    *
 118    * @param componentKey key of the component to unregister.
 119    * @return the ComponentAdapter that was associated with this component.
 120    */
 121    ComponentAdapter unregisterComponent(Object componentKey);
 122   
 123    /**
 124    * Unregister a component by instance.
 125    *
 126    * @param componentInstance the component instance to unregister.
 127    * @return the ComponentAdapter that was associated with this component.
 128    */
 129    ComponentAdapter unregisterComponentByInstance(Object componentInstance);
 130   
 131    // TODO: For the sake of simplicity/unambiguity - perhaps remove this method and instead expose getComponentAdapterFactory()? --Aslak
 132    /**
 133    * Make a child container, using the same implementation of MutablePicoContainer as the parent.
 134    * It will have a reference to this as parent. This will list the resulting MPC as a child.
 135    * Lifecycle events will be cascaded from parent to child
 136    * as a consequence of this.
 137    *
 138    * @return the new child container.
 139    * @since 1.1
 140    */
 141    MutablePicoContainer makeChildContainer();
 142   
 143    /**
 144    * Add a child container. This action will list the the 'child' as exactly that in the parents scope.
 145    * It will not change the child's view of a parent. That is determined by the constructor arguments of the child
 146    * itself. Lifecycle events will be cascaded from parent to child
 147    * as a consequence of calling this method.
 148    *
 149    * @param child the child container
 150    * @return <code>true</code> if the child container was not already in.
 151    * @since 1.1
 152    */
 153    boolean addChildContainer(PicoContainer child);
 154   
 155    /**
 156    * Remove a child container from this container. It will not change the child's view of a parent.
 157    * Lifecycle event will no longer be cascaded from the parent to the child.
 158    *
 159    * @param child the child container
 160    * @return <code>true</code> if the child container has been removed.
 161    * @since 1.1
 162    */
 163    boolean removeChildContainer(PicoContainer child);
 164    }