1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
|
/*
* 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;
}
|
