Clover coverage report - PicoContainer - 1.0-RC-1
Coverage timestamp: Tue May 18 2004 16:19:33 EDT
file stats: LOC: 140   Methods: 0
NCLOC: 12   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   
  * This is the core interface used for registration of components with a container. It is possible to register {@link
 14   
  * #registerComponentImplementation(Object,Class) an implementation class}, {@link #registerComponentInstance(Object) an
 15   
  * instance} or {@link #registerComponent(ComponentAdapter) a ComponentAdapter}.
 16   
  *
 17   
  * @see "The <a href='package-summary.html#package_description'>The package description</a> has a basic overview of how to use the picocontainer package."
 18   
  * 
 19   
  * @author Paul Hammant
 20   
  * @author Aslak Helles&oslash;y
 21   
  * @author Jon Tirs&eacute;n
 22   
  * @version $Revision: 1.29 $
 23   
  * @since 1.0
 24   
  */
 25   
 public interface MutablePicoContainer extends PicoContainer {
 26   
 
 27   
     /**
 28   
      * Register a component.
 29   
      * 
 30   
      * @param componentKey            a key that identifies the component. Must be unique within the container. The type
 31   
      *                                of the key object has no semantic significance unless explicitly specified in the
 32   
      *                                documentation of the implementing container.
 33   
      * @param componentImplementation the component's implementation class. This must be a concrete class (ie, a
 34   
      *                                class that can be instantiated).
 35   
      * @return the ComponentAdapter that has been associated with this component. In the majority of cases, this return
 36   
      *     value can be safely ignored, as one of the <code>getXXX()</code> methods of the
 37   
      *     {@link PicoContainer} interface can be used to retrieve a reference to the component later on.
 38   
      * @throws PicoRegistrationException if registration of the component fails.
 39   
      * @see #registerComponentImplementation(Object,Class,Parameter[]) a variant of this method that allows more control
 40   
      *     over the parameters passed into the componentImplementation constructor when constructing an instance. 
 41   
      */
 42   
     ComponentAdapter registerComponentImplementation(Object componentKey, Class componentImplementation) throws PicoRegistrationException;
 43   
 
 44   
     /**
 45   
      * Register a component.
 46   
      * 
 47   
      * @param componentKey            a key that identifies the component. Must be unique within the container. The type
 48   
      *                                of the key object has no semantic significance unless explicitly specified in the
 49   
      *                                documentation of the implementing container.
 50   
      * @param componentImplementation the component's implementation class. This must be a concrete class (ie, a
 51   
      *                                class that can be instantiated).
 52   
      * @param parameters              an array of parameters that gives the container hints about what arguments to pass
 53   
      *                                to the constructor when it is instantiated. Container implementations may ignore
 54   
      *                                one or more of these hints.
 55   
      * @return the ComponentAdapter that has been associated with this component. In the majority of cases, this return
 56   
      *     value can be safely ignored, as one of the <code>getXXX()</code> methods of the
 57   
      *     {@link PicoContainer} interface can be used to retrieve a reference to the component later on.
 58   
      * @throws PicoRegistrationException if registration of the component fails.
 59   
      */
 60   
     ComponentAdapter registerComponentImplementation(Object componentKey, Class componentImplementation, Parameter[] parameters) throws PicoRegistrationException;
 61   
 
 62   
     /**
 63   
      * Register a component using the componentImplementation as key. Calling this method is equivalent to calling
 64   
      * <code>registerComponentImplementation(componentImplementation, componentImplementation)</code>.
 65   
      * 
 66   
      * @param componentImplementation the concrete component class.
 67   
      * @return the ComponentAdapter that has been associated with this component. In the majority of cases, this return
 68   
      *     value can be safely ignored, as one of the <code>getXXX()</code> methods of the
 69   
      *     {@link PicoContainer} interface can be used to retrieve a reference to the component later on.
 70   
      * @throws PicoRegistrationException if registration fails.
 71   
      */
 72   
     ComponentAdapter registerComponentImplementation(Class componentImplementation) throws PicoRegistrationException;
 73   
 
 74   
     /**
 75   
      * Register an arbitrary object. The class of the object will be used as a key. Calling this method is equivalent to
 76   
      * calling     * <code>registerComponentImplementation(componentImplementation, componentImplementation)</code>.
 77   
      * 
 78   
      * @param componentInstance 
 79   
      * @return the ComponentAdapter that has been associated with this component. In the majority of cases, this return
 80   
      *     value can be safely ignored, as one of the <code>getXXX()</code> methods of the
 81   
      *     {@link PicoContainer} interface can be used to retrieve a reference to the component later on.
 82   
      * @throws PicoRegistrationException if registration fails.
 83   
      */
 84   
     ComponentAdapter registerComponentInstance(Object componentInstance) throws PicoRegistrationException;
 85   
 
 86   
     /**
 87   
      * Register an arbitrary object as a component in the container. This is handy when other components in the same
 88   
      * container have dependencies on this kind of object, but where letting the container manage and instantiate it is
 89   
      * impossible.
 90   
      * <p/>
 91   
      * Beware that too much use of this method is an <a href="http://docs.codehaus.org/display/PICO/Instance+Registration">antipattern</a>.
 92   
      * 
 93   
      * @param componentKey      a key that identifies the component. Must be unique within the conainer. The type of the
 94   
      *                          key object has no semantic significance unless explicitly specified in the implementing
 95   
      *                          container.
 96   
      * @param componentInstance an arbitrary object.
 97   
      * @return the ComponentAdapter that has been associated with this component. In the majority of cases, this return
 98   
      *     value can be safely ignored, as one of the <code>getXXX()</code> methods of the
 99   
      *     {@link PicoContainer} interface can be used to retrieve a reference to the component later on.
 100   
      * @throws PicoRegistrationException if registration fails.
 101   
      */
 102   
     ComponentAdapter registerComponentInstance(Object componentKey, Object componentInstance) throws PicoRegistrationException;
 103   
 
 104   
     /**
 105   
      * Register a component via a ComponentAdapter. Use this if you need fine grained control over what
 106   
      * ComponentAdapter to use for a specific component.
 107   
      * 
 108   
      * @param componentAdapter the adapter
 109   
      * @return the same adapter that was passed as an argument.
 110   
      * @throws PicoRegistrationException if registration fails.
 111   
      */
 112   
     ComponentAdapter registerComponent(ComponentAdapter componentAdapter) throws PicoRegistrationException;
 113   
 
 114   
     /**
 115   
      * Unregister a component by key.
 116   
      * 
 117   
      * @param componentKey key of the component to unregister.
 118   
      * @return the ComponentAdapter that was associated with this component.
 119   
      */
 120   
     ComponentAdapter unregisterComponent(Object componentKey);
 121   
 
 122   
     /**
 123   
      * Unregister a component by instance.
 124   
      * 
 125   
      * @param componentInstance the component instance to unregister.
 126   
      * @return the ComponentAdapter that was associated with this component.
 127   
      */
 128   
     ComponentAdapter unregisterComponentByInstance(Object componentInstance);
 129   
 
 130   
     /**
 131   
      * Set the Parent container.
 132   
      * 
 133   
      * @param parent parent container.
 134   
      * @deprecated This will probably go away. implementations should take the parent in the constructor (constructor
 135   
      *             injection!)
 136   
      */
 137   
     void setParent(PicoContainer parent);
 138   
 
 139   
 }
 140