KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > osgi > service > device > Driver


1 /*
2  * $Header: /cvshome/build/org.osgi.service.device/src/org/osgi/service/device/Driver.java,v 1.11 2006/07/11 00:54:08 hargrave Exp $
3  *
4  * Copyright (c) OSGi Alliance (2000, 2006). All Rights Reserved.
5  *
6  * Licensed under the Apache License, Version 2.0 (the "License");
7  * you may not use this file except in compliance with the License.
8  * You may obtain a copy of the License at
9  *
10  * http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing, software
13  * distributed under the License is distributed on an "AS IS" BASIS,
14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15  * See the License for the specific language governing permissions and
16  * limitations under the License.
17  */
18 package org.osgi.service.device;
19
20 import org.osgi.framework.ServiceReference;
21
22 /**
23  * A <code>Driver</code> service object must be registered by each Driver bundle
24  * wishing to attach to Device services provided by other drivers. For each
25  * newly discovered {@link Device} object, the device manager enters a bidding
26  * phase. The <code>Driver</code> object whose {@link #match} method bids the
27  * highest for a particular <code>Device</code> object will be instructed by the
28  * device manager to attach to the <code>Device</code> object.
29  *
30  * @version $Revision: 1.11 $
31  * @see Device
32  * @see DriverLocator
33  */
34 public interface Driver {
35     /**
36      * Checks whether this Driver service can be attached to the Device service.
37      *
38      * The Device service is represented by the given {@link ServiceReference}
39      * and returns a value indicating how well this driver can support the given
40      * Device service, or {@link Device#MATCH_NONE} if it cannot support the
41      * given Device service at all.
42      *
43      * <p>
44      * The return value must be one of the possible match values defined in the
45      * device category definition for the given Device service, or
46      * <code>Device.MATCH_NONE</code> if the category of the Device service is not
47      * recognized.
48      *
49      * <p>
50      * In order to make its decision, this Driver service may examine the
51      * properties associated with the given Device service, or may get the
52      * referenced service object (representing the actual physical device) to
53      * talk to it, as long as it ungets the service and returns the physical
54      * device to a normal state before this method returns.
55      *
56      * <p>
57      * A Driver service must always return the same match code whenever it is
58      * presented with the same Device service.
59      *
60      * <p>
61      * The match function is called by the device manager during the matching
62      * process.
63      *
64      * @param reference the <code>ServiceReference</code> object of the device to
65      * match
66      *
67      * @return value indicating how well this driver can support the given
68      * Device service, or <code>Device.MATCH_NONE</code> if it cannot
69      * support the Device service at all
70      *
71      * @throws java.lang.Exception if this Driver service cannot examine the
72      * Device service
73      */
74     public int match(ServiceReference reference) throws Exception JavaDoc;
75
76     /**
77      * Attaches this Driver service to the Device service represented by the
78      * given <code>ServiceReference</code> object.
79      *
80      * <p>
81      * A return value of <code>null</code> indicates that this Driver service has
82      * successfully attached to the given Device service. If this Driver service
83      * is unable to attach to the given Device service, but knows of a more
84      * suitable Driver service, it must return the <code>DRIVER_ID</code> of that
85      * Driver service. This allows for the implementation of referring drivers
86      * whose only purpose is to refer to other drivers capable of handling a
87      * given Device service.
88      *
89      * <p>
90      * After having attached to the Device service, this driver may register the
91      * underlying device as a new service exposing driver-specific
92      * functionality.
93      *
94      * <p>
95      * This method is called by the device manager.
96      *
97      * @param reference the <code>ServiceReference</code> object of the device to
98      * attach to
99      *
100      * @return <code>null</code> if this Driver service has successfully attached
101      * to the given Device service, or the <code>DRIVER_ID</code> of a
102      * more suitable driver
103      *
104      * @throws java.lang.Exception if the driver cannot attach to the given
105      * device and does not know of a more suitable driver
106      */
107     public String JavaDoc attach(ServiceReference reference) throws Exception JavaDoc;
108 }
109
Popular Tags