| /* |
| * Copyright (c) OSGi Alliance (2000, 2015). 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.service.device; |
| |
| import org.osgi.framework.ServiceReference; |
| |
| /** |
| * A {@code Driver} service object must be registered by each Driver bundle |
| * wishing to attach to Device services provided by other drivers. For each |
| * newly discovered {@link Device} object, the device manager enters a bidding |
| * phase. The {@code Driver} object whose {@link #match(ServiceReference)} |
| * method bids the highest for a particular {@code Device} object will be |
| * instructed by the device manager to attach to the {@code Device} object. |
| * |
| * @author $Id$ |
| * @see Device |
| * @see DriverLocator |
| * @ThreadSafe |
| */ |
| public interface Driver { |
| /** |
| * Checks whether this Driver service can be attached to the Device service. |
| * |
| * The Device service is represented by the given {@link ServiceReference} |
| * and returns a value indicating how well this driver can support the given |
| * Device service, or {@link Device#MATCH_NONE} if it cannot support the |
| * given Device service at all. |
| * |
| * <p> |
| * The return value must be one of the possible match values defined in the |
| * device category definition for the given Device service, or |
| * {@code Device.MATCH_NONE} if the category of the Device service is not |
| * recognized. |
| * |
| * <p> |
| * In order to make its decision, this Driver service may examine the |
| * properties associated with the given Device service, or may get the |
| * referenced service object (representing the actual physical device) to |
| * talk to it, as long as it ungets the service and returns the physical |
| * device to a normal state before this method returns. |
| * |
| * <p> |
| * A Driver service must always return the same match code whenever it is |
| * presented with the same Device service. |
| * |
| * <p> |
| * The match function is called by the device manager during the matching |
| * process. |
| * |
| * @param reference the {@code ServiceReference} object of the device to |
| * match |
| * |
| * @return value indicating how well this driver can support the given |
| * Device service, or {@code Device.MATCH_NONE} if it cannot support |
| * the Device service at all |
| * |
| * @throws java.lang.Exception if this Driver service cannot examine the |
| * Device service |
| */ |
| public int match(ServiceReference<?> reference) throws Exception; |
| |
| /** |
| * Attaches this Driver service to the Device service represented by the |
| * given {@code ServiceReference} object. |
| * |
| * <p> |
| * A return value of {@code null} indicates that this Driver service has |
| * successfully attached to the given Device service. If this Driver service |
| * is unable to attach to the given Device service, but knows of a more |
| * suitable Driver service, it must return the {@code DRIVER_ID} of that |
| * Driver service. This allows for the implementation of referring drivers |
| * whose only purpose is to refer to other drivers capable of handling a |
| * given Device service. |
| * |
| * <p> |
| * After having attached to the Device service, this driver may register the |
| * underlying device as a new service exposing driver-specific |
| * functionality. |
| * |
| * <p> |
| * This method is called by the device manager. |
| * |
| * @param reference the {@code ServiceReference} object of the device to |
| * attach to |
| * |
| * @return {@code null} if this Driver service has successfully attached to |
| * the given Device service, or the {@code DRIVER_ID} of a more |
| * suitable driver |
| * |
| * @throws java.lang.Exception if the driver cannot attach to the given |
| * device and does not know of a more suitable driver |
| */ |
| public String attach(ServiceReference<?> reference) throws Exception; |
| } |