Clover coverage report - PicoContainer - 1.1
Coverage timestamp: Thu Nov 4 2004 11:55:45 CST
file stats: LOC: 165   Methods: 0
NCLOC: 14   Classes: 1
30 day Evaluation Version distributed via the Maven Jar Repository. Clover is not free. You have 30 days to evaluate it. Please visit http://www.thecortex.net/clover to obtain a licensed version of Clover
 
 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: 1.49 $
 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   
 }
 165