org.osgi.framework.ServiceReference Maven / Gradle / Ivy
/*
* Copyright (c) OSGi Alliance (2000, 2009). All Rights Reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.osgi.framework;
import java.util.Dictionary;
/**
* A reference to a service.
*
*
* The Framework returns ServiceReference objects from the
* BundleContext.getServiceReference and
* BundleContext.getServiceReferences methods.
*
* A ServiceReference object may be shared between bundles and
* can be used to examine the properties of the service and to get the service
* object.
*
* Every service registered in the Framework has a unique
* ServiceRegistration object and may have multiple, distinct
* ServiceReference objects referring to it.
* ServiceReference objects associated with a
* ServiceRegistration object have the same hashCode
* and are considered equal (more specifically, their equals()
* method will return true when compared).
*
* If the same service object is registered multiple times,
* ServiceReference objects associated with different
* ServiceRegistration objects are not equal.
*
* @see BundleContext#getServiceReference
* @see BundleContext#getServiceReferences
* @see BundleContext#getService
* @ThreadSafe
* @version $Revision: 6374 $
*/
public interface ServiceReference extends Comparable {
/**
* Returns the property value to which the specified property key is mapped
* in the properties Dictionary object of the service
* referenced by this ServiceReference object.
*
*
* Property keys are case-insensitive.
*
*
* This method must continue to return property values after the service has
* been unregistered. This is so references to unregistered services (for
* example, ServiceReference objects stored in the log) can
* still be interrogated.
*
* @param key The property key.
* @return The property value to which the key is mapped; null
* if there is no property named after the key.
*/
public Object getProperty(String key);
/**
* Returns an array of the keys in the properties Dictionary
* object of the service referenced by this ServiceReference
* object.
*
*
* This method will continue to return the keys after the service has been
* unregistered. This is so references to unregistered services (for
* example, ServiceReference objects stored in the log) can
* still be interrogated.
*
*
* This method is case-preserving ; this means that every key in the
* returned array must have the same case as the corresponding key in the
* properties Dictionary that was passed to the
* {@link BundleContext#registerService(String[],Object,Dictionary)} or
* {@link ServiceRegistration#setProperties} methods.
*
* @return An array of property keys.
*/
public String[] getPropertyKeys();
/**
* Returns the bundle that registered the service referenced by this
* ServiceReference object.
*
*
* This method must return null when the service has been
* unregistered. This can be used to determine if the service has been
* unregistered.
*
* @return The bundle that registered the service referenced by this
* ServiceReference object; null if that
* service has already been unregistered.
* @see BundleContext#registerService(String[],Object,Dictionary)
*/
public Bundle getBundle();
/**
* Returns the bundles that are using the service referenced by this
* ServiceReference object. Specifically, this method returns
* the bundles whose usage count for that service is greater than zero.
*
* @return An array of bundles whose usage count for the service referenced
* by this ServiceReference object is greater than
* zero; null if no bundles are currently using that
* service.
*
* @since 1.1
*/
public Bundle[] getUsingBundles();
/**
* Tests if the bundle that registered the service referenced by this
* ServiceReference and the specified bundle use the same
* source for the package of the specified class name.
*
* This method performs the following checks:
*
* - Get the package name from the specified class name.
* - For the bundle that registered the service referenced by this
*
ServiceReference (registrant bundle); find the source for
* the package. If no source is found then return true if the
* registrant bundle is equal to the specified bundle; otherwise return
* false.
* - If the package source of the registrant bundle is equal to the
* package source of the specified bundle then return
true;
* otherwise return false.
*
*
* @param bundle The Bundle object to check.
* @param className The class name to check.
* @return true if the bundle which registered the service
* referenced by this ServiceReference and the
* specified bundle use the same source for the package of the
* specified class name. Otherwise false is returned.
* @throws IllegalArgumentException If the specified Bundle was
* not created by the same framework instance as this
* ServiceReference.
* @since 1.3
*/
public boolean isAssignableTo(Bundle bundle, String className);
/**
* Compares this ServiceReference with the specified
* ServiceReference for order.
*
*
* If this ServiceReference and the specified
* ServiceReference have the same {@link Constants#SERVICE_ID
* service id} they are equal. This ServiceReference is less
* than the specified ServiceReference if it has a lower
* {@link Constants#SERVICE_RANKING service ranking} and greater if it has a
* higher service ranking. Otherwise, if this ServiceReference
* and the specified ServiceReference have the same
* {@link Constants#SERVICE_RANKING service ranking}, this
* ServiceReference is less than the specified
* ServiceReference if it has a higher
* {@link Constants#SERVICE_ID service id} and greater if it has a lower
* service id.
*
* @param reference The ServiceReference to be compared.
* @return Returns a negative integer, zero, or a positive integer if this
* ServiceReference is less than, equal to, or greater
* than the specified ServiceReference.
* @throws IllegalArgumentException If the specified
* ServiceReference was not created by the same
* framework instance as this ServiceReference.
* @since 1.4
*/
public int compareTo(Object reference);
}