Richard S. Hall | 930fecc | 2005-08-16 18:33:34 +0000 | [diff] [blame^] | 1 | /* |
| 2 | * $Header: /cvshome/build/org.osgi.framework/src/org/osgi/framework/ServiceFactory.java,v 1.6 2005/05/13 20:32:55 hargrave Exp $ |
| 3 | * |
| 4 | * Copyright (c) OSGi Alliance (2000, 2005). All Rights Reserved. |
| 5 | * |
| 6 | * This program and the accompanying materials are made available under the |
| 7 | * terms of the Eclipse Public License v1.0 which accompanies this |
| 8 | * distribution, and is available at http://www.eclipse.org/legal/epl-v10.html. |
| 9 | */ |
| 10 | |
| 11 | package org.osgi.framework; |
| 12 | |
| 13 | /** |
| 14 | * Allows services to provide customized service objects in the OSGi |
| 15 | * environment. |
| 16 | * |
| 17 | * <p> |
| 18 | * When registering a service, a <code>ServiceFactory</code> object can be used |
| 19 | * instead of a service object, so that the bundle developer can gain control of |
| 20 | * the specific service object granted to a bundle that is using the service. |
| 21 | * |
| 22 | * <p> |
| 23 | * When this happens, the <code>BundleContext.getService(ServiceReference)</code> |
| 24 | * method calls the <code>ServiceFactory.getService</code> method to create a |
| 25 | * service object specifically for the requesting bundle. The service object |
| 26 | * returned by the <code>ServiceFactory</code> object is cached by the Framework |
| 27 | * until the bundle releases its use of the service. |
| 28 | * |
| 29 | * <p> |
| 30 | * When the bundle's use count for the service equals zero (including the bundle |
| 31 | * stopping or the service being unregistered), the |
| 32 | * <code>ServiceFactory.ungetService</code> method is called. |
| 33 | * |
| 34 | * <p> |
| 35 | * <code>ServiceFactory</code> objects are only used by the Framework and are not |
| 36 | * made available to other bundles in the OSGi environment. |
| 37 | * |
| 38 | * @version $Revision: 1.6 $ |
| 39 | * @see BundleContext#getService |
| 40 | */ |
| 41 | |
| 42 | public abstract interface ServiceFactory { |
| 43 | /** |
| 44 | * Creates a new service object. |
| 45 | * |
| 46 | * <p> |
| 47 | * The Framework invokes this method the first time the specified |
| 48 | * <code>bundle</code> requests a service object using the |
| 49 | * <code>BundleContext.getService(ServiceReference)</code> method. The service |
| 50 | * factory can then return a specific service object for each bundle. |
| 51 | * |
| 52 | * <p> |
| 53 | * The Framework caches the value returned (unless it is <code>null</code>), |
| 54 | * and will return the same service object on any future call to |
| 55 | * <code>BundleContext.getService</code> from the same bundle. |
| 56 | * |
| 57 | * <p> |
| 58 | * The Framework will check if the returned service object is an instance of |
| 59 | * all the classes named when the service was registered. If not, then |
| 60 | * <code>null</code> is returned to the bundle. |
| 61 | * |
| 62 | * @param bundle The bundle using the service. |
| 63 | * @param registration The <code>ServiceRegistration</code> object for the |
| 64 | * service. |
| 65 | * @return A service object that <strong>must </strong> be an instance of |
| 66 | * all the classes named when the service was registered. |
| 67 | * @see BundleContext#getService |
| 68 | */ |
| 69 | public abstract Object getService(Bundle bundle, |
| 70 | ServiceRegistration registration); |
| 71 | |
| 72 | /** |
| 73 | * Releases a service object. |
| 74 | * |
| 75 | * <p> |
| 76 | * The Framework invokes this method when a service has been released by a |
| 77 | * bundle. The service object may then be destroyed. |
| 78 | * |
| 79 | * @param bundle The bundle releasing the service. |
| 80 | * @param registration The <code>ServiceRegistration</code> object for the |
| 81 | * service. |
| 82 | * @param service The service object returned by a previous call to the |
| 83 | * <code>ServiceFactory.getService</code> method. |
| 84 | * @see BundleContext#ungetService |
| 85 | */ |
| 86 | public abstract void ungetService(Bundle bundle, |
| 87 | ServiceRegistration registration, Object service); |
| 88 | } |
| 89 | |