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 * Idea by Rachel Davies, Original code by various * 009 *****************************************************************************/ 010 package org.picocontainer; 011 012 import java.util.Properties; 013 014 /** 015 * This is the core interface used for registration of components with a container. It is possible to register 016 * implementations and instances here 017 * 018 * @author Paul Hammant 019 * @author Aslak Hellesøy 020 * @author Jon Tirsén 021 * @see <a href="package-summary.html#package_description">See package description for basic overview how to use PicoContainer.</a> 022 */ 023 public interface MutablePicoContainer extends PicoContainer, Startable, Disposable { 024 025 /** 026 * Register a component and creates specific instructions on which constructor to use, along with 027 * which components and/or constants to provide as constructor arguments. These "directives" are 028 * provided through an array of <tt>Parameter</tt> objects. Parameter[0] correspondes to the first constructor 029 * argument, Parameter[N] corresponds to the N+1th constructor argument. 030 * <h4>Tips for Parameter usage</h4> 031 * <ul> 032 * <li><strong>Partial Autowiring: </strong>If you have two constructor args to match and you only wish to specify one of the constructors and 033 * let PicoContainer wire the other one, you can use as parameters: 034 * <code><strong>new ComponentParameter()</strong>, new ComponentParameter("someService")</code> 035 * The default constructor for the component parameter indicates auto-wiring should take place for 036 * that parameter. 037 * </li> 038 * <li><strong>Force No-Arg constructor usage:</strong> If you wish to force a component to be constructed with 039 * the no-arg constructor, use a zero length Parameter array. Ex: <code>new Parameter[0]</code> 040 * <ul> 041 * 042 * @param componentKey a key that identifies the component. Must be unique within the container. The type 043 * of the key object has no semantic significance unless explicitly specified in the 044 * documentation of the implementing container. 045 * @param componentImplementationOrInstance 046 * the component's implementation class. This must be a concrete class (ie, a 047 * class that can be instantiated). Or an intance of the compoent. 048 * @param parameters the parameters that gives the container hints about what arguments to pass 049 * to the constructor when it is instantiated. Container implementations may ignore 050 * one or more of these hints. 051 * 052 * @return the same instance of MutablePicoContainer 053 * 054 * @throws PicoCompositionException if registration of the component fails. 055 * @see org.picocontainer.Parameter 056 * @see org.picocontainer.parameters.ConstantParameter 057 * @see org.picocontainer.parameters.ComponentParameter 058 */ 059 MutablePicoContainer addComponent(Object componentKey, 060 Object componentImplementationOrInstance, 061 Parameter... parameters); 062 063 /** 064 * Register an arbitrary object. The class of the object will be used as a key. Calling this method is equivalent to 065 * calling <code>addComponent(componentImplementation, componentImplementation)</code>. 066 * 067 * @param implOrInstance Component implementation or instance 068 * 069 * @return the same instance of MutablePicoContainer 070 * 071 * @throws PicoCompositionException if registration fails. 072 */ 073 MutablePicoContainer addComponent(Object implOrInstance); 074 075 /** 076 * Register a config item. 077 * 078 * @param name the name of the config item 079 * @param val the value of the config item 080 * 081 * @return the same instance of MutablePicoContainer 082 * 083 * @throws PicoCompositionException if registration fails. 084 */ 085 MutablePicoContainer addConfig(String name, Object val); 086 087 /** 088 * Register a component via a ComponentAdapter. Use this if you need fine grained control over what 089 * ComponentAdapter to use for a specific component. The adapter will be wrapped in whatever behaviors that the 090 * the container has been set up with. If you want to bypass that behavior for the adapter you are adding, 091 * you should use Characteristics.NONE like so pico.as(Characteristics.NONE).addAdapter(...) 092 * 093 * @param componentAdapter the adapter 094 * 095 * @return the same instance of MutablePicoContainer 096 * 097 * @throws PicoCompositionException if registration fails. 098 */ 099 MutablePicoContainer addAdapter(ComponentAdapter<?> componentAdapter); 100 101 /** 102 * Unregister a component by key. 103 * 104 * @param componentKey key of the component to unregister. 105 * 106 * @return the ComponentAdapter that was associated with this component. 107 */ 108 <T> ComponentAdapter<T> removeComponent(Object componentKey); 109 110 /** 111 * Unregister a component by instance. 112 * 113 * @param componentInstance the component instance to unregister. 114 * 115 * @return the same instance of MutablePicoContainer 116 */ 117 <T> ComponentAdapter<T> removeComponentByInstance(T componentInstance); 118 119 /** 120 * Make a child container, using the same implementation of MutablePicoContainer as the parent. 121 * It will have a reference to this as parent. This will list the resulting MPC as a child. 122 * Lifecycle events will be cascaded from parent to child 123 * as a consequence of this. 124 * 125 * @return the new child container. 126 * 127 */ 128 MutablePicoContainer makeChildContainer(); 129 130 /** 131 * Add a child container. This action will list the the 'child' as exactly that in the parents scope. 132 * It will not change the child's view of a parent. That is determined by the constructor arguments of the child 133 * itself. Lifecycle events will be cascaded from parent to child 134 * as a consequence of calling this method. 135 * 136 * @param child the child container 137 * 138 * @return the same instance of MutablePicoContainer 139 * 140 */ 141 MutablePicoContainer addChildContainer(PicoContainer child); 142 143 /** 144 * Remove a child container from this container. It will not change the child's view of a parent. 145 * Lifecycle event will no longer be cascaded from the parent to the child. 146 * 147 * @param child the child container 148 * 149 * @return <code>true</code> if the child container has been removed. 150 * 151 */ 152 boolean removeChildContainer(PicoContainer child); 153 154 155 /** 156 * You can change the characteristic of registration of all subsequent components in this container. 157 * 158 * @param properties 159 * @return the same Pico instance with changed properties 160 */ 161 MutablePicoContainer change(Properties... properties); 162 163 /** 164 * You can set for the following operation only the characteristic of registration of a component on the fly. 165 * 166 * @param properties 167 * @return the same Pico instance with temporary properties 168 */ 169 MutablePicoContainer as(Properties... properties); 170 171 }