org.mbs.services.device.abstractdriver
Class AbstractDeviceDriver

java.lang.Object
  org.mbs.services.device.abstractdriver.AbstractDeviceDriver

All Implemented Interfaces:

java.util.EventListener, org.osgi.framework.ServiceListener, Driver

public abstract class AbstractDeviceDriver
extends java.lang.Object
implements Driver, org.osgi.framework.ServiceListener

Base driver class for all device drivers. A driver holds the logic of matching and attaching devices. If the driver matches a device service (bids a highest match number of all currently registered drivers), its attach(ServiceReference) method is invoked. If attaching is successful a new org.mbs.services.control.ControlUnit service is registered in the framework.

The AbstractDeviceDriver provides implementation of the attach method, while the extending classes should implement the logic of matching devices in their match method.

Since:

$Date: 2005/02/17 08:33:37 $

Author:

Stoyan Zoubev

Field Summary

protected java.util.Hashtable	attachedServices Hold all attached services.
protected org.osgi.framework.BundleContext	bc BundleContext object of the driver bundle
static int	CONTROLLER_DEBUG_LEVEL
static int	DRIVER_DEBUG_LEVEL
protected org.osgi.framework.ServiceRegistration	driverReg Service registration of the driver service
static java.lang.String	LAYER The identification of this component used for logging
static ManagedLog	log service used for logging
static int	MODEL_DEBUG_LEVEL
protected DeviceStateGraph	stateGraph Device state graph
static DB	storage reference to DB service, used for handling device additional names
protected boolean	useTokenDevices

Constructor Summary

AbstractDeviceDriver(org.osgi.framework.BundleContext bc)
Constructor.

Method Summary

java.lang.String	attach(org.osgi.framework.ServiceReference reference) Attaches this Driver service to the Device service represented by the given ServiceReference object.
protected DeviceControlUnit	createDeviceCU(java.lang.Object service) Creates device control unit implementation for the given device service.
abstract java.lang.String	generateControlUnitID(java.lang.Object device) Generates a control unit id based on the service passed as parameter.
java.lang.String[]	getControlledDevices() Returns a String array of the IDs of all the devices controlled by the driver
protected abstract AbstractDeviceController	getController(java.lang.Object device) Returns an AbstractDeviceController instance for device type of the driver.
abstract java.lang.String	getDeviceServiceFilter() This method is called to register driver service listener with service filter.
abstract java.lang.String	getDriverID() Implementing classes return their DRIVER_IDs as in the Device Access specification.
protected abstract AbstractDeviceModel	getModel(java.lang.Object device) An instance of a class, extending AbstractDeviceModel, model for the types of devices this driver attaches.
void	handleUnregistering() Invoked when this driver's bundle is stopped.
abstract int	match(org.osgi.framework.ServiceReference reference) Checks whether this Driver service can be attached to the Device service.
static java.lang.String	readAdditionalName(java.lang.String type, java.lang.String id) Reads the device additional name from persistent storage.
void	registerDriverService(org.osgi.framework.BundleContext bc) Registers this class as a driver service
void	release() Release driver resources.
void	serviceChanged(org.osgi.framework.ServiceEvent event) Implementation of ServiceListener interface.
void	setDeviceStateGraph(DeviceStateGraph stateGraph) Sets the device state graph the should be used to control devices registered by this driver.
void	setDeviceToken(boolean useTokenDevices) Changes the default class of the created control unit by the driver.
void	unregisterDriverService() Unregisters this class as a driver service.
static void	writeAdditionalName(java.lang.String type, java.lang.String id, java.lang.String name) Stores persistently the device additional name.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

log

public static ManagedLog log

service used for logging

storage

public static DB storage

reference to DB service, used for handling device additional names

LAYER

public static final java.lang.String LAYER

The identification of this component used for logging

See Also:

Constant Field Values

DRIVER_DEBUG_LEVEL

public static final int DRIVER_DEBUG_LEVEL

See Also:

Constant Field Values

CONTROLLER_DEBUG_LEVEL

public static final int CONTROLLER_DEBUG_LEVEL

See Also:

Constant Field Values

MODEL_DEBUG_LEVEL

public static final int MODEL_DEBUG_LEVEL

See Also:

Constant Field Values

bc

protected org.osgi.framework.BundleContext bc

BundleContext object of the driver bundle

attachedServices

protected java.util.Hashtable attachedServices

Hold all attached services. Key is ServiceReference, value is a corresponding ControlUnit instance.

driverReg

protected org.osgi.framework.ServiceRegistration driverReg

Service registration of the driver service

stateGraph

protected DeviceStateGraph stateGraph

Device state graph

useTokenDevices

protected boolean useTokenDevices

Constructor Detail

AbstractDeviceDriver

public AbstractDeviceDriver(org.osgi.framework.BundleContext bc)
                     throws java.lang.Exception

Constructor.

Parameters:

bc - this diver's bundle BundleContext

Throws:

java.lang.Exception

Method Detail

setDeviceToken

public void setDeviceToken(boolean useTokenDevices)

Changes the default class of the created control unit by the driver. If the parameter useTokenDevices is true, then all control units that will be registered by the driver will be of class TokenDeviceControlUnit and will support the token locking mechanism. By default, when driver is created the token support is determined by the value of the system property "mbs.abstractdriver.token".

Note: Calling this method will not affect already registered control units by the driver.

Parameters:

useTokenDevices - true if control units registered by this driver will support token mechanism.

match

public abstract int match(org.osgi.framework.ServiceReference reference)
                   throws java.lang.Exception

Checks whether this Driver service can be attached to the Device service. The Device service is represented by the given ServiceReference and returns a value indicating how well this driver can support the given Device service, or 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 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.

Specified by:

match in interface Driver

Parameters:

reference - the ServiceReference object of the device to match

Returns:

value indicating how well this driver can support the given Device service, or 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

attach

public java.lang.String attach(org.osgi.framework.ServiceReference reference)
                        throws java.lang.Exception

Attaches this Driver service to the Device service represented by the given ServiceReference object. This results in the registration of a ControlUnit service in the framework.

A return value of 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 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.

Specified by:

attach in interface Driver

Parameters:

reference - the ServiceReference object of the device to attach to

Returns:

null if this Driver service has successfully attached to the given Device service, or the 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

getDriverID

public abstract java.lang.String getDriverID()

Implementing classes return their DRIVER_IDs as in the Device Access specification.

Returns:

driver ID for the implementing class.

getController

protected abstract AbstractDeviceController getController(java.lang.Object device)

Returns an AbstractDeviceController instance for device type of the driver.

Parameters:

device - EHSDevice service which

Returns:

an AbstractDeviceController instance for device type of the driver.

getModel

protected abstract AbstractDeviceModel getModel(java.lang.Object device)

An instance of a class, extending AbstractDeviceModel, model for the types of devices this driver attaches.

Parameters:

device -

Returns:

An instance of a class, extending AbstractDeviceModel

createDeviceCU

protected DeviceControlUnit createDeviceCU(java.lang.Object service)

Creates device control unit implementation for the given device service.

Parameters:

service - the device service

Returns:

default implementations of the control unit, with the attached model and controller. If the method setDeviceToken() was used with true parameter, then the returned control unit will be instance of TokenDeviceControlUnit and will support, lock & unlock operations.

serviceChanged

public void serviceChanged(org.osgi.framework.ServiceEvent event)

Implementation of ServiceListener interface.

Specified by:

serviceChanged in interface org.osgi.framework.ServiceListener

Parameters:

event - The ServiceEvent object.

See Also:

ServiceListener.serviceChanged(org.osgi.framework.ServiceEvent)

registerDriverService

public void registerDriverService(org.osgi.framework.BundleContext bc)

Registers this class as a driver service

Parameters:

bc - the BundleContext object with which the service is registered

unregisterDriverService

public void unregisterDriverService()

Unregisters this class as a driver service.

handleUnregistering

public void handleUnregistering()

Invoked when this driver's bundle is stopped. Unregister all registered ControlUnit services.

release

public void release()

Release driver resources.

getControlledDevices

public java.lang.String[] getControlledDevices()

Returns a String array of the IDs of all the devices controlled by the driver

Returns:

returns a String array of the IDs of all the devices controlled by the driver

generateControlUnitID

public abstract java.lang.String generateControlUnitID(java.lang.Object device)

Generates a control unit id based on the service passed as parameter.

Parameters:

device - a device service

Returns:

a control unit id

getDeviceServiceFilter

public abstract java.lang.String getDeviceServiceFilter()

This method is called to register driver service listener with service filter.

Returns:

filter string to be used registering service listener

setDeviceStateGraph

public void setDeviceStateGraph(DeviceStateGraph stateGraph)

Sets the device state graph the should be used to control devices registered by this driver.

Parameters:

stateGraph - device state graph

writeAdditionalName

public static void writeAdditionalName(java.lang.String type,
                                       java.lang.String id,
                                       java.lang.String name)
                                throws java.io.IOException

Stores persistently the device additional name.

Parameters:

type - the type of the device

id - the id of the device

name - the user-friendly name of the device

Throws:

java.io.IOException - thrown if problems writing to storage occur

readAdditionalName

public static java.lang.String readAdditionalName(java.lang.String type,
                                                  java.lang.String id)

Reads the device additional name from persistent storage. If storage is not available or errors during reading occur, then empty string is returned.

Parameters:

type - the type of the device

id - the id of the device

Returns:

name the device additional name read from the storage or an empty string