Mercurial > projects > dwt2

comparison org.eclipse.osgi/osgi/src/org/osgi/framework/ServiceReference.d @ 86:12b890a6392a

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