org.osgi.service.device.Driver Maven / Gradle / Ivy
/*
* Copyright (c) OSGi Alliance (2000, 2011). 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.
*
* @version $Id: 8d86c732bdc1e4d50c18a237427578472e13dcbf $
* @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.
*
*
* 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.
*
*
* 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.
*
*
* A Driver service must always return the same match code whenever it is
* presented with the same Device service.
*
*
* 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.
*
*
* 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.
*
*
* After having attached to the Device service, this driver may register the
* underlying device as a new service exposing driver-specific
* functionality.
*
*
* 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;
}