ServiceFactory


1   /*
2    * $Header: /cvshome/build/org.osgi.framework/src/org/osgi/framework/ServiceFactory.java,v 1.10 2007/02/20 00:16:30 hargrave Exp $
3    * 
4    * Copyright (c) OSGi Alliance (2000, 2007). All Rights Reserved.
5    * 
6    * Licensed under the Apache License, Version 2.0 (the "License");
7    * you may not use this file except in compliance with the License.
8    * 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, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  
19  package org.osgi.framework;
20  
21  /**
22   * Allows services to provide customized service objects in the OSGi
23   * environment.
24   * 
25   * <p>
26   * When registering a service, a <code>ServiceFactory</code> object can be
27   * used instead of a service object, so that the bundle developer can gain
28   * control of the specific service object granted to a bundle that is using the
29   * service.
30   * 
31   * <p>
32   * When this happens, the
33   * <code>BundleContext.getService(ServiceReference)</code> method calls the
34   * <code>ServiceFactory.getService</code> method to create a service object
35   * specifically for the requesting bundle. The service object returned by the
36   * <code>ServiceFactory</code> is cached by the Framework until the bundle
37   * releases its use of the service.
38   * 
39   * <p>
40   * When the bundle's use count for the service equals zero (including the bundle
41   * stopping or the service being unregistered), the
42   * <code>ServiceFactory.ungetService</code> method is called.
43   * 
44   * <p>
45   * <code>ServiceFactory</code> objects are only used by the Framework and are
46   * not made available to other bundles in the OSGi environment. The Framework
47   * may concurrently call a <code>ServiceFactory</code>.
48   * 
49   * @see BundleContext#getService
50   * @ThreadSafe
51   * @version $Revision: 1.10 $
52   */
53  
54  public interface ServiceFactory {
55      /**
56       * Creates a new service object.
57       * 
58       * <p>
59       * The Framework invokes this method the first time the specified
60       * <code>bundle</code> requests a service object using the
61       * <code>BundleContext.getService(ServiceReference)</code> method. The
62       * service factory can then return a specific service object for each
63       * bundle.
64       * 
65       * <p>
66       * The Framework caches the value returned (unless it is <code>null</code>),
67       * and will return the same service object on any future call to
68       * <code>BundleContext.getService</code> from the same bundle.
69       * 
70       * <p>
71       * The Framework will check if the returned service object is an instance of
72       * all the classes named when the service was registered. If not, then
73       * <code>null</code> is returned to the bundle.
74       * 
75       * @param bundle The bundle using the service.
76       * @param registration The <code>ServiceRegistration</code> object for the
77       *        service.
78       * @return A service object that <strong>must </strong> be an instance of
79       *         all the classes named when the service was registered.
80       * @see BundleContext#getService
81       */
82      public Object   getService(Bundle bundle, ServiceRegistration registration);
83  
84      /**
85       * Releases a service object.
86       * 
87       * <p>
88       * The Framework invokes this method when a service has been released by a
89       * bundle. The service object may then be destroyed.
90       * 
91       * @param bundle The bundle releasing the service.
92       * @param registration The <code>ServiceRegistration</code> object for the
93       *        service.
94       * @param service The service object returned by a previous call to the
95       *        <code>ServiceFactory.getService</code> method.
96       * @see BundleContext#ungetService
97       */
98      public void ungetService(Bundle bundle, ServiceRegistration registration,
99              Object   service);
100 }
101
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags