cdev.dir
Class DirectoryService

java.lang.Object
  |
  +--cdev.dir.DirectoryService

public abstract class DirectoryService
extends java.lang.Object

This abstract class is a starting point for getting DirectoryItem objects and object identifiers from string or numeric parameters. After this you can get additional information from the objects themselves.

As a first step you must get the implemented directory service with a statement like:

DirectoryService dir = cdev.dir.service.DirectoryServiceImplementation.getService();

This will also connect you to any database(s) you may need for getting data. After this you work only with the interfaces with statements like:

DeviceData devdat = dir.getDeviceData("BR1.QNO"); and : String devname = devdat.getName();

Several methods require a 'query' string for making a selection of object identifiers. The form and content of these queries is implementation dependent. For an implementation with a relational database this could be any valid 'WHERE' section of an SQL query, like 'column1=data1 AND column2=data2'. Avoid such queries in generic programs which must be ported to other implementations.

General documentation in DirectoryServiceDoc . Note: only one DirectoryServiceImplementation is installed for a site. This implementation may however address multiple DirectoryItem implementations

See Also:
DeviceData, DeviceClass, DeviceList, DeviceProperty, DeviceMessage, BitPatternDefinition, cdev.dir.service.DirectoryServiceImplementation

Method Summary
abstract  BitPatternDefinition getBitPatternDefinition(java.lang.String patternName)
          Gets BitPatternDefinition object for the given pattern name.
abstract  DeviceProperty getCommonProperty(java.lang.String propertyName, java.lang.String[] classNames)
          Instantiates common DeviceProperty object for property name and device class names.
abstract  DeviceClass getDeviceClass(java.lang.String className)
          Gets DeviceClass object when given the class name.
abstract  java.lang.String[] getDeviceClassNames()
          Gets an array of all device class names.
abstract  java.lang.String[] getDeviceClassNames(java.lang.String query)
          Gets an array of device class names from a query string.
abstract  DeviceData getDeviceData(java.lang.String deviceName)
          Gets the DeviceData object from the device name.
abstract  DeviceList getDeviceListByName(java.lang.String listName)
          Gets DeviceList object from the name of a list.
abstract  DeviceList getDeviceListByQuery(java.lang.String query)
          Gets DeviceList object from a database query string.
abstract  java.lang.String[] getDeviceListNames()
          Gets array of all devicelist names.
abstract  java.lang.String[] getDeviceListNames(java.lang.String query)
          Gets array of devicelist names from a database query.
abstract  DeviceMessage getDeviceMessage(int messageLevel, int messageNumber, java.lang.String serviceName)
          Gets DeviceMessage object corresponding to level, number and service.
abstract  java.lang.String[] getDeviceNames(java.lang.String query)
          Gets device names from a query string.
abstract  DeviceProperty getDeviceProperty(java.lang.String propertyName, java.lang.String className)
          Gets DeviceProperty object for given property name and class name.
static DirectoryService getService()
          Gets unique instantiation of the directory service implementation.
abstract  int getSymbolValue(java.lang.String symbolCategory, java.lang.String symbolName)
          Gets the symbol value when given the symbol category and symbol name.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getService

public static DirectoryService getService()
                                   throws BadConnectionException
Gets unique instantiation of the directory service implementation. This static method must be overridden in the implementation.
Throws:
BadConnectionException - -

getDeviceClass

public abstract DeviceClass getDeviceClass(java.lang.String className)
                                    throws BadConnectionException,
                                           NoSuchDataException,
                                           TooManyValuesException
Gets DeviceClass object when given the class name.
Parameters:
className - the name of the device class
Returns:
the DeviceClass object
Throws:
BadConnectionException - -
NoSuchDataException - -
TooManyValuesException - -

getDeviceClassNames

public abstract java.lang.String[] getDeviceClassNames()
                                                throws BadConnectionException,
                                                       NoSuchDataException
Gets an array of all device class names.
Throws:
BadConnectionException - -
NoSuchDataException - -

getDeviceClassNames

public abstract java.lang.String[] getDeviceClassNames(java.lang.String query)
                                                throws BadConnectionException,
                                                       NoSuchDataException,
                                                       BadQueryException
Gets an array of device class names from a query string.
Parameters:
query - a selection statement depending on the implementation
Returns:
array of device class names
Throws:
BadConnectionException - -
NoSuchDataException - -
BadQueryException - -

getDeviceData

public abstract DeviceData getDeviceData(java.lang.String deviceName)
                                  throws BadConnectionException,
                                         NoSuchDataException,
                                         TooManyValuesException
Gets the DeviceData object from the device name.
Returns:
the DeviceData object.
Throws:
BadConnectionException - -
NoSuchDataException - -
TooManyValuesException - -

getDeviceNames

public abstract java.lang.String[] getDeviceNames(java.lang.String query)
                                           throws BadConnectionException,
                                                  NoSuchDataException,
                                                  BadQueryException
Gets device names from a query string.
Parameters:
query - a selection statement depending on the implementation
Returns:
array of device names
Throws:
BadConnectionException - -
NoSuchDataException - -
BadQueryException - -

getDeviceListNames

public abstract java.lang.String[] getDeviceListNames()
                                               throws BadConnectionException,
                                                      NoSuchDataException
Gets array of all devicelist names.
Returns:
array of device list names
Throws:
BadConnectionException - -
NoSuchDataException - -

getDeviceListNames

public abstract java.lang.String[] getDeviceListNames(java.lang.String query)
                                               throws BadConnectionException,
                                                      NoSuchDataException,
                                                      BadQueryException
Gets array of devicelist names from a database query.
Returns:
array of device list names
Throws:
BadConnectionException - -
NoSuchDataException - -
BadQueryException - -

getDeviceListByName

public abstract DeviceList getDeviceListByName(java.lang.String listName)
                                        throws BadConnectionException,
                                               NoSuchDataException,
                                               TooManyValuesException
Gets DeviceList object from the name of a list.
Parameters:
listName - the name of the device list
Returns:
DeviceList object
Throws:
BadConnectionException - -
NoSuchDataException - -
TooManyValuesException - -

getDeviceListByQuery

public abstract DeviceList getDeviceListByQuery(java.lang.String query)
                                         throws BadConnectionException,
                                                NoSuchDataException,
                                                BadQueryException
Gets DeviceList object from a database query string. Devices are grouped by class. Ordering of groups and devices is implementation-dependent.
Parameters:
query - a selection statement depending on the implementation
Returns:
array of device list names
Throws:
BadConnectionException - -
NoSuchDataException - -
BadQueryException - -

getDeviceProperty

public abstract DeviceProperty getDeviceProperty(java.lang.String propertyName,
                                                 java.lang.String className)
                                          throws BadConnectionException,
                                                 NoSuchDataException,
                                                 TooManyValuesException
Gets DeviceProperty object for given property name and class name.
Parameters:
className - the name of the class
propertyName - the property name for the class
Returns:
DeviceProperty object
Throws:
BadConnectionException - -
NoSuchDataException - -
TooManyValuesException - -

getCommonProperty

public abstract DeviceProperty getCommonProperty(java.lang.String propertyName,
                                                 java.lang.String[] classNames)
                                          throws BadConnectionException,
                                                 NoSuchDataException
Instantiates common DeviceProperty object for property name and device class names. This determines what can be done collectively with a set of devices belonging to different classes, for instance a group from a DeviceList.

To be compatible, the properties must:

Throw NoSuchDataException if the classes are incompatible for the property.

The values of the composite property for the classes are :

Only the compatible characteristics defined in all the classes are listed. To be compatible, characteristics which have a property name as value must have the same name for all the classes. Characteristics which have different values for some of the classes are given the value string "MULTIVALUED"

Parameters:
propertyName - the name of the property
classNames - the classes for which the property should be defined
Returns:
DeviceProperty object
Throws:
BadConnectionException - -
NoSuchDataException - -

getDeviceMessage

public abstract DeviceMessage getDeviceMessage(int messageLevel,
                                               int messageNumber,
                                               java.lang.String serviceName)
                                        throws BadConnectionException,
                                               NoSuchDataException,
                                               TooManyValuesException
Gets DeviceMessage object corresponding to level, number and service. If the serviceName is irrelevant, set it to "ALL".
Throws:
BadConnectionException - -
NoSuchDataException - -
TooManyValuesException - - when duplicate messageKey found.

getBitPatternDefinition

public abstract BitPatternDefinition getBitPatternDefinition(java.lang.String patternName)
                                                      throws BadConnectionException,
                                                             NoSuchDataException,
                                                             TooManyValuesException
Gets BitPatternDefinition object for the given pattern name.
Parameters:
patternName - the pattern name for the class
Returns:
BitPatternDefinition object
Throws:
BadConnectionException - -
NoSuchDataException - -
TooManyValuesException - -

getSymbolValue

public abstract int getSymbolValue(java.lang.String symbolCategory,
                                   java.lang.String symbolName)
                            throws BadConnectionException,
                                   NoSuchDataException,
                                   TooManyValuesException
Gets the symbol value when given the symbol category and symbol name.
Parameters:
symbolCategory - the category of the symbol
symbolName - the name of the symbol
Returns:
the corresponding symbol value
Throws:
BadConnectionException - -
NoSuchDataException - -
TooManyValuesException - -