001 /*
002 * Copyright (c) OSGi Alliance (2004, 2009). All Rights Reserved.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017 package org.osgi.service.component;
018
019 import java.util.Dictionary;
020
021 import org.osgi.framework.Bundle;
022 import org.osgi.framework.BundleContext;
023 import org.osgi.framework.ServiceReference;
024
025 /**
026 * A Component Context object is used by a component instance to interact with
027 * its execution context including locating services by reference name. Each
028 * component instance has a unique Component Context.
029 *
030 * <p>
031 * A component instance may have an activate method. If a component instance has
032 * a suitable and accessible activate method, this method will be called when a
033 * component configuration is activated. If the activate method takes a
034 * <code>ComponentContext</code> argument, it will be passed the component
035 * instance's Component Context object. If the activate method takes a
036 * <code>BundleContext</code> argument, it will be passed the component
037 * instance's Bundle Context object. If the activate method takes a
038 * <code>Map</code> argument, it will be passed an unmodifiable Map containing
039 * the component properties.
040 *
041 * <p>
042 * A component instance may have a deactivate method. If a component instance
043 * has a suitable and accessible deactivate method, this method will be called
044 * when the component configuration is deactivated. If the deactivate method
045 * takes a <code>ComponentContext</code> argument, it will be passed the
046 * component instance's Component Context object. If the deactivate method takes
047 * a <code>BundleContext</code> argument, it will be passed the component
048 * instance's Bundle Context object. If the deactivate method takes a
049 * <code>Map</code> argument, it will be passed an unmodifiable Map containing
050 * the component properties. If the deactivate method takes an <code>int</code>
051 * or <code>Integer</code> argument, it will be passed the reason code for the
052 * component instance's deactivation.
053 *
054 * @ThreadSafe
055 * @version $Revision: 6462 $
056 */
057 public interface ComponentContext {
058 /**
059 * Returns the component properties for this Component Context.
060 *
061 * @return The properties for this Component Context. The Dictionary is read
062 * only and cannot be modified.
063 */
064 public Dictionary getProperties();
065
066 /**
067 * Returns the service object for the specified reference name.
068 *
069 * <p>
070 * If the cardinality of the reference is <code>0..n</code> or
071 * <code>1..n</code> and multiple services are bound to the reference, the
072 * service with the highest ranking (as specified in its
073 * <code>Constants.SERVICE_RANKING</code> property) is returned. If there is
074 * a tie in ranking, the service with the lowest service ID (as specified in
075 * its <code>Constants.SERVICE_ID</code> property); that is, the service
076 * that was registered first is returned.
077 *
078 * @param name The name of a reference as specified in a
079 * <code>reference</code> element in this component's description.
080 * @return A service object for the referenced service or <code>null</code>
081 * if the reference cardinality is <code>0..1</code> or
082 * <code>0..n</code> and no bound service is available.
083 * @throws ComponentException If the Service Component Runtime catches an
084 * exception while activating the bound service.
085 */
086 public Object locateService(String name);
087
088 /**
089 * Returns the service object for the specified reference name and
090 * <code>ServiceReference</code>.
091 *
092 * @param name The name of a reference as specified in a
093 * <code>reference</code> element in this component's description.
094 * @param reference The <code>ServiceReference</code> to a bound service.
095 * This must be a <code>ServiceReference</code> provided to the
096 * component via the bind or unbind method for the specified
097 * reference name.
098 * @return A service object for the referenced service or <code>null</code>
099 * if the specified <code>ServiceReference</code> is not a bound
100 * service for the specified reference name.
101 * @throws ComponentException If the Service Component Runtime catches an
102 * exception while activating the bound service.
103 */
104 public Object locateService(String name, ServiceReference reference);
105
106 /**
107 * Returns the service objects for the specified reference name.
108 *
109 * @param name The name of a reference as specified in a
110 * <code>reference</code> element in this component's description.
111 * @return An array of service objects for the referenced service or
112 * <code>null</code> if the reference cardinality is
113 * <code>0..1</code> or <code>0..n</code> and no bound service is
114 * available. If the reference cardinality is <code>0..1</code> or
115 * <code>1..1</code> and a bound service is available, the array
116 * will have exactly one element.
117 * @throws ComponentException If the Service Component Runtime catches an
118 * exception while activating a bound service.
119 */
120 public Object[] locateServices(String name);
121
122 /**
123 * Returns the <code>BundleContext</code> of the bundle which contains this
124 * component.
125 *
126 * @return The <code>BundleContext</code> of the bundle containing this
127 * component.
128 */
129 public BundleContext getBundleContext();
130
131 /**
132 * If the component instance is registered as a service using the
133 * <code>servicefactory="true"</code> attribute, then this method
134 * returns the bundle using the service provided by the component instance.
135 * <p>
136 * This method will return <code>null</code> if:
137 * <ul>
138 * <li>The component instance is not a service, then no bundle can be using
139 * it as a service.
140 * <li>The component instance is a service but did not specify the
141 * <code>servicefactory="true"</code> attribute, then all bundles
142 * using the service provided by the component instance will share the same
143 * component instance.
144 * <li>The service provided by the component instance is not currently being
145 * used by any bundle.
146 * </ul>
147 *
148 * @return The bundle using the component instance as a service or
149 * <code>null</code>.
150 */
151 public Bundle getUsingBundle();
152
153 /**
154 * Returns the Component Instance object for the component instance
155 * associated with this Component Context.
156 *
157 * @return The Component Instance object for the component instance.
158 */
159 public ComponentInstance getComponentInstance();
160
161 /**
162 * Enables the specified component name. The specified component name must
163 * be in the same bundle as this component.
164 *
165 * @param name The name of a component or <code>null</code> to indicate all
166 * components in the bundle.
167 */
168 public void enableComponent(String name);
169
170 /**
171 * Disables the specified component name. The specified component name must
172 * be in the same bundle as this component.
173 *
174 * @param name The name of a component.
175 */
176 public void disableComponent(String name);
177
178 /**
179 * If the component instance is registered as a service using the
180 * <code>service</code> element, then this method returns the service
181 * reference of the service provided by this component instance.
182 * <p>
183 * This method will return <code>null</code> if the component instance is
184 * not registered as a service.
185 *
186 * @return The <code>ServiceReference</code> object for the component
187 * instance or <code>null</code> if the component instance is not
188 * registered as a service.
189 */
190 public ServiceReference getServiceReference();
191 }