KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > osgi > util > tracker > ServiceTrackerCustomizer


1 /*
2  * $Header: /cvshome/build/org.osgi.util.tracker/src/org/osgi/util/tracker/ServiceTrackerCustomizer.java,v 1.13 2007/02/19 19:04:33 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.util.tracker;
20
21 import org.osgi.framework.ServiceReference;
22
23 /**
24  * The <code>ServiceTrackerCustomizer</code> interface allows a
25  * <code>ServiceTracker</code> object to customize the service objects that
26  * are tracked. The <code>ServiceTrackerCustomizer</code> object is called
27  * when a service is being added to the <code>ServiceTracker</code> object.
28  * The <code>ServiceTrackerCustomizer</code> can then return an object for the
29  * tracked service. The <code>ServiceTrackerCustomizer</code> object is also
30  * called when a tracked service is modified or has been removed from the
31  * <code>ServiceTracker</code> object.
32  *
33  * <p>
34  * The methods in this interface may be called as the result of a
35  * <code>ServiceEvent</code> being received by a <code>ServiceTracker</code>
36  * object. Since <code>ServiceEvent</code> s are synchronously delivered by
37  * the Framework, it is highly recommended that implementations of these methods
38  * do not register (<code>BundleContext.registerService</code>), modify (
39  * <code>ServiceRegistration.setProperties</code>) or unregister (
40  * <code>ServiceRegistration.unregister</code>) a service while being
41  * synchronized on any object.
42  *
43  * <p>
44  * The <code>ServiceTracker</code> class is thread-safe. It does not call a
45  * <code>ServiceTrackerCustomizer</code> object while holding any locks.
46  * <code>ServiceTrackerCustomizer</code> implementations must also be
47  * thread-safe.
48  *
49  * @ThreadSafe
50  * @version $Revision: 1.13 $
51  */
52 public interface ServiceTrackerCustomizer {
53     /**
54      * A service is being added to the <code>ServiceTracker</code> object.
55      *
56      * <p>
57      * This method is called before a service which matched the search
58      * parameters of the <code>ServiceTracker</code> object is added to it.
59      * This method should return the service object to be tracked for this
60      * <code>ServiceReference</code> object. The returned service object is
61      * stored in the <code>ServiceTracker</code> object and is available from
62      * the <code>getService</code> and <code>getServices</code> methods.
63      *
64      * @param reference Reference to service being added to the
65      * <code>ServiceTracker</code> object.
66      * @return The service object to be tracked for the
67      * <code>ServiceReference</code> object or <code>null</code> if
68      * the <code>ServiceReference</code> object should not be tracked.
69      */
70     public Object JavaDoc addingService(ServiceReference reference);
71
72     /**
73      * A service tracked by the <code>ServiceTracker</code> object has been
74      * modified.
75      *
76      * <p>
77      * This method is called when a service being tracked by the
78      * <code>ServiceTracker</code> object has had it properties modified.
79      *
80      * @param reference Reference to service that has been modified.
81      * @param service The service object for the modified service.
82      */
83     public void modifiedService(ServiceReference reference, Object JavaDoc service);
84
85     /**
86      * A service tracked by the <code>ServiceTracker</code> object has been
87      * removed.
88      *
89      * <p>
90      * This method is called after a service is no longer being tracked by the
91      * <code>ServiceTracker</code> object.
92      *
93      * @param reference Reference to service that has been removed.
94      * @param service The service object for the removed service.
95      */
96     public void removedService(ServiceReference reference, Object JavaDoc service);
97 }
98
Popular Tags