Pierre De Rop | ddce586 | 2009-12-04 22:16:48 +0000 | [diff] [blame] | 1 | /* |
| 2 | * Licensed to the Apache Software Foundation (ASF) under one or more contributor license |
| 3 | * agreements. See the NOTICE file distributed with this work for additional information |
| 4 | * regarding copyright ownership. The ASF licenses this file to you under the Apache License, |
| 5 | * Version 2.0 (the "License"); you may not use this file except in compliance with the License. |
| 6 | * You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless |
| 7 | * required by applicable law or agreed to in writing, software distributed under the License is |
| 8 | * distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express |
| 9 | * or implied. See the License for the specific language governing permissions and limitations |
| 10 | * under the License. |
| 11 | */ |
Marcel Offermans | 8b93efa | 2010-07-02 18:27:21 +0000 | [diff] [blame] | 12 | package org.apache.felix.dm; |
Pierre De Rop | ddce586 | 2009-12-04 22:16:48 +0000 | [diff] [blame] | 13 | |
Pierre De Rop | ddce586 | 2009-12-04 22:16:48 +0000 | [diff] [blame] | 14 | /** |
Marcel Offermans | 5be5f14 | 2011-04-26 10:47:12 +0000 | [diff] [blame] | 15 | * A Temporal Service dependency that can block the caller thread between service updates. Only useful for required stateless |
| 16 | * dependencies that can be replaced transparently. A Dynamic Proxy is used to wrap the actual service dependency. When the |
| 17 | * dependency goes away, an attempt is made to replace it with another one which satisfies the service dependency criteria. If |
| 18 | * no service replacement is available, then any method invocation (through the dynamic proxy) will block during a configurable |
| 19 | * timeout. On timeout, an unchecked <code>IllegalStateException</code> exception is raised (but the service is not |
| 20 | * deactivated). |
| 21 | * <p> |
| 22 | * <b>This class only supports required dependencies, and temporal dependencies must be accessed outside the Activator (OSGi) |
| 23 | * thread, because method invocations may block the caller thread when dependencies are not satisfied. </b> |
| 24 | * <p> |
| 25 | * Sample Code: |
| 26 | * <p> |
| 27 | * <blockquote> |
| 28 | * |
| 29 | * <pre> |
| 30 | * import org.apache.felix.dependencymanager.*; |
| 31 | * |
| 32 | * public class Activator extends DependencyActivatorBase { |
| 33 | * public void init(BundleContext ctx, DependencyManager dm) throws Exception { |
| 34 | * dm.add(createService() |
| 35 | * .setImplementation(MyServer.class) |
| 36 | * .add(createTemporalServiceDependency() |
| 37 | * .setTimeout(15000) |
| 38 | * .setService(MyDependency.class))); |
| 39 | * } |
| 40 | * |
| 41 | * public void destroy(BundleContext ctx, DependencyManager dm) throws Exception { |
| 42 | * } |
| 43 | * } |
| 44 | * |
| 45 | * class MyServer implements Runnable { |
| 46 | * MyDependency _dependency; // Auto-Injected by reflection. |
| 47 | * void start() { |
| 48 | * (new Thread(this)).start(); |
| 49 | * } |
| 50 | * |
| 51 | * public void run() { |
| 52 | * try { |
| 53 | * _dependency.doWork(); |
| 54 | * } catch (IllegalStateException e) { |
| 55 | * t.printStackTrace(); |
| 56 | * } |
| 57 | * } |
| 58 | * </pre> |
| 59 | * |
| 60 | * </blockquote> |
| 61 | * |
| 62 | * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a> |
| 63 | */ |
Pierre De Rop | ddce586 | 2009-12-04 22:16:48 +0000 | [diff] [blame] | 64 | public interface TemporalServiceDependency extends ServiceDependency { |
| 65 | /** |
| 66 | * Sets the timeout for this temporal dependency. Specifying a timeout value of zero means that there is no timeout period, |
| 67 | * and an invocation on a missing service will fail immediately. |
| 68 | * |
| 69 | * @param timeout the dependency timeout value greater or equals to 0 |
| 70 | * @throws IllegalArgumentException if the timeout is negative |
| 71 | * @return this temporal dependency |
| 72 | */ |
| 73 | TemporalServiceDependency setTimeout(long timeout); |
| 74 | } |