David Jencks | 9c8e4b1 | 2014-11-21 22:13:59 +0000 | [diff] [blame] | 1 | /* |
| 2 | * Copyright (c) OSGi Alliance (2004, 2014). All Rights Reserved. |
| 3 | * |
| 4 | * Licensed under the Apache License, Version 2.0 (the "License"); |
| 5 | * you may not use this file except in compliance with the License. |
| 6 | * You may obtain a copy of the License at |
| 7 | * |
| 8 | * http://www.apache.org/licenses/LICENSE-2.0 |
| 9 | * |
| 10 | * Unless required by applicable law or agreed to in writing, software |
| 11 | * distributed under the License is distributed on an "AS IS" BASIS, |
| 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 13 | * See the License for the specific language governing permissions and |
| 14 | * limitations under the License. |
| 15 | */ |
| 16 | |
| 17 | package org.osgi.service.component; |
| 18 | |
| 19 | import java.util.Dictionary; |
| 20 | import org.osgi.annotation.versioning.ProviderType; |
| 21 | import org.osgi.framework.Bundle; |
| 22 | import org.osgi.framework.BundleContext; |
| 23 | import org.osgi.framework.ServiceReference; |
| 24 | |
| 25 | /** |
| 26 | * A Component Context object is used by a component instance to interact with |
| 27 | * its execution context including locating services by reference name. Each |
| 28 | * component instance has a unique Component Context. |
| 29 | * |
| 30 | * <p> |
| 31 | * A component instance may have an activate method. If a component instance has |
| 32 | * a suitable and accessible activate method, this method will be called when a |
| 33 | * component configuration is activated. If the activate method takes a |
| 34 | * {@code ComponentContext} argument, it will be passed the component instance's |
| 35 | * Component Context object. If the activate method takes a |
| 36 | * {@code BundleContext} argument, it will be passed the component instance's |
| 37 | * Bundle Context object. If the activate method takes a {@code Map} argument, |
| 38 | * it will be passed an unmodifiable Map containing the component properties. |
| 39 | * |
| 40 | * <p> |
| 41 | * A component instance may have a deactivate method. If a component instance |
| 42 | * has a suitable and accessible deactivate method, this method will be called |
| 43 | * when the component configuration is deactivated. If the deactivate method |
| 44 | * takes a {@code ComponentContext} argument, it will be passed the component |
| 45 | * instance's Component Context object. If the deactivate method takes a |
| 46 | * {@code BundleContext} argument, it will be passed the component instance's |
| 47 | * Bundle Context object. If the deactivate method takes a {@code Map} argument, |
| 48 | * it will be passed an unmodifiable Map containing the component properties. If |
| 49 | * the deactivate method takes an {@code int} or {@code Integer} argument, it |
| 50 | * will be passed the reason code for the component instance's deactivation. |
| 51 | * |
| 52 | * @ThreadSafe |
| 53 | * @author $Id: 8d2c1ae7d15b9ae109ce4e3e1b0dfae987d137e0 $ |
| 54 | */ |
| 55 | @ProviderType |
| 56 | public interface ComponentContext { |
| 57 | /** |
| 58 | * Returns the component properties for this Component Context. |
| 59 | * |
| 60 | * @return The properties for this Component Context. The Dictionary is read |
| 61 | * only and cannot be modified. |
| 62 | */ |
| 63 | public Dictionary<String, Object> getProperties(); |
| 64 | |
| 65 | /** |
| 66 | * Returns the service object for the specified reference name. |
| 67 | * |
| 68 | * <p> |
| 69 | * If the cardinality of the reference is {@code 0..n} or {@code 1..n} and |
| 70 | * multiple services are bound to the reference, the service with the |
| 71 | * highest ranking (as specified in its {@code Constants.SERVICE_RANKING} |
| 72 | * property) is returned. If there is a tie in ranking, the service with the |
| 73 | * lowest service id (as specified in its {@code Constants.SERVICE_ID} |
| 74 | * property); that is, the service that was registered first is returned. |
| 75 | * |
| 76 | * @param name The name of a reference as specified in a {@code reference} |
| 77 | * element in this component's description. |
| 78 | * @return A service object for the referenced service or {@code null} if |
| 79 | * the reference cardinality is {@code 0..1} or {@code 0..n} and no |
| 80 | * bound service is available. |
| 81 | * @throws ComponentException If Service Component Runtime catches an |
| 82 | * exception while activating the bound service. |
| 83 | */ |
| 84 | public Object locateService(String name); |
| 85 | |
| 86 | /** |
| 87 | * Returns the service object for the specified reference name and |
| 88 | * {@code ServiceReference}. |
| 89 | * |
| 90 | * @param <S> Type of Service. |
| 91 | * @param name The name of a reference as specified in a {@code reference} |
| 92 | * element in this component's description. |
| 93 | * @param reference The {@code ServiceReference} to a bound service. This |
| 94 | * must be a {@code ServiceReference} provided to the component via |
| 95 | * the bind or unbind method for the specified reference name. |
| 96 | * @return A service object for the referenced service or {@code null} if |
| 97 | * the specified {@code ServiceReference} is not a bound service for |
| 98 | * the specified reference name. |
| 99 | * @throws ComponentException If Service Component Runtime catches an |
| 100 | * exception while activating the bound service. |
| 101 | */ |
| 102 | public <S> S locateService(String name, ServiceReference<S> reference); |
| 103 | |
| 104 | /** |
| 105 | * Returns the service objects for the specified reference name. |
| 106 | * |
| 107 | * @param name The name of a reference as specified in a {@code reference} |
| 108 | * element in this component's description. |
| 109 | * @return An array of service objects for the referenced service or |
| 110 | * {@code null} if the reference cardinality is {@code 0..1} or |
| 111 | * {@code 0..n} and no bound service is available. If the reference |
| 112 | * cardinality is {@code 0..1} or {@code 1..1} and a bound service |
| 113 | * is available, the array will have exactly one element. |
| 114 | * @throws ComponentException If Service Component Runtime catches an |
| 115 | * exception while activating a bound service. |
| 116 | */ |
| 117 | public Object[] locateServices(String name); |
| 118 | |
| 119 | /** |
| 120 | * Returns the {@code BundleContext} of the bundle which contains this |
| 121 | * component. |
| 122 | * |
| 123 | * @return The {@code BundleContext} of the bundle containing this |
| 124 | * component. |
| 125 | */ |
| 126 | public BundleContext getBundleContext(); |
| 127 | |
| 128 | /** |
| 129 | * If the component instance is registered as a service using the |
| 130 | * {@code servicescope="bundle"} or {@code servicescope="prototype"} |
| 131 | * attribute, then this method returns the bundle using the service provided |
| 132 | * by the component instance. |
| 133 | * <p> |
| 134 | * This method will return {@code null} if: |
| 135 | * <ul> |
| 136 | * <li>The component instance is not a service, then no bundle can be using |
| 137 | * it as a service.</li> |
| 138 | * <li>The component instance is a service but did not specify the |
| 139 | * {@code servicescope="bundle"} or {@code servicescope="prototype"} |
| 140 | * attribute, then all bundles using the service provided by the component |
| 141 | * instance will share the same component instance.</li> |
| 142 | * <li>The service provided by the component instance is not currently being |
| 143 | * used by any bundle.</li> |
| 144 | * </ul> |
| 145 | * |
| 146 | * @return The bundle using the component instance as a service or |
| 147 | * {@code null}. |
| 148 | */ |
| 149 | public Bundle getUsingBundle(); |
| 150 | |
| 151 | /** |
| 152 | * Returns the Component Instance object for the component instance |
| 153 | * associated with this Component Context. |
| 154 | * |
| 155 | * @return The Component Instance object for the component instance. |
| 156 | */ |
| 157 | public ComponentInstance getComponentInstance(); |
| 158 | |
| 159 | /** |
| 160 | * Enables the specified component name. The specified component name must |
| 161 | * be in the same bundle as this component. |
| 162 | * |
| 163 | * <p> |
| 164 | * This method must return after changing the enabled state of the specified |
| 165 | * component name. Any actions that result from this, such as activating or |
| 166 | * deactivating a component configuration, must occur asynchronously to this |
| 167 | * method call. |
| 168 | * |
| 169 | * @param name The name of a component or {@code null} to indicate all |
| 170 | * components in the bundle. |
| 171 | */ |
| 172 | public void enableComponent(String name); |
| 173 | |
| 174 | /** |
| 175 | * Disables the specified component name. The specified component name must |
| 176 | * be in the same bundle as this component. |
| 177 | * |
| 178 | * <p> |
| 179 | * This method must return after changing the enabled state of the specified |
| 180 | * component name. Any actions that result from this, such as activating or |
| 181 | * deactivating a component configuration, must occur asynchronously to this |
| 182 | * method call. |
| 183 | * |
| 184 | * @param name The name of a component. |
| 185 | */ |
| 186 | public void disableComponent(String name); |
| 187 | |
| 188 | /** |
| 189 | * If the component instance is registered as a service using the |
| 190 | * {@code service} element, then this method returns the service reference |
| 191 | * of the service provided by this component instance. |
| 192 | * <p> |
| 193 | * This method will return {@code null} if the component instance is not |
| 194 | * registered as a service. |
| 195 | * |
| 196 | * @return The {@code ServiceReference} object for the component instance or |
| 197 | * {@code null} if the component instance is not registered as a |
| 198 | * service. |
| 199 | */ |
| 200 | public ServiceReference<?> getServiceReference(); |
| 201 | } |