001 /*
002 * Copyright (c) OSGi Alliance (2000, 2008). All Rights Reserved.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package org.osgi.service.device;
017
018 import org.osgi.framework.ServiceReference;
019
020 /**
021 * A <code>Driver</code> service object must be registered by each Driver bundle
022 * wishing to attach to Device services provided by other drivers. For each
023 * newly discovered {@link Device} object, the device manager enters a bidding
024 * phase. The <code>Driver</code> object whose {@link #match} method bids the
025 * highest for a particular <code>Device</code> object will be instructed by the
026 * device manager to attach to the <code>Device</code> object.
027 *
028 * @version $Revision: 5654 $
029 * @see Device
030 * @see DriverLocator
031 * @ThreadSafe
032 */
033 public interface Driver {
034 /**
035 * Checks whether this Driver service can be attached to the Device service.
036 *
037 * The Device service is represented by the given {@link ServiceReference}
038 * and returns a value indicating how well this driver can support the given
039 * Device service, or {@link Device#MATCH_NONE} if it cannot support the
040 * given Device service at all.
041 *
042 * <p>
043 * The return value must be one of the possible match values defined in the
044 * device category definition for the given Device service, or
045 * <code>Device.MATCH_NONE</code> if the category of the Device service is
046 * not recognized.
047 *
048 * <p>
049 * In order to make its decision, this Driver service may examine the
050 * properties associated with the given Device service, or may get the
051 * referenced service object (representing the actual physical device) to
052 * talk to it, as long as it ungets the service and returns the physical
053 * device to a normal state before this method returns.
054 *
055 * <p>
056 * A Driver service must always return the same match code whenever it is
057 * presented with the same Device service.
058 *
059 * <p>
060 * The match function is called by the device manager during the matching
061 * process.
062 *
063 * @param reference the <code>ServiceReference</code> object of the device
064 * to match
065 *
066 * @return value indicating how well this driver can support the given
067 * Device service, or <code>Device.MATCH_NONE</code> if it cannot
068 * support the Device service at all
069 *
070 * @throws java.lang.Exception if this Driver service cannot examine the
071 * Device service
072 */
073 public int match(ServiceReference reference) throws Exception;
074
075 /**
076 * Attaches this Driver service to the Device service represented by the
077 * given <code>ServiceReference</code> object.
078 *
079 * <p>
080 * A return value of <code>null</code> indicates that this Driver service
081 * has successfully attached to the given Device service. If this Driver
082 * service is unable to attach to the given Device service, but knows of a
083 * more suitable Driver service, it must return the <code>DRIVER_ID</code>
084 * of that Driver service. This allows for the implementation of referring
085 * drivers whose only purpose is to refer to other drivers capable of
086 * handling a given Device service.
087 *
088 * <p>
089 * After having attached to the Device service, this driver may register the
090 * underlying device as a new service exposing driver-specific
091 * functionality.
092 *
093 * <p>
094 * This method is called by the device manager.
095 *
096 * @param reference the <code>ServiceReference</code> object of the device
097 * to attach to
098 *
099 * @return <code>null</code> if this Driver service has successfully
100 * attached to the given Device service, or the
101 * <code>DRIVER_ID</code> of a more suitable driver
102 *
103 * @throws java.lang.Exception if the driver cannot attach to the given
104 * device and does not know of a more suitable driver
105 */
106 public String attach(ServiceReference reference) throws Exception;
107 }