KickJava   Java API By Example, From Geeks To Geeks.

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


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