/*
 * $Header: /cvshome/build/org.osgi.service.device/src/org/osgi/service/device/Driver.java,v 1.10 2006/06/16 16:31:29 hargrave Exp $
 *
 * Copyright (c) OSGi Alliance (2000, 2006). 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</code> 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</code> object whose {@link #match}method bids the
 * highest for a particular <code>Device</code> object will be instructed by the
 * device manager to attach to the <code>Device</code> object.
 * 
 * @version $Revision: 1.10 $
 * @see Device
 * @see DriverLocator
 */
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</code> 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</code> object of the device to
	 *        match
	 * 
	 * @return value indicating how well this driver can support the given
	 *         Device service, or <code>Device.MATCH_NONE</code> 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</code> object.
	 * 
	 * <p>
	 * A return value of <code>null</code> 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</code> 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</code> object of the device to
	 *        attach to
	 * 
	 * @return <code>null</code> if this Driver service has successfully attached
	 *         to the given Device service, or the <code>DRIVER_ID</code> 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;
}