OSGi 8.1.0 · org.osgi.framework.ServiceReference · APIdia, the JavaDoc alternative

Method Summary

Modifier and Type	Method and Description
public < The type to which this `ServiceReference` object is to be adapted. A> A	Returns: The object, of the specified type, to which this `ServiceReference` object has been adapted or `null` if this `ServiceReference` object cannot be adapted to the specified type. adapt(Class<A> Class object for the type to which this `ServiceReference` object is to be adapted. type) Adapt this `ServiceReference` object to the specified type.
public int	Returns: Returns a negative integer, zero, or a positive integer if this `ServiceReference` is less than, equal to, or greater than the specified `ServiceReference`. compareTo(Object The `ServiceReference` to be compared. reference) Redeclares java.lang.Comparable.compareTo. Compares this `ServiceReference` with the specified `ServiceReference` for order.
public Bundle	Returns: The bundle that registered the service referenced by this `ServiceReference` object; `null` if that service has already been unregistered. getBundle() Redeclares org.osgi.framework.BundleReference.getBundle. Returns the bundle that registered the service referenced by this `ServiceReference` object.
public Dictionary<String, Object>	Returns: A copy of the properties of the service referenced by this `ServiceReference` object getProperties() Returns a copy of the properties of the service referenced by this `ServiceReference` object.
public Object	Returns: The property value to which the key is mapped; `null` if there is no property named after the key. getProperty(String The property key. key) 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.
public String[]	Returns: An array of property keys. getPropertyKeys() Returns an array of the keys in the properties `Dictionary` object of the service referenced by this `ServiceReference` object.
public Bundle[]	Returns: 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. getUsingBundles() Returns the bundles that are using the service referenced by this `ServiceReference` object.
public boolean	Returns: `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. isAssignableTo(Bundle The `Bundle` object to check. bundle, String The class name to check. className) 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.

Method Detail

adapt back to summary

adapt	back to summary
public <A> A adapt(Class<A> type) Adapt this `ServiceReference` object to the specified type. Adapting this `ServiceReference` object to the specified type may require certain checks, including security checks, to succeed. If a check does not succeed, then this `ServiceReference` object cannot be adapted and `null` is returned. Parameters <A> The type to which this `ServiceReference` object is to be adapted. type:Class<A> Class object for the type to which this `ServiceReference` object is to be adapted. Returns:A The object, of the specified type, to which this `ServiceReference` object has been adapted or `null` if this `ServiceReference` object cannot be adapted to the specified type. Exceptions SecurityException: If the caller does not have the appropriate `AdaptPermission[type,this,ADAPT]`, and the Java Runtime Environment supports permissions. Since 1.10

public <A> A adapt(Class<A> type)

Adapt this ServiceReference object to the specified type.

Adapting this ServiceReference object to the specified type may require certain checks, including security checks, to succeed. If a check does not succeed, then this ServiceReference object cannot be adapted and null is returned.

Parameters

<A>: The type to which this ServiceReference object is to be adapted.
type:Class<A>: Class object for the type to which this ServiceReference object is to be adapted.

Returns:A

The object, of the specified type, to which this ServiceReference object has been adapted or null if this ServiceReference object cannot be adapted to the specified type.

Exceptions

SecurityException:: If the caller does not have the appropriate AdaptPermission[type,this,ADAPT], and the Java Runtime Environment supports permissions.

Since

1.10

compareTo back to summary

compareTo	back to summary
public int compareTo(Object reference) Redeclares java.lang.Comparable.compareTo. Compares this `ServiceReference` with the specified `ServiceReference` for order. If this `ServiceReference` and the specified `ServiceReference` have the same `service id` they are equal. This `ServiceReference` is less than the specified `ServiceReference` if it has a lower `service ranking` and greater if it has a higher service ranking. Otherwise, if this `ServiceReference` and the specified `ServiceReference` have the same `service ranking`, this `ServiceReference` is less than the specified `ServiceReference` if it has a higher `service id` and greater if it has a lower service id. Parameters reference:Object The `ServiceReference` to be compared. Returns:int Returns a negative integer, zero, or a positive integer if this `ServiceReference` is less than, equal to, or greater than the specified `ServiceReference`. Annotations @Override Exceptions IllegalArgumentException: If the specified `ServiceReference` was not created by the same framework instance as this `ServiceReference`. Since 1.4

public int compareTo(Object reference)

Redeclares java.lang.Comparable.compareTo.

Compares this ServiceReference with the specified ServiceReference for order.

If this ServiceReference and the specified ServiceReference have the same service id they are equal. This ServiceReference is less than the specified ServiceReference if it has a lower service ranking and greater if it has a higher service ranking. Otherwise, if this ServiceReference and the specified ServiceReference have the same service ranking, this ServiceReference is less than the specified ServiceReference if it has a higher service id and greater if it has a lower service id.

Parameters

reference:Object: The ServiceReference to be compared.

Returns:int

Returns a negative integer, zero, or a positive integer if this ServiceReference is less than, equal to, or greater than the specified ServiceReference.

Annotations

@Override

Exceptions

IllegalArgumentException:: If the specified ServiceReference was not created by the same framework instance as this ServiceReference.

Since

1.4

getBundle back to summary

getBundle	back to summary
public Bundle getBundle() Redeclares org.osgi.framework.BundleReference.getBundle. 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. Returns:Bundle The bundle that registered the service referenced by this `ServiceReference` object; `null` if that service has already been unregistered. Annotations @Override See Also `BundleContext#registerService(String[], Object, Dictionary)`

public Bundle getBundle()

Redeclares org.osgi.framework.BundleReference.getBundle.

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.

Returns:Bundle

The bundle that registered the service referenced by this ServiceReference object; null if that service has already been unregistered.

Annotations

@Override

getProperties back to summary

getProperties	back to summary
public Dictionary<String, Object> getProperties() Returns a copy of the properties of the service referenced by this `ServiceReference` object. This method will continue to return the properties 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. The returned `Dictionary` object: Must map property values by using property keys in a case-insensitive manner. Must return property keys is a case-preserving manner. This means that the keys must have the same case as the corresponding key in the properties `Dictionary` that was passed to the `BundleContext#registerService(String[], Object, Dictionary)` or `ServiceRegistration#setProperties(Dictionary)` methods. Is the property of the caller and can be modified by the caller but any changes are not reflected in the properties of the service. `ServiceRegistration#setProperties(Dictionary)` must be called to modify the properties of the service. Returns:Dictionary<String, Object> A copy of the properties of the service referenced by this `ServiceReference` object Since 1.9

public Dictionary<String, Object> getProperties()

Returns a copy of the properties of the service referenced by this ServiceReference object.

This method will continue to return the properties 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.

The returned Dictionary object:

Must map property values by using property keys in a case-insensitive manner.
Must return property keys is a case-preserving manner. This means that the keys must have the same case as the corresponding key in the properties Dictionary that was passed to the BundleContext#registerService(String[], Object, Dictionary) or ServiceRegistration#setProperties(Dictionary) methods.
Is the property of the caller and can be modified by the caller but any changes are not reflected in the properties of the service. ServiceRegistration#setProperties(Dictionary) must be called to modify the properties of the service.

Returns:Dictionary<String, Object>: A copy of the properties of the service referenced by this ServiceReference object
Since: 1.9

getProperty back to summary

getProperty	back to summary
public Object getProperty(String key) 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. Parameters key:String The property key. Returns:Object 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 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.

Parameters

key:String: The property key.

Returns:Object

The property value to which the key is mapped; null if there is no property named after the key.

getPropertyKeys back to summary

getPropertyKeys	back to summary
public String[] getPropertyKeys() 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 `BundleContext#registerService(String[], Object, Dictionary)` or `ServiceRegistration#setProperties(Dictionary)` methods. Returns:String[] An array of property keys.

public String[] getPropertyKeys()

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 BundleContext#registerService(String[], Object, Dictionary) or ServiceRegistration#setProperties(Dictionary) methods.

Returns:String[]: An array of property keys.

getUsingBundles back to summary

getUsingBundles	back to summary
public Bundle[] getUsingBundles() 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. Returns:Bundle[] 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()

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.

Returns:Bundle[]: 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

isAssignableTo back to summary

isAssignableTo	back to summary
public boolean isAssignableTo(Bundle bundle, String className) 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: If the specified bundle is equal to the bundle that registered the service referenced by this `ServiceReference` (registrant bundle) return `true`. Get the package name from the specified class name. For the specified bundle; find the source for the package. If no source is found then return `true` (use of reflection is assumed by the specified bundle). For the registrant bundle; find the source for the package. If the package source is found then return `true` if the package source equals the package source of the specified bundle; otherwise return `false`. If no package source is found for the registrant bundle then determine the package source based on the service object. If the service object is a `ServiceFactory` and the factory implementation is not from the registrant bundle return `true`; otherwise attempt to find the package source based on the service object class. If the package source is found and is equal to package source of the specified bundle return `true`; otherwise return `false`. Parameters bundle:Bundle The `Bundle` object to check. className:String The class name to check. Returns:boolean `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. Exceptions 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)

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:

If the specified bundle is equal to the bundle that registered the service referenced by this ServiceReference (registrant bundle) return true.
Get the package name from the specified class name.
For the specified bundle; find the source for the package. If no source is found then return true (use of reflection is assumed by the specified bundle).
For the registrant bundle; find the source for the package. If the package source is found then return true if the package source equals the package source of the specified bundle; otherwise return false.
If no package source is found for the registrant bundle then determine the package source based on the service object. If the service object is a ServiceFactory and the factory implementation is not from the registrant bundle return true; otherwise attempt to find the package source based on the service object class. If the package source is found and is equal to package source of the specified bundle return true; otherwise return false.

Parameters

bundle:Bundle: The Bundle object to check.
className:String: The class name to check.

Returns:boolean

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.

Exceptions

IllegalArgumentException:: If the specified Bundle was not created by the same framework instance as this ServiceReference.

Since

1.3

public Interface ServiceReference<S>

Method Summary

Method Detail