Java tutorial
/****************************************************************************** * Copyright (c) 2006, 2010 VMware Inc. * All rights reserved. This program and the accompanying materials * are made available under the terms of the Eclipse Public License v1.0 * and Apache License v2.0 which accompanies this distribution. * The Eclipse Public License is available at * http://www.eclipse.org/legal/epl-v10.html and the Apache License v2.0 * is available at http://www.opensource.org/licenses/apache2.0.php. * You may elect to redistribute this code under either of these licenses. * * Contributors: * VMware Inc. *****************************************************************************/ package org.eclipse.gemini.blueprint.util; import java.util.Collections; import java.util.Dictionary; import java.util.LinkedHashMap; import java.util.Map; import org.apache.commons.logging.Log; import org.apache.commons.logging.LogFactory; import org.eclipse.gemini.blueprint.util.internal.MapBasedDictionary; import org.eclipse.gemini.blueprint.util.internal.ServiceReferenceBasedMap; import org.osgi.framework.BundleContext; import org.osgi.framework.Constants; import org.osgi.framework.InvalidSyntaxException; import org.osgi.framework.ServiceReference; import org.springframework.util.Assert; import org.springframework.util.ObjectUtils; /** * 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 {@link InvalidSyntaxException} into unchecked ones. * * <p/> * * This classes uses {@link OsgiFilterUtils} underneath to allow multiple class names to be used for service reference * lookup. * * @see OsgiFilterUtils * @author Costin Leau * */ public abstract class OsgiServiceReferenceUtils { private static final Log log = LogFactory.getLog(OsgiServiceReferenceUtils.class); /** * Returns a reference to the <em>best matching</em> service for the given class names. * * @param bundleContext OSGi bundle context * @param classes array of fully qualified class names * @return reference to the <em>best matching</em> service */ public static ServiceReference getServiceReference(BundleContext bundleContext, String[] classes) { return getServiceReference(bundleContext, classes, null); } /** * Returns a reference to the <em>best matching</em> service for the given class and OSGi filter. * * @param bundleContext OSGi bundle context * @param clazz fully qualified class name (can be <code>null</code>) * @param filter valid OSGi filter (can be <code>null</code>) * @return reference to the <em>best matching</em> service */ public static ServiceReference getServiceReference(BundleContext bundleContext, String clazz, String filter) { ServiceReference[] refs = getServiceReferences(bundleContext, clazz, filter); // pick the best service return getServiceReference(refs); } public static ServiceReference getServiceReference(ServiceReference... references) { if (ObjectUtils.isEmpty(references)) { return null; } ServiceReference winningReference = references[0]; if (references.length > 1) { long winningId = getServiceId(winningReference); int winningRanking = getServiceRanking(winningReference); // start iterating in order to find the best match for (int i = 1; i < references.length; i++) { ServiceReference reference = references[i]; int serviceRanking = getServiceRanking(reference); long serviceId = getServiceId(reference); if ((serviceRanking > winningRanking) || (serviceRanking == winningRanking && winningId > serviceId)) { winningReference = reference; winningId = serviceId; winningRanking = serviceRanking; } } } return winningReference; } /** * Returns a reference to the <em>best matching</em> service for the given classes and OSGi filter. * * @param bundleContext OSGi bundle context * @param classes array of fully qualified class names * @param filter valid OSGi filter (can be <code>null</code>) * @return reference to the <em>best matching</em> service */ public static ServiceReference getServiceReference(BundleContext bundleContext, String[] classes, String filter) { // use #getServiceReference(BundleContext, String, String) method to // speed the service lookup process by // giving one class as a hint to the OSGi implementation String clazz = (ObjectUtils.isEmpty(classes) ? null : classes[0]); return getServiceReference(bundleContext, clazz, OsgiFilterUtils.unifyFilter(classes, filter)); } /** * Returns a reference to the <em>best matching</em> service for the given OSGi filter. * * @param bundleContext OSGi bundle context * @param filter valid OSGi filter (can be <code>null</code>) * @return reference to the <em>best matching</em> service */ public static ServiceReference getServiceReference(BundleContext bundleContext, String filter) { return getServiceReference(bundleContext, (String) null, filter); } /** * Returns references to <em>all</em> services matching the given class names. * * @param bundleContext OSGi bundle context * @param classes array of fully qualified class names * @return non-<code>null</code> array of references to matching services */ public static ServiceReference[] getServiceReferences(BundleContext bundleContext, String[] classes) { return getServiceReferences(bundleContext, classes, null); } /** * Returns references to <em>all</em> services matching the given class name and OSGi filter. * * @param bundleContext OSGi bundle context * @param clazz fully qualified class name (can be <code>null</code>) * @param filter valid OSGi filter (can be <code>null</code>) * @return non-<code>null</code> array of references to matching services */ public static ServiceReference[] getServiceReferences(BundleContext bundleContext, String clazz, String filter) { Assert.notNull(bundleContext, "bundleContext should be not null"); try { ServiceReference[] refs = bundleContext.getServiceReferences(clazz, filter); return (refs == null ? new ServiceReference[0] : refs); } catch (InvalidSyntaxException ise) { throw (RuntimeException) new IllegalArgumentException("invalid filter: " + ise.getFilter()) .initCause(ise); } } /** * Returns references to <em>all</em> services matching the given class names and OSGi filter. * * @param bundleContext OSGi bundle context * @param classes array of fully qualified class names * @param filter valid OSGi filter (can be <code>null</code>) * @return non-<code>null</code> array of references to matching services */ public static ServiceReference[] getServiceReferences(BundleContext bundleContext, String[] classes, String filter) { // use #getServiceReferences(BundleContext, String, String) method to // speed the service lookup process by // giving one class as a hint to the OSGi implementation // additionally this allows type filtering String clazz = (ObjectUtils.isEmpty(classes) ? null : classes[0]); return getServiceReferences(bundleContext, clazz, OsgiFilterUtils.unifyFilter(classes, filter)); } /** * Returns references to <em>all</em> services matching the OSGi filter. * * @param bundleContext OSGi bundle context * @param filter valid OSGi filter (can be <code>null</code>) * @return non-<code>null</code> array of references to matching services */ public static ServiceReference[] getServiceReferences(BundleContext bundleContext, String filter) { return getServiceReferences(bundleContext, (String) null, filter); } /** * Returns the service id ({@link Constants#SERVICE_ID}) of the given service reference. * * @param reference OSGi service reference * @return service id */ public static long getServiceId(ServiceReference reference) { Assert.notNull(reference); return ((Long) reference.getProperty(Constants.SERVICE_ID)).longValue(); } /** * Returns the service ranking ({@link Constants#SERVICE_RANKING}) of the given service reference. * * @param reference OSGi service reference * @return service ranking */ public static int getServiceRanking(ServiceReference reference) { Assert.notNull(reference); Object ranking = reference.getProperty(Constants.SERVICE_RANKING); // if the property is not supplied or of incorrect type, use a // default return ((ranking != null && ranking instanceof Integer) ? ((Integer) ranking).intValue() : 0); } /** * Returns the advertised class names ({@link Constants#OBJECTCLASS}) of the given service reference. * * @param reference OSGi service reference * @return service advertised class names */ public static String[] getServiceObjectClasses(ServiceReference reference) { Assert.notNull(reference); return (String[]) reference.getProperty(Constants.OBJECTCLASS); } /** * Returns a {@link 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. * * <p/> Note that the returned type implements the {@link java.util.Map} interface also. * * @param reference OSGi service reference * @return a <code>Dictionary</code> containing the service reference properties taken as a snapshot */ public static Dictionary getServicePropertiesSnapshot(ServiceReference reference) { return new MapBasedDictionary(getServicePropertiesSnapshotAsMap(reference)); } /** * Returns a {@link 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. * * @param reference OSGi service reference * @return a <code>Map</code> containing the service reference properties taken as a snapshot */ public static Map getServicePropertiesSnapshotAsMap(ServiceReference reference) { Assert.notNull(reference); String[] keys = reference.getPropertyKeys(); Map map = new LinkedHashMap(keys.length); for (int i = 0; i < keys.length; i++) { map.put(keys[i], reference.getProperty(keys[i])); } // mark it as read-only map = Collections.unmodifiableMap(map); return map; } /** * Returns a {@link Dictionary} containing the properties available for the given service reference. The returned * object will reflect any updates made to to the <code>ServiceReference</code> through the owning * <code>ServiceRegistration</code>. * * * <p/> Note that the returned type implements the {@link java.util.Map} interface also. * * @param reference OSGi service reference * @return a <code>Dictionary</code> containing the latest service reference properties */ public static Dictionary getServiceProperties(ServiceReference reference) { return new MapBasedDictionary(getServicePropertiesAsMap(reference)); } /** * Returns a {@link Map} containing the properties available for the given service reference. The returned object * will reflect any updates made to to the <code>ServiceReference</code> through the owning * <code>ServiceRegistration</code>. Consider using {@link #getServiceProperties(ServiceReference)} which returns an * object that extends {@link Dictionary} as well as implements the {@link Map} interface. * * @param reference OSGi service reference * @return a <code>Map</code> containing the latest service reference properties * @see #getServiceProperties(ServiceReference) */ public static Map getServicePropertiesAsMap(ServiceReference reference) { Assert.notNull(reference); return new ServiceReferenceBasedMap(reference); } /** * Checks if the given filter matches at least one OSGi service or not. * * @param bundleContext OSGi bundle context * @param filter valid OSGi filter (can be <code>null</code>) * @return true if the filter matches at least one OSGi service, false otherwise */ public static boolean isServicePresent(BundleContext bundleContext, String filter) { return !ObjectUtils.isEmpty(getServiceReferences(bundleContext, filter)); } }