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 java.util.Dictionary;
022
023import org.apache.felix.ipojo.architecture.InstanceDescription;
024import org.osgi.framework.BundleContext;
025
026/**
027 * This class defines the iPOJO's component instance concept.
028 * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
029 */
030public interface ComponentInstance {
031
032    /**
033     * Component Instance State : DISPOSED. The component instance was disposed.
034     */
035    int DISPOSED = -1;
036    
037    /**
038     * Component Instance State : STOPPED. The component instance is not
039     * started.
040     */
041    int STOPPED = 0;
042
043    /**
044     * Component Instance State : INVALID. The component instance is invalid when it
045     * starts or when a component dependency is invalid.
046     */
047    int INVALID = 1;
048
049    /**
050     * Component Instance State : VALID. The component instance is resolved when it is
051     * running and all its attached handlers are valid.
052     */
053    int VALID = 2;
054
055    /**
056     * Starts the component instance.
057     */
058    void start();
059
060    /**
061     * Stops the component instance.
062     * A stopped instance can be re-started.
063     */
064    void stop();
065    
066    /**
067     * Disposes the component instance.
068     * A disposed instance cannot be re-started.
069     */
070    void dispose();
071
072    /**
073     * Returns the actual state of the instance. 
074     * @return the actual state of the component instance.
075     */
076    int getState();
077
078    /**
079     * Returns the instance description.
080     * @return the instance description of the current instance
081     */
082    InstanceDescription getInstanceDescription();
083
084    /**
085     * Returns the factory who created this instance.
086     * @return the factory of the component instance.
087     */
088    ComponentFactory getFactory();
089
090    /**
091     * Returns the bundle context of this instance.
092     * @return the context of the component instance
093     */
094    BundleContext getContext();
095
096    /**
097     * Returns the name of the instance.
098     * @return the name of the component instance
099     */
100    String getInstanceName();
101
102    /**
103     * Checks if the instance is started.
104     * @return <code>true</code> if {@link ComponentInstance#getState()} 
105     * returns {@link ComponentInstance#INVALID} or {@link ComponentInstance#VALID}.
106     */
107    boolean isStarted();
108
109    /**
110     * Re-configures an instance. Do nothing if the instance does not support
111     * dynamic reconfiguration. The reconfiguration does not stop the instance.
112     * @param configuration the new configuration.
113     */
114    void reconfigure(Dictionary configuration);
115    
116    /**
117     * Adds an instance state listener on the current instance.
118     * @param listener the listener to add.
119     */
120    void addInstanceStateListener(InstanceStateListener listener);
121    
122    /**
123     * Removes an instance state listener on the current instance.
124     * @param listener the listener to remove.
125     */
126    void removeInstanceStateListener(InstanceStateListener listener);
127
128}