001/* 
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *   http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied.  See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019package org.apache.felix.ipojo;
020
021import org.apache.felix.ipojo.architecture.ComponentTypeDescription;
022import org.apache.felix.ipojo.metadata.Element;
023import org.osgi.framework.BundleContext;
024
025import java.util.Dictionary;
026import java.util.List;
027
028/**
029 * Component Type Factory Service. This service is exposed by a instance manager factory, and allows the dynamic creation of component instance.
030 *
031 * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
032 */
033public interface Factory {
034
035    /**
036     * Factory State.
037     * A valid factory is a factory where all required handlers are available.
038     */
039    int VALID = 1;
040    /**
041     * Factory State.
042     * An invalid factory is a factory where at least one required handler is
043     * unavailable. Creating an instance with an invalid factory failed.
044     */
045    int INVALID = 0;
046    /**
047     * Instance configuration can set the instance name using this property.
048     */
049    String INSTANCE_NAME_PROPERTY = "instance.name";
050    /**
051     * Instance configuration can set the factory version they target using this property.
052     */
053    String FACTORY_VERSION_PROPERTY = "factory.version";
054
055    /**
056     * Creates an instance manager (i.e. component type instance).
057     *
058     * @param configuration the configuration properties for this component.
059     * @return the created instance manager.
060     * @throws UnacceptableConfiguration if the given configuration is not valid.
061     * @throws MissingHandlerException   if an handler is missing.
062     * @throws ConfigurationException    if the instance configuration failed.
063     */
064    ComponentInstance createComponentInstance(Dictionary configuration) throws UnacceptableConfiguration, MissingHandlerException, ConfigurationException;
065
066    /**
067     * Creates an instance manager (i.e. component type instance).
068     * The instance is created in the scope given in argument.
069     *
070     * @param configuration  the configuration properties for this component.
071     * @param serviceContext the service context of the component.
072     * @return the created instance manager.
073     * @throws UnacceptableConfiguration if the given configuration is not valid.
074     * @throws MissingHandlerException   if an handler is missing.
075     * @throws ConfigurationException    if the instance configuration failed.
076     */
077    ComponentInstance createComponentInstance(Dictionary configuration, ServiceContext serviceContext) throws UnacceptableConfiguration, MissingHandlerException, ConfigurationException;
078
079    /**
080     * Gets the component type information containing provided service,
081     * configuration properties ...
082     *
083     * @return the component type information.
084     */
085    Element getDescription();
086
087    /**
088     * Gets the component type description.
089     *
090     * @return the component type description object
091     */
092    ComponentTypeDescription getComponentDescription();
093
094    /**
095     * Checks if the given configuration is acceptable as a configuration
096     * of a component instance.
097     *
098     * @param conf the configuration to test
099     * @return <code>true</code> if the configuration is acceptable
100     */
101    boolean isAcceptable(Dictionary conf);
102
103    /**
104     * Returns the factory name.
105     *
106     * @return the name of the factory.
107     */
108    String getName();
109
110    /**
111     * Reconfigures an instance already created. This configuration needs to
112     * have the name property to identify the instance.
113     *
114     * @param conf the configuration to reconfigure the instance. The instance.name property must be set to identify
115     *             the instance to reconfigure.
116     * @throws UnacceptableConfiguration if the given configuration is not consistent for the targeted instance.
117     * @throws MissingHandlerException   if an handler is missing.
118     */
119    void reconfigure(Dictionary conf) throws UnacceptableConfiguration, MissingHandlerException;
120
121    /**
122     * Adds a factory state listener on the current factory.
123     *
124     * @param listener the listener to add
125     */
126    void addFactoryStateListener(FactoryStateListener listener);
127
128    /**
129     * Removes the given factory state listener from the listener list.
130     *
131     * @param listener the listener to remove
132     */
133    void removeFactoryStateListener(FactoryStateListener listener);
134
135    /**
136     * Gets the list of missing handlers.
137     * The handlers are given under the form namespace:name
138     *
139     * @return the list containing the name of missing handlers
140     */
141    List getMissingHandlers();
142
143    /**
144     * Get the list of required handlers.
145     * The handlers are given under the form namespace:name
146     *
147     * @return the list containing the name of required handlers
148     */
149    List getRequiredHandlers();
150
151    /**
152     * Returns the class name of the component type.
153     * For factories which does not contains a class, return "composite"
154     *
155     * @return the class name of the component type or "composite"
156     * @deprecated
157     */
158    String getClassName();
159
160    /**
161     * Returns the state of the factory.
162     *
163     * @return the state of the factory
164     */
165    int getState();
166
167    /**
168     * Gets the bundle context of the factory.
169     *
170     * @return the bundle context of the factory.
171     */
172    BundleContext getBundleContext();
173
174    /**
175     * Gets the version of the component type.
176     *
177     * @return the component type version or <code>null</code> if
178     *         not specified.
179     */
180    String getVersion();
181
182    /**
183     * Gets the component type metadata (Element - Attribute structure)
184     *
185     * @return the root element of the component metadata. The result must <b>not</b> be modified.
186     */
187    Element getComponentMetadata();
188
189    /**
190     * Gets the list of instances created by the factory. The instances must be still alive.
191     *
192     * @return the list of created (and living) instances
193     * @since 1.11.0
194     */
195    List<ComponentInstance> getInstances();
196
197    /**
198     * Gets the list of the names of the instances created by the factory. The instances must be still alive.
199     *
200     * @return the list of the names of created (and living) instances
201     * @since 1.11.0
202     */
203    List<String> getInstancesNames();
204
205}