org.springframework.osgi.util
Class OsgiServiceReferenceUtils

java.lang.Object
  extended by org.springframework.osgi.util.OsgiServiceReferenceUtils

public abstract class OsgiServiceReferenceUtils
extends Object

Utility class for retrieving OSGi service references. This class offers a unified filter-based access for OSGi services as well as translation of checked exceptions InvalidSyntaxException into unchecked ones.

This classes uses OsgiFilterUtils underneath to allow multiple class names to be used for service reference lookup.

Author:
Costin Leau
See Also:
OsgiFilterUtils

Constructor Summary
OsgiServiceReferenceUtils()
           
 
Method Summary
static long getServiceId(ServiceReference reference)
          Returns the service id (Constants.SERVICE_ID) of the given service reference.
static String[] getServiceObjectClasses(ServiceReference reference)
          Returns the advertised class names (Constants.OBJECTCLASS) of the given service reference.
static Dictionary getServiceProperties(ServiceReference reference)
          Returns a Dictionary containing the properties available for the given service reference.
static Map getServicePropertiesAsMap(ServiceReference reference)
          Returns a Map containing the properties available for the given service reference.
static Dictionary getServicePropertiesSnapshot(ServiceReference reference)
          Returns a Map containing the properties available for the given service reference.
static Map getServicePropertiesSnapshotAsMap(ServiceReference reference)
          Returns a Map containing the properties available for the given service reference.
static int getServiceRanking(ServiceReference reference)
          Returns the service ranking (Constants.SERVICE_RANKING) of the given service reference.
static ServiceReference getServiceReference(BundleContext bundleContext, String filter)
          Returns a reference to the best matching service for the given OSGi filter.
static ServiceReference getServiceReference(BundleContext bundleContext, String[] classes)
          Returns a reference to the best matching service for the given class names.
static ServiceReference getServiceReference(BundleContext bundleContext, String[] classes, String filter)
          Returns a reference to the best matching service for the given classes and OSGi filter.
static ServiceReference getServiceReference(BundleContext bundleContext, String clazz, String filter)
          Returns a reference to the best matching service for the given class and OSGi filter.
static ServiceReference[] getServiceReferences(BundleContext bundleContext, String filter)
          Returns references to all services matching the OSGi filter.
static ServiceReference[] getServiceReferences(BundleContext bundleContext, String[] classes)
          Returns references to all services matching the given class names.
static ServiceReference[] getServiceReferences(BundleContext bundleContext, String[] classes, String filter)
          Returns references to all services matching the given class names and OSGi filter.
static ServiceReference[] getServiceReferences(BundleContext bundleContext, String clazz, String filter)
          Returns references to all services matching the given class name and OSGi filter.
static boolean isServicePresent(BundleContext bundleContext, String filter)
          Checks if the given filter matches at least one OSGi service or not.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

OsgiServiceReferenceUtils

public OsgiServiceReferenceUtils()
Method Detail

getServiceReference

public static ServiceReference getServiceReference(BundleContext bundleContext,
                                                   String[] classes)
Returns a reference to the best matching service for the given class names.

Parameters:
bundleContext - OSGi bundle context
classes - array of fully qualified class names
Returns:
reference to the best matching service

getServiceReference

public static ServiceReference getServiceReference(BundleContext bundleContext,
                                                   String clazz,
                                                   String filter)
Returns a reference to the best matching service for the given class and OSGi filter.

Parameters:
bundleContext - OSGi bundle context
clazz - fully qualified class name (can be null)
filter - valid OSGi filter (can be null)
Returns:
reference to the best matching service

getServiceReference

public static ServiceReference getServiceReference(BundleContext bundleContext,
                                                   String[] classes,
                                                   String filter)
Returns a reference to the best matching service for the given classes and OSGi filter.

Parameters:
bundleContext - OSGi bundle context
classes - array of fully qualified class names
filter - valid OSGi filter (can be null)
Returns:
reference to the best matching service

getServiceReference

public static ServiceReference getServiceReference(BundleContext bundleContext,
                                                   String filter)
Returns a reference to the best matching service for the given OSGi filter.

Parameters:
bundleContext - OSGi bundle context
filter - valid OSGi filter (can be null)
Returns:
reference to the best matching service

getServiceReferences

public static ServiceReference[] getServiceReferences(BundleContext bundleContext,
                                                      String[] classes)
Returns references to all services matching the given class names.

Parameters:
bundleContext - OSGi bundle context
classes - array of fully qualified class names
Returns:
non-null array of references to matching services

getServiceReferences

public static ServiceReference[] getServiceReferences(BundleContext bundleContext,
                                                      String clazz,
                                                      String filter)
Returns references to all services matching the given class name and OSGi filter.

Parameters:
bundleContext - OSGi bundle context
clazz - fully qualified class name (can be null)
filter - valid OSGi filter (can be null)
Returns:
non-null array of references to matching services

getServiceReferences

public static ServiceReference[] getServiceReferences(BundleContext bundleContext,
                                                      String[] classes,
                                                      String filter)
Returns references to all services matching the given class names and OSGi filter.

Parameters:
bundleContext - OSGi bundle context
classes - array of fully qualified class names
filter - valid OSGi filter (can be null)
Returns:
non-null array of references to matching services

getServiceReferences

public static ServiceReference[] getServiceReferences(BundleContext bundleContext,
                                                      String filter)
Returns references to all services matching the OSGi filter.

Parameters:
bundleContext - OSGi bundle context
filter - valid OSGi filter (can be null)
Returns:
non-null array of references to matching services

getServiceId

public static long getServiceId(ServiceReference reference)
Returns the service id (Constants.SERVICE_ID) of the given service reference.

Parameters:
reference - OSGi service reference
Returns:
service id

getServiceRanking

public static int getServiceRanking(ServiceReference reference)
Returns the service ranking (Constants.SERVICE_RANKING) of the given service reference.

Parameters:
reference - OSGi service reference
Returns:
service ranking

getServiceObjectClasses

public static String[] getServiceObjectClasses(ServiceReference reference)
Returns the advertised class names (Constants.OBJECTCLASS) of the given service reference.

Parameters:
reference - OSGi service reference
Returns:
service advertised class names

getServicePropertiesSnapshot

public static Dictionary getServicePropertiesSnapshot(ServiceReference reference)
Returns a Map containing the properties available for the given service reference. This method takes a snapshot of the properties; future changes to the service properties will not be reflected in the returned dictionary.

Note that the returned type implements the Map interface also.

Parameters:
reference - OSGi service reference
Returns:
a Dictionary containing the service reference properties taken as a snapshot

getServicePropertiesSnapshotAsMap

public static Map getServicePropertiesSnapshotAsMap(ServiceReference reference)
Returns a Map containing the properties available for the given service reference. This method takes a snapshot of the properties; future changes to the service properties will not be reflected in the returned dictionary.

Parameters:
reference - OSGi service reference
Returns:
a Map containing the service reference properties taken as a snapshot

getServiceProperties

public static Dictionary getServiceProperties(ServiceReference reference)
Returns a Dictionary containing the properties available for the given service reference. The returned object will reflect any updates made to to the ServiceReference through the owning ServiceRegistration.

Note that the returned type implements the Map interface also.

Parameters:
reference - OSGi service reference
Returns:
a Dictionary containing the latest service reference properties

getServicePropertiesAsMap

public static Map getServicePropertiesAsMap(ServiceReference reference)
Returns a Map containing the properties available for the given service reference. The returned object will reflect any updates made to to the ServiceReference through the owning ServiceRegistration. Consider using getServiceProperties(ServiceReference) which returns an object that extends Dictionary as well as implements the Map interface.

Parameters:
reference - OSGi service reference
Returns:
a Map containing the latest service reference properties
See Also:
getServiceProperties(ServiceReference)

isServicePresent

public static boolean isServicePresent(BundleContext bundleContext,
                                       String filter)
Checks if the given filter matches at least one OSGi service or not.

Parameters:
bundleContext - OSGi bundle context
filter - valid OSGi filter (can be null)
Returns:
true if the filter matches at least one OSGi service, false otherwise


Copyright � 2006-2008 Spring Framework. All Rights Reserved.