|
86
|
1 /*
|
|
|
2 * $Header: /cvshome/build/org.osgi.framework/src/org/osgi/framework/ServiceRegistration.java,v 1.14 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.ServiceRegistration;
|
|
|
22
|
|
|
23 import java.lang.all;
|
|
105
|
24
|
|
|
25 import org.osgi.framework.ServiceReference; // packageimport
|
|
|
26
|
|
86
|
27 import java.util.Dictionary;
|
|
|
28
|
|
|
29 /**
|
|
|
30 * A registered service.
|
|
105
|
31 *
|
|
86
|
32 * <p>
|
|
|
33 * The Framework returns a <code>ServiceRegistration</code> object when a
|
|
|
34 * <code>BundleContext.registerService</code> method invocation is successful.
|
|
|
35 * The <code>ServiceRegistration</code> object is for the private use of the
|
|
|
36 * registering bundle and should not be shared with other bundles.
|
|
|
37 * <p>
|
|
|
38 * The <code>ServiceRegistration</code> object may be used to update the
|
|
|
39 * properties of the service or to unregister the service.
|
|
105
|
40 *
|
|
86
|
41 * @see BundleContext#registerService(String[],Object,Dictionary)
|
|
|
42 * @ThreadSafe
|
|
|
43 * @version $Revision: 1.14 $
|
|
|
44 */
|
|
|
45
|
|
|
46 public interface ServiceRegistration {
|
|
|
47 /**
|
|
|
48 * Returns a <code>ServiceReference</code> object for a service being
|
|
|
49 * registered.
|
|
|
50 * <p>
|
|
|
51 * The <code>ServiceReference</code> object may be shared with other
|
|
|
52 * bundles.
|
|
105
|
53 *
|
|
86
|
54 * @throws java.lang.IllegalStateException If this
|
|
|
55 * <code>ServiceRegistration</code> object has already been
|
|
|
56 * unregistered.
|
|
|
57 * @return <code>ServiceReference</code> object.
|
|
|
58 */
|
|
|
59 public ServiceReference getReference();
|
|
|
60
|
|
|
61 /**
|
|
|
62 * Updates the properties associated with a service.
|
|
105
|
63 *
|
|
86
|
64 * <p>
|
|
|
65 * The {@link Constants#OBJECTCLASS} and {@link Constants#SERVICE_ID} keys
|
|
|
66 * cannot be modified by this method. These values are set by the Framework
|
|
|
67 * when the service is registered in the OSGi environment.
|
|
105
|
68 *
|
|
86
|
69 * <p>
|
|
|
70 * The following steps are required to modify service properties:
|
|
|
71 * <ol>
|
|
|
72 * <li>The service's properties are replaced with the provided properties.
|
|
|
73 * <li>A service event of type {@link ServiceEvent#MODIFIED} is
|
|
|
74 * fired.
|
|
|
75 * </ol>
|
|
105
|
76 *
|
|
86
|
77 * @param properties The properties for this service. See {@link Constants}
|
|
|
78 * for a list of standard service property keys. Changes should not
|
|
|
79 * be made to this object after calling this method. To update the
|
|
|
80 * service's properties this method should be called again.
|
|
105
|
81 *
|
|
86
|
82 * @throws IllegalStateException If this <code>ServiceRegistration</code>
|
|
|
83 * object has already been unregistered.
|
|
|
84 * @throws IllegalArgumentException If <code>properties</code> contains
|
|
|
85 * case variants of the same key name.
|
|
|
86 */
|
|
|
87 public void setProperties(Dictionary properties);
|
|
|
88
|
|
|
89 /**
|
|
|
90 * Unregisters a service. Remove a <code>ServiceRegistration</code> object
|
|
|
91 * from the Framework service registry. All <code>ServiceReference</code>
|
|
|
92 * objects associated with this <code>ServiceRegistration</code> object
|
|
|
93 * can no longer be used to interact with the service.
|
|
105
|
94 *
|
|
86
|
95 * <p>
|
|
|
96 * The following steps are required to unregister a service:
|
|
|
97 * <ol>
|
|
|
98 * <li>The service is removed from the Framework service registry so that
|
|
|
99 * it can no longer be used. <code>ServiceReference</code> objects for the
|
|
|
100 * service may no longer be used to get a service object for the service.
|
|
|
101 * <li>A service event of type {@link ServiceEvent#UNREGISTERING} is
|
|
|
102 * fired so that bundles using this service can release their
|
|
|
103 * use of it.
|
|
|
104 * <li>For each bundle whose use count for this service is greater than
|
|
|
105 * zero: <br>
|
|
|
106 * The bundle's use count for this service is set to zero. <br>
|
|
|
107 * If the service was registered with a {@link ServiceFactory} object, the
|
|
|
108 * <code>ServiceFactory.ungetService</code> method is called to release
|
|
|
109 * the service object for the bundle.
|
|
|
110 * </ol>
|
|
105
|
111 *
|
|
86
|
112 * @throws java.lang.IllegalStateException If this
|
|
|
113 * <code>ServiceRegistration</code> object has already been
|
|
|
114 * unregistered.
|
|
|
115 * @see BundleContext#ungetService
|
|
|
116 * @see ServiceFactory#ungetService
|
|
|
117 */
|
|
|
118 public void unregister();
|
|
|
119 }
|
