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> |
David Jencks | 13fe7ff | 2015-01-06 16:24:29 +0000 | [diff] [blame^] | 31 | * A component instance may obtain its Component Context object through its |
| 32 | * activate, modified, and deactivate methods. |
David Jencks | 9c8e4b1 | 2014-11-21 22:13:59 +0000 | [diff] [blame] | 33 | * |
| 34 | * @ThreadSafe |
David Jencks | 13fe7ff | 2015-01-06 16:24:29 +0000 | [diff] [blame^] | 35 | * @author $Id: 5499691841bcfbb0d35222564785af1a5a530c7f $ |
David Jencks | 9c8e4b1 | 2014-11-21 22:13:59 +0000 | [diff] [blame] | 36 | */ |
| 37 | @ProviderType |
| 38 | public interface ComponentContext { |
| 39 | /** |
| 40 | * Returns the component properties for this Component Context. |
| 41 | * |
| 42 | * @return The properties for this Component Context. The Dictionary is read |
| 43 | * only and cannot be modified. |
| 44 | */ |
| 45 | public Dictionary<String, Object> getProperties(); |
| 46 | |
| 47 | /** |
| 48 | * Returns the service object for the specified reference name. |
| 49 | * |
| 50 | * <p> |
| 51 | * If the cardinality of the reference is {@code 0..n} or {@code 1..n} and |
| 52 | * multiple services are bound to the reference, the service with the |
| 53 | * highest ranking (as specified in its {@code Constants.SERVICE_RANKING} |
| 54 | * property) is returned. If there is a tie in ranking, the service with the |
| 55 | * lowest service id (as specified in its {@code Constants.SERVICE_ID} |
| 56 | * property); that is, the service that was registered first is returned. |
| 57 | * |
| 58 | * @param name The name of a reference as specified in a {@code reference} |
| 59 | * element in this component's description. |
| 60 | * @return A service object for the referenced service or {@code null} if |
| 61 | * the reference cardinality is {@code 0..1} or {@code 0..n} and no |
| 62 | * bound service is available. |
| 63 | * @throws ComponentException If Service Component Runtime catches an |
| 64 | * exception while activating the bound service. |
| 65 | */ |
| 66 | public Object locateService(String name); |
| 67 | |
| 68 | /** |
| 69 | * Returns the service object for the specified reference name and |
| 70 | * {@code ServiceReference}. |
| 71 | * |
| 72 | * @param <S> Type of Service. |
| 73 | * @param name The name of a reference as specified in a {@code reference} |
| 74 | * element in this component's description. |
| 75 | * @param reference The {@code ServiceReference} to a bound service. This |
| 76 | * must be a {@code ServiceReference} provided to the component via |
| 77 | * the bind or unbind method for the specified reference name. |
| 78 | * @return A service object for the referenced service or {@code null} if |
| 79 | * the specified {@code ServiceReference} is not a bound service for |
| 80 | * the specified reference name. |
| 81 | * @throws ComponentException If Service Component Runtime catches an |
| 82 | * exception while activating the bound service. |
| 83 | */ |
| 84 | public <S> S locateService(String name, ServiceReference<S> reference); |
| 85 | |
| 86 | /** |
| 87 | * Returns the service objects for the specified reference name. |
| 88 | * |
| 89 | * @param name The name of a reference as specified in a {@code reference} |
| 90 | * element in this component's description. |
| 91 | * @return An array of service objects for the referenced service or |
| 92 | * {@code null} if the reference cardinality is {@code 0..1} or |
| 93 | * {@code 0..n} and no bound service is available. If the reference |
| 94 | * cardinality is {@code 0..1} or {@code 1..1} and a bound service |
| 95 | * is available, the array will have exactly one element. |
| 96 | * @throws ComponentException If Service Component Runtime catches an |
| 97 | * exception while activating a bound service. |
| 98 | */ |
| 99 | public Object[] locateServices(String name); |
| 100 | |
| 101 | /** |
| 102 | * Returns the {@code BundleContext} of the bundle which contains this |
| 103 | * component. |
| 104 | * |
| 105 | * @return The {@code BundleContext} of the bundle containing this |
| 106 | * component. |
| 107 | */ |
| 108 | public BundleContext getBundleContext(); |
| 109 | |
| 110 | /** |
| 111 | * If the component instance is registered as a service using the |
| 112 | * {@code servicescope="bundle"} or {@code servicescope="prototype"} |
| 113 | * attribute, then this method returns the bundle using the service provided |
| 114 | * by the component instance. |
| 115 | * <p> |
| 116 | * This method will return {@code null} if: |
| 117 | * <ul> |
| 118 | * <li>The component instance is not a service, then no bundle can be using |
| 119 | * it as a service.</li> |
| 120 | * <li>The component instance is a service but did not specify the |
| 121 | * {@code servicescope="bundle"} or {@code servicescope="prototype"} |
| 122 | * attribute, then all bundles using the service provided by the component |
| 123 | * instance will share the same component instance.</li> |
| 124 | * <li>The service provided by the component instance is not currently being |
| 125 | * used by any bundle.</li> |
| 126 | * </ul> |
| 127 | * |
| 128 | * @return The bundle using the component instance as a service or |
| 129 | * {@code null}. |
| 130 | */ |
| 131 | public Bundle getUsingBundle(); |
| 132 | |
| 133 | /** |
| 134 | * Returns the Component Instance object for the component instance |
| 135 | * associated with this Component Context. |
| 136 | * |
| 137 | * @return The Component Instance object for the component instance. |
| 138 | */ |
| 139 | public ComponentInstance getComponentInstance(); |
| 140 | |
| 141 | /** |
| 142 | * Enables the specified component name. The specified component name must |
| 143 | * be in the same bundle as this component. |
| 144 | * |
| 145 | * <p> |
| 146 | * This method must return after changing the enabled state of the specified |
| 147 | * component name. Any actions that result from this, such as activating or |
| 148 | * deactivating a component configuration, must occur asynchronously to this |
| 149 | * method call. |
| 150 | * |
| 151 | * @param name The name of a component or {@code null} to indicate all |
| 152 | * components in the bundle. |
| 153 | */ |
| 154 | public void enableComponent(String name); |
| 155 | |
| 156 | /** |
| 157 | * Disables the specified component name. The specified component name must |
| 158 | * be in the same bundle as this component. |
| 159 | * |
| 160 | * <p> |
| 161 | * This method must return after changing the enabled state of the specified |
| 162 | * component name. Any actions that result from this, such as activating or |
| 163 | * deactivating a component configuration, must occur asynchronously to this |
| 164 | * method call. |
| 165 | * |
| 166 | * @param name The name of a component. |
| 167 | */ |
| 168 | public void disableComponent(String name); |
| 169 | |
| 170 | /** |
| 171 | * If the component instance is registered as a service using the |
| 172 | * {@code service} element, then this method returns the service reference |
| 173 | * of the service provided by this component instance. |
| 174 | * <p> |
| 175 | * This method will return {@code null} if the component instance is not |
| 176 | * registered as a service. |
| 177 | * |
| 178 | * @return The {@code ServiceReference} object for the component instance or |
| 179 | * {@code null} if the component instance is not registered as a |
| 180 | * service. |
| 181 | */ |
| 182 | public ServiceReference<?> getServiceReference(); |
| 183 | } |