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