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: *****************************************************************************/package org.picocontainer;
010:
011: import java.util.Properties;
012:
013: /**
014: * This is the core interface used for registration of components with a container. It is possible to register
015: * implementations and instances here
016: *
017: * @author Paul Hammant
018: * @author Aslak Hellesøy
019: * @author Jon Tirsén
020: * @see <a href="package-summary.html#package_description">See package description for basic overview how to use PicoContainer.</a>
021: */
022: public interface MutablePicoContainer extends PicoContainer, Startable,
023: 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(
118: T componentInstance);
119:
120: /**
121: * Make a child container, using the same implementation of MutablePicoContainer as the parent.
122: * It will have a reference to this as parent. This will list the resulting MPC as a child.
123: * Lifecycle events will be cascaded from parent to child
124: * as a consequence of this.
125: *
126: * @return the new child container.
127: *
128: */
129: MutablePicoContainer makeChildContainer();
130:
131: /**
132: * Add a child container. This action will list the the 'child' as exactly that in the parents scope.
133: * It will not change the child's view of a parent. That is determined by the constructor arguments of the child
134: * itself. Lifecycle events will be cascaded from parent to child
135: * as a consequence of calling this method.
136: *
137: * @param child the child container
138: *
139: * @return the same instance of MutablePicoContainer
140: *
141: */
142: MutablePicoContainer addChildContainer(PicoContainer child);
143:
144: /**
145: * Remove a child container from this container. It will not change the child's view of a parent.
146: * Lifecycle event will no longer be cascaded from the parent to the child.
147: *
148: * @param child the child container
149: *
150: * @return <code>true</code> if the child container has been removed.
151: *
152: */
153: boolean removeChildContainer(PicoContainer child);
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: }
|