Pierre De Rop | 3a00a21 | 2015-03-01 09:27:46 +0000 | [diff] [blame] | 1 | /* |
| 2 | * Licensed to the Apache Software Foundation (ASF) under one |
| 3 | * or more contributor license agreements. See the NOTICE file |
| 4 | * distributed with this work for additional information |
| 5 | * regarding copyright ownership. The ASF licenses this file |
| 6 | * to you under the Apache License, Version 2.0 (the |
| 7 | * "License"); you may not use this file except in compliance |
| 8 | * with the License. You may obtain a copy of the License at |
| 9 | * |
| 10 | * http://www.apache.org/licenses/LICENSE-2.0 |
| 11 | * |
| 12 | * Unless required by applicable law or agreed to in writing, |
| 13 | * software distributed under the License is distributed on an |
| 14 | * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| 15 | * KIND, either express or implied. See the License for the |
| 16 | * specific language governing permissions and limitations |
| 17 | * under the License. |
| 18 | */ |
| 19 | package org.apache.felix.dm.context; |
| 20 | |
Pierre De Rop | 9e5cdba | 2016-02-17 20:35:16 +0000 | [diff] [blame^] | 21 | import java.util.Dictionary; |
Pierre De Rop | 3a00a21 | 2015-03-01 09:27:46 +0000 | [diff] [blame] | 22 | import java.util.List; |
| 23 | import java.util.Set; |
| 24 | import java.util.concurrent.Executor; |
| 25 | |
| 26 | import org.apache.felix.dm.Component; |
| 27 | import org.apache.felix.dm.Logger; |
| 28 | import org.osgi.framework.Bundle; |
| 29 | import org.osgi.framework.BundleContext; |
| 30 | |
Pierre De Rop | c723eb3 | 2015-11-22 21:49:00 +0000 | [diff] [blame] | 31 | import aQute.bnd.annotation.ProviderType; |
| 32 | |
Pierre De Rop | 3a00a21 | 2015-03-01 09:27:46 +0000 | [diff] [blame] | 33 | /** |
| 34 | * This interface is the entry point to the Component implementation context. |
| 35 | * It is used by all DependencyManager Dependency implementations. |
| 36 | * |
| 37 | * @see DependencyContext interface |
| 38 | * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a> |
| 39 | */ |
Pierre De Rop | c723eb3 | 2015-11-22 21:49:00 +0000 | [diff] [blame] | 40 | @ProviderType |
Pierre De Rop | 3a00a21 | 2015-03-01 09:27:46 +0000 | [diff] [blame] | 41 | public interface ComponentContext extends Component { |
| 42 | /** |
Pierre De Rop | c723eb3 | 2015-11-22 21:49:00 +0000 | [diff] [blame] | 43 | * Returns the Component Executor gate that can be used to ensure proper component event serialization. |
| 44 | * When you schedule a task in the component executor, your task is executed safely and you do not need |
| 45 | * to managed synchronization (other external events, like service dependency events) will be queued |
| 46 | * until your task has been executed). |
| 47 | */ |
| 48 | public Executor getExecutor(); |
| 49 | |
| 50 | /** |
Pierre De Rop | 3a00a21 | 2015-03-01 09:27:46 +0000 | [diff] [blame] | 51 | * Returns the logger which can be used by the DependencyManager Dependencies implementations. |
| 52 | */ |
| 53 | public Logger getLogger(); |
| 54 | |
| 55 | /** |
| 56 | * Returns the Component's bundle context |
| 57 | * @return the Component's bundle context |
| 58 | */ |
| 59 | public BundleContext getBundleContext(); |
| 60 | |
| 61 | /** |
| 62 | * Returns the Compoent's bundle. |
| 63 | * @return the Compoent's bundle. |
| 64 | */ |
| 65 | public Bundle getBundle(); |
| 66 | |
| 67 | /** |
| 68 | * Sets a threadpool that the component will use when handling external events |
| 69 | * @param threadPool a threadpool used to handle component events and invoke the component's lifecycle callbacks |
| 70 | */ |
| 71 | public void setThreadPool(Executor threadPool); |
| 72 | |
| 73 | /** |
| 74 | * Starts the component. All initial dependencies previously added to the component will be started. |
| 75 | */ |
| 76 | public void start(); |
| 77 | |
| 78 | /** |
| 79 | * Stops the component. |
| 80 | */ |
| 81 | public void stop(); |
| 82 | |
| 83 | /** |
| 84 | * Is this component already started ? |
| 85 | * @return true if this component has been started |
| 86 | */ |
| 87 | public boolean isActive(); |
| 88 | |
| 89 | /** |
| 90 | * Is this component available (all required dependencies are available) ? |
| 91 | * @return true if this component is available (all dependencies are available), or false |
| 92 | */ |
| 93 | public boolean isAvailable(); |
| 94 | |
| 95 | /** |
| 96 | * Notifies the Component about a dependency event. |
| 97 | * An event is for example fired when:<p> |
| 98 | * <ul> |
| 99 | * <li> a dependency service becomes available {@link EventType#ADDED}) |
| 100 | * <li> a dependenc service has changed is changed {@link EventType#CHANGED}) |
| 101 | * <li> a dependency service has been lost {@link EventType#REMOVED}) |
| 102 | * <li> a dependency service has been swapped by another {@link EventType#SWAPPED}) |
| 103 | * </ul> |
| 104 | * @param dc the dependency |
| 105 | * @param type the dependency event type |
| 106 | * @param e the dependency event |
| 107 | * @see EventType |
| 108 | */ |
| 109 | public void handleEvent(DependencyContext dc, EventType type, Event ... event); |
| 110 | |
| 111 | /** |
| 112 | * Returns the list of dependencies that has been registered on this component |
| 113 | * @return the list of dependencies that has been registered on this component |
| 114 | */ |
| 115 | public List<DependencyContext> getDependencies(); |
| 116 | |
| 117 | /** |
| 118 | * Invoke a component callback method with a given dependency service instance |
| 119 | * @param instances the component instances |
| 120 | * @param methodName the method name |
| 121 | * @param signatures the method signatures (types) |
| 122 | * @param parameters the method parameters |
| 123 | */ |
| 124 | public void invokeCallbackMethod(Object[] instances, String methodName, Class<?>[][] signatures, Object[][] parameters); |
| 125 | |
| 126 | /** |
| 127 | * Returns the component instances |
| 128 | * @return the component instances |
| 129 | */ |
| 130 | public Object[] getInstances(); |
| 131 | |
| 132 | /** |
| 133 | * Returns the component instance field that is assignable to a given class type |
| 134 | * @param clazz the type of an object that has to be injected in the component instance field |
| 135 | * @return the name of the component instance field that can be assigned to an object having the same type as |
| 136 | * the "clazz" parameter |
| 137 | */ |
| 138 | public String getAutoConfigInstance(Class<?> clazz); |
| 139 | |
| 140 | /** |
| 141 | * Indicates if an object of the given class can be injected in one field of the component |
| 142 | * @param clazz the class of an object that has to be injected in one of the component fields |
| 143 | * @return true if the component can be injected with an object having the specified "clazz" type. |
| 144 | */ |
| 145 | public boolean getAutoConfig(Class<?> clazz); |
| 146 | |
| 147 | /** |
| 148 | * Returns the highest ranked dependency service instance for a given dependency |
| 149 | * @param dc the dependency |
| 150 | * @return the highest ranked dependency service instance for a given dependency |
| 151 | */ |
| 152 | public Event getDependencyEvent(DependencyContext dc); |
| 153 | |
| 154 | /** |
| 155 | * Returns all the available dependency services for a given dependency |
| 156 | * @param dc the dependency |
| 157 | * @return all the available dependency services for a given dependency |
| 158 | */ |
| 159 | public Set<Event> getDependencyEvents(DependencyContext dc); |
Pierre De Rop | 9e5cdba | 2016-02-17 20:35:16 +0000 | [diff] [blame^] | 160 | |
| 161 | /** |
| 162 | * Creates a configuration for a given type backed by a given dictionary. |
| 163 | * This method can be used by any custom Dependency Manager dependency that |
| 164 | * needs to expose some configuration through a dynamic proxy interface. |
| 165 | * |
| 166 | * @param type the configuration class, cannot be <code>null</code>; |
| 167 | * @param config the configuration to wrap, cannot be <code>null</code>. |
| 168 | * @return an instance of the given type that wraps the given configuration. |
| 169 | */ |
| 170 | public <T> T createConfigurationProxy(Class<T> type, Dictionary<?, ?> config); |
Pierre De Rop | 3a00a21 | 2015-03-01 09:27:46 +0000 | [diff] [blame] | 171 | } |