KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > osgi > framework > ServiceReference


1 /*
2  * $Header: /cvshome/build/org.osgi.framework/src/org/osgi/framework/ServiceReference.java,v 1.20 2007/02/21 16:49:05 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  * A reference to a service.
23  *
24  * <p>
25  * The Framework returns <code>ServiceReference</code> objects from the
26  * <code>BundleContext.getServiceReference</code> and
27  * <code>BundleContext.getServiceReferences</code> methods.
28  * <p>
29  * A <code>ServiceReference</code> object may be shared between bundles and
30  * can be used to examine the properties of the service and to get the service
31  * object.
32  * <p>
33  * Every service registered in the Framework has a unique
34  * <code>ServiceRegistration</code> object and may have multiple, distinct
35  * <code>ServiceReference</code> objects referring to it.
36  * <code>ServiceReference</code> objects associated with a
37  * <code>ServiceRegistration</code> object have the same <code>hashCode</code>
38  * and are considered equal (more specifically, their <code>equals()</code>
39  * method will return <code>true</code> when compared).
40  * <p>
41  * If the same service object is registered multiple times,
42  * <code>ServiceReference</code> objects associated with different
43  * <code>ServiceRegistration</code> objects are not equal.
44  *
45  * @see BundleContext#getServiceReference
46  * @see BundleContext#getServiceReferences
47  * @see BundleContext#getService
48  * @ThreadSafe
49  * @version $Revision: 1.20 $
50  */
51
52 public interface ServiceReference extends Comparable JavaDoc {
53     /**
54      * Returns the property value to which the specified property key is mapped
55      * in the properties <code>Dictionary</code> object of the service
56      * referenced by this <code>ServiceReference</code> object.
57      *
58      * <p>
59      * Property keys are case-insensitive.
60      *
61      * <p>
62      * This method must continue to return property values after the service has
63      * been unregistered. This is so references to unregistered services (for
64      * example, <code>ServiceReference</code> objects stored in the log) can
65      * still be interrogated.
66      *
67      * @param key The property key.
68      * @return The property value to which the key is mapped; <code>null</code>
69      * if there is no property named after the key.
70      */
71     public Object JavaDoc getProperty(String JavaDoc key);
72
73     /**
74      * Returns an array of the keys in the properties <code>Dictionary</code>
75      * object of the service referenced by this <code>ServiceReference</code>
76      * object.
77      *
78      * <p>
79      * This method will continue to return the keys after the service has been
80      * unregistered. This is so references to unregistered services (for
81      * example, <code>ServiceReference</code> objects stored in the log) can
82      * still be interrogated.
83      *
84      * <p>
85      * This method is <i>case-preserving </i>; this means that every key in the
86      * returned array must have the same case as the corresponding key in the
87      * properties <code>Dictionary</code> that was passed to the
88      * {@link BundleContext#registerService(String[],Object,java.util.Dictionary)}
89      * or {@link ServiceRegistration#setProperties} methods.
90      *
91      * @return An array of property keys.
92      */
93     public String JavaDoc[] getPropertyKeys();
94
95     /**
96      * Returns the bundle that registered the service referenced by this
97      * <code>ServiceReference</code> object.
98      *
99      * <p>
100      * This method must return <code>null</code> when the service has been
101      * unregistered. This can be used to determine if the service has been
102      * unregistered.
103      *
104      * @return The bundle that registered the service referenced by this
105      * <code>ServiceReference</code> object; <code>null</code> if
106      * that service has already been unregistered.
107      * @see BundleContext#registerService(String[],Object,java.util.Dictionary)
108      */
109     public Bundle getBundle();
110
111     /**
112      * Returns the bundles that are using the service referenced by this
113      * <code>ServiceReference</code> object. Specifically, this method returns
114      * the bundles whose usage count for that service is greater than zero.
115      *
116      * @return An array of bundles whose usage count for the service referenced
117      * by this <code>ServiceReference</code> object is greater than
118      * zero; <code>null</code> if no bundles are currently using that
119      * service.
120      *
121      * @since 1.1
122      */
123     public Bundle[] getUsingBundles();
124
125     /**
126      * Tests if the bundle that registered the service referenced by this
127      * <code>ServiceReference</code> and the specified bundle use the same
128      * source for the package of the specified class name.
129      * <p>
130      * This method performs the following checks:
131      * <ol>
132      * <li>Get the package name from the specified class name.</li>
133      * <li>For the bundle that registered the service referenced by this
134      * <code>ServiceReference</code> (registrant bundle); find the source for
135      * the package. If no source is found then return <code>true</code> if the
136      * registrant bundle is equal to the specified bundle; otherwise return
137      * <code>false</code>.</li>
138      * <li>If the package source of the registrant bundle is equal to the
139      * package source of the specified bundle then return <code>true</code>;
140      * otherwise return <code>false</code>.</li>
141      * </ol>
142      *
143      * @param bundle The <code>Bundle</code> object to check.
144      * @param className The class name to check.
145      * @return <code>true</code> if the bundle which registered the service
146      * referenced by this <code>ServiceReference</code> and the
147      * specified bundle use the same source for the package of the
148      * specified class name. Otherwise <code>false</code> is returned.
149      *
150      * @since 1.3
151      */
152     public boolean isAssignableTo(Bundle bundle, String JavaDoc className);
153
154     /**
155      * Compares this <code>ServiceReference</code> with the specified
156      * <code>ServiceReference</code> for order.
157      *
158      * <p>
159      * If this <code>ServiceReference</code> and the specified
160      * <code>ServiceReference</code> have the same
161      * {@link Constants#SERVICE_ID service id} they are equal. This
162      * <code>ServiceReference</code> is less than the specified
163      * <code>ServiceReference</code> if it has a lower
164      * {@link Constants#SERVICE_RANKING service ranking} and greater if it has a
165      * higher service ranking. Otherwise, if this <code>ServiceReference</code>
166      * and the specified <code>ServiceReference</code> have the same
167      * {@link Constants#SERVICE_RANKING service ranking}, this
168      * <code>ServiceReference</code> is less than the specified
169      * <code>ServiceReference</code> if it has a higher
170      * {@link Constants#SERVICE_ID service id} and greater if it has a lower
171      * service id.
172      *
173      * @param reference The <code>ServiceReference</code> to be compared.
174      * @return Returns a negative integer, zero, or a positive integer if this
175      * <code>ServiceReference</code> is less than, equal to, or
176      * greater than the specified <code>ServiceReference</code>.
177      * @since 1.4
178      */
179     public int compareTo(Object JavaDoc reference);
180 }
181
Popular Tags