cdev.dir
Interface BitPatternDefinition

public interface BitPatternDefinition

extends DirectoryItem

Interface for the meaning of bitgroups in a bitpattern. By far the most common bitpattern will be an enumeration. If you are sure this is the only thing you will encounter, then methods

• int convertToValue(String label) - convert a label to an integer value
• String convertToString(int value) - convert an integer value to a label
• String[] getLabels(0) - get an array of defined labels

are all you need and you can skip the rest of this description. But the real world can be more complex and lot of information is in packed form such as status words coming from device or interface registers. A generic program can make sence of these bitpatterns with the help of this class.

A bitpattern is an integer data word wich is seen as a composite structure. A bitpattern can contain one or more consecutive bitgroups and a bitgroup can contain one or more consecutive bits. A bitgroup is identified by firstBit and ends before the firstBit of the next group, if any. The value of a bitpattern is the value of the data word seen as an integer.

It must be possible to mask unimportant bits in the bitpattern (this treats them as if they were 0) but this is done transparantly by the implementation.

A bitgroup is defined by one or more records composed of:

• firstBit : the first bit in the bitgroup (from 0)
• groupValue : reference value for the bitgroup seen as an integer, with firstBit having a weight of 1.
• label : string corresponding to groupValue. Labels should be unique for the BitPatternDefinition.

A bitgroup is discrete if it has corresponding defined pairs of groupValue and label. An exclusive group of bits is just a special case of a discrete group.

A bitgroup is continuous if its bits are read as an integer value. A continuous group is defined by a single record with reference value=-1 (so that it will match no possible actual value) and the label indicates the meaning of the value. The label seen in conversions (on input or output) is in fact a concatenation: 'label=value', for instance: 'widget position=15'. This makes decoding of packed values easier.

A BitPatternDefinition object can be obtained with DirectoryService#getBitPatternDefinition(patternName). The patternName must be unique for the implementation.
Implementation with a local cache is recommended for efficiency.

Note: in the bit description, describe only interesting situations: if a bit=1 indicates a fault, then there should be a matching label, but an absence of the fault (here bit=0) should have no matching label.

General documentation in DirectoryService .

See Also:

DirectoryService, DeviceProperty, DeviceMessage, cdev.dir.rdbms.RdbmsBitPatternDefinition

Field Summary

static char

DEFAULT_SEPARATOR Default separator (',') for concatenated labels.

Method Summary

long[]	convertToGroupValues(long value) Converts a bitpattern to an array of group values.
DeviceMessage	convertToMessage(long value) Converts a bitpattern to a DeviceMessage.
java.lang.String	convertToString(long value) Converts a bitpattern to a label (for an enumeration), or a concatenation of labels for a more complex bitpattern.
java.lang.String	convertToString(long value, char separator) Converts a bitpattern to a string of concatenated labels.
long	convertToValue(java.lang.String label) Converts a label, or a concatenation of labels separated by DEFAULT_SEPARATOR, to a value.
long	convertToValue(java.lang.String labelConcatenation, char separator) Converts a concatenation of labels, with given separator, to a value.
int[]	getFirstBits() Gets array of firstBits for bitgroups.
DeviceMessage[]	getMessages(int firstBit) Gets array of defined messages for bitgroup starting at firstBit
boolean	isEnumeration() Returns true if this bitpattern definition is a simple enumeration
boolean	isThisLabel(long value, java.lang.String label) Return true if this bitpattern 'contains' the label

Methods inherited from interface cdev.dir.DirectoryItem

getDescription, getInfo, getInfoLines, getInfoWidth, getName, getServiceName, toString

Field Detail

DEFAULT_SEPARATOR

public static final char DEFAULT_SEPARATOR

Default separator (',') for concatenated labels.

Method Detail

convertToGroupValues

public long[] convertToGroupValues(long value)

Converts a bitpattern to an array of group values. One value per bitgroup is returned, in the sequence of the bitgroups.

Parameters:

value - the integer to be converted

Returns:

array of group values

convertToMessage

public DeviceMessage convertToMessage(long value)
                               throws NoSuchDataException

Converts a bitpattern to a DeviceMessage. Only the message with the highest level is returned.

Parameters:

value - the integer to be converted

Returns:

most relevant DeviceMessage

Throws:

NoSuchDataException - -

convertToString

public java.lang.String convertToString(long value)
                                 throws NoSuchDataException,
                                        TooManyValuesException

Converts a bitpattern to a label (for an enumeration), or a concatenation of labels for a more complex bitpattern. The separator is DEFAULT_SEPARATOR.

Parameters:

value - the integer to be converted to string

Returns:

the label or concatenated labels corresponding to the value

Throws:

NoSuchDataException - -

TooManyValuesException - -

convertToString

public java.lang.String convertToString(long value,
                                        char separator)
                                 throws NoSuchDataException

Converts a bitpattern to a string of concatenated labels. Returns labels, separated by separator in the sequence of the bitgroups but bitgroups which have no corresponding label are skipped.

Parameters:

value - the integer to be converted

Returns:

concatenation of one or more labels

Throws:

NoSuchDataException - -

convertToValue

public long convertToValue(java.lang.String label)
                    throws NoSuchDataException,
                           TooManyValuesException

Converts a label, or a concatenation of labels separated by DEFAULT_SEPARATOR, to a value.

Parameters:

label - the string to be converted to integer

Returns:

the value of the label

Throws:

NoSuchDataException - -

TooManyValuesException - -

convertToValue

public long convertToValue(java.lang.String labelConcatenation,
                           char separator)
                    throws BadQueryException,
                           NoSuchDataException

Converts a concatenation of labels, with given separator, to a value. The labels may be in any order. For each label in concatenation, bitgroups are searched until the label is found and its groupvalue is packed into the value. The method fails if any of the labels is not found.

Parameters:

labels - the strings to be be packed in the bitpattern

Returns:

the value of the bitpattern

Throws:

NoSuchDataException - -

BadQueryException - -

getFirstBits

public int[] getFirstBits()

Gets array of firstBits for bitgroups.

Returns:

array of firstBits

getMessages

public DeviceMessage[] getMessages(int firstBit)
                            throws BadQueryException

Gets array of defined messages for bitgroup starting at firstBit

Parameters:

firstBit - the first bit of the bitgroup

Returns:

array of messages

Throws:

BadQueryException - if bitgroup is not defined

isEnumeration

public boolean isEnumeration()

Returns true if this bitpattern definition is a simple enumeration

Returns:

true if this is an enumeration

isThisLabel

public boolean isThisLabel(long value,
                           java.lang.String label)

Return true if this bitpattern 'contains' the label

Parameters:

value - the value of the bitpattern seen as an integer

label - the presence of this label must be checked

Returns:

true if this 'contains' the label