public abstract class ProtocolDevice
extends java.lang.Object
The general idea is that devices have data to be accessed and control points to be managed; however, the exact means to access a given point, such as the state of a door switch, or to control a given function, such as turning on a light, vary greatly from one protocol to another.
To make a more versatile implementation for the application side, the protocol specific configurations will re-map all points of interest to generic data addresses (dataAddress). These generic points then will be accessible using a variety of specific methods for primitive types. Mechanisms will also be provided to access the map, if desired, to find what specific primitive type a given point may be; however, normally, there should probably be some preconceived notion of what data type exists at each address in a given environment and implementation.
If a protocol must extend beyond the primitive types for some reason, there will be the option to use the readObject and writeObject methods. Knowledge about the class of the object used or returned will be specific to the given protocol.
All read functions will return an array whose length is the same as the requested count in the read. Any protocol needing to return more or less data than requested must implement the readObject method.
Constructor and Description |
---|
ProtocolDevice() |
Modifier and Type | Method and Description |
---|---|
abstract void |
configureConnection(java.util.Properties connectionConfig)
configure access to the physical device.
|
void |
configureDataMap(java.util.Properties dataConfig)
configure addressing schemes between the physical device and the client
presentation of the data.
|
abstract void |
configureProtocol(java.util.Properties protocolConfig)
any protocol specific configuration elements would be configured here.
|
abstract void |
connect()
attempt to connect to the field device using the provided configuration.
|
abstract void |
disconnect()
attempt to disconnect from the field device.
|
abstract int |
getConnectStatus()
for expedience, can test the status of the connection prior to attempting
a command.
|
abstract java.lang.String |
getDataType(int dataAddress)
get the primitive data type for the selected address.
|
abstract int |
getEndOfRange(int dataAddress)
gets the last address in a contiguous block of the same type data.
|
abstract java.lang.String |
getProtocolName()
returns the protocol name for the specific protocol implemented.
|
abstract int |
getStartOfRange(int dataAddress)
gets the first address in a contiguous block of the same type data.
|
abstract java.lang.String |
getUnitAddress()
this returns the address given the RTU in the configureProtocol.
|
abstract boolean |
isAddressMapped(int dataAddress)
validate that the protocol has a mapping for the desired address.
|
boolean[] |
readBooleans(int dataAddress,
int count)
read 1 or more boolean points from the attached field device.
|
byte[] |
readBytes(int dataAddress,
int count)
read 1 or more byte points from the attached field device.
|
char[] |
readChars(int dataAddress,
int count)
read 1 or more char points from the attached field device.
|
double[] |
readDoubles(int dataAddress,
int count)
read 1 or more double points from the attached field device.
|
float[] |
readFloats(int dataAddress,
int count)
read 1 or more float points from the attached field device.
|
int[] |
readInts(int dataAddress,
int count)
read 1 or more int points from the attached field device.
|
long[] |
readLongs(int dataAddress,
int count)
read 1 or more long points from the attached field device.
|
java.lang.Object |
readObject(int dataAddress)
read a single object from the address.
|
short[] |
readShorts(int dataAddress,
int count)
read 1 or more short points from the attached field device.
|
long[] |
readUnsignedInts(int dataAddress,
int count)
read 1 or more unsigned int points from the attached field device.
|
int[] |
readUnsignedShorts(int dataAddress,
int count)
read 1 or more unsigned short points from the attached field device.
|
abstract java.lang.String |
toString()
returns the unit name given in the configureProtocol call.
|
void |
writeBooleans(int dataAddress,
boolean[] data)
write 1 or more boolean values to the attached field device.
|
void |
writeBytes(int dataAddress,
byte[] data)
write 1 or more byte values to the attached field device.
|
void |
writeChars(int dataAddress,
char[] data)
write 1 or more char values to the attached field device.
|
void |
writeDoubles(int dataAddress,
double[] data)
write 1 or more double values to the attached field device.
|
void |
writeFloats(int dataAddress,
float[] data)
write 1 or more float values to the attached field device.
|
void |
writeInts(int dataAddress,
int[] data)
write 1 or more int values to the attached field device.
|
void |
writeLongs(int dataAddress,
long[] data)
write 1 or more long values to the attached field device.
|
void |
writeObject(int dataAddress,
java.lang.Object data)
write a single object to the address.
|
void |
writeShorts(int dataAddress,
short[] data)
write 1 or more short values to the attached field device.
|
void |
writeUnsignedInts(int dataAddress,
long[] data)
write 1 or more unsigned int values to the attached field device.
|
void |
writeUnsignedShorts(int dataAddress,
int[] data)
write 1 or more unsigned short values to the attached field device.
|
public abstract java.lang.String toString()
toString
in class java.lang.Object
Object.toString()
public abstract java.lang.String getProtocolName()
public abstract java.lang.String getUnitAddress()
public abstract void configureProtocol(java.util.Properties protocolConfig) throws ProtocolConfigurationInvalidException
protocolConfig
- key/value pairing directly from configuration file or may be
generated.ProtocolConfigurationInvalidException
- unspecified problem with the configurationpublic abstract void configureConnection(java.util.Properties connectionConfig) throws ProtocolConfigurationInvalidException
connectionConfig
- key/value pairing directly from configuration file or may be
generated.ProtocolConfigurationInvalidException
- unspecified problem with the configurationpublic void configureDataMap(java.util.Properties dataConfig) throws ProtocolConfigurationInvalidException, ProtocolMethodNotSupportedException
For most protocols, additional entries may be added to the data mapping at any time and will replace any mapping already existing, without any warning or indication of said replacement. It is not possible to remove a data mapping.
Protocols are not required to implement this method.
dataConfig
- key/value pairing directly from configuration file or may be
generated.ProtocolConfigurationInvalidException
- unspecified problem with the configurationProtocolMethodNotSupportedException
- exception always thrown by default methodpublic abstract int getConnectStatus()
All protocols must implement this method.
ProtocolConnectionStatus
.public abstract void connect() throws ProtocolConfigurationInvalidException
Refer to getConnectStatus
to determine if the
connection is completed.
All protocols must implement this method.
ProtocolConfigurationInvalidException
- this operates on the basic assumption that access to a device
should exist, if the device is unreachable, it is interpreted
as a failure of the configuration.public abstract void disconnect()
All protocols must implement this method.
getConnectStatus()
public abstract boolean isAddressMapped(int dataAddress)
All protocols must implement this method.
dataAddress
- this is the local address, not the field addresspublic abstract int getStartOfRange(int dataAddress) throws ProtocolDataAddressInvalidException
All protocols must implement this method.
dataAddress
- may be the first or last address or anywhere in between for
the range determined.ProtocolDataAddressInvalidException
- the requested data address is not mappedpublic abstract int getEndOfRange(int dataAddress) throws ProtocolDataAddressInvalidException
All protocols must implement this method.
dataAddress
- may be the first or last address or anywhere n between for the
range determined.ProtocolDataAddressInvalidException
- the requested data address is not mappedpublic abstract java.lang.String getDataType(int dataAddress) throws ProtocolDataAddressInvalidException
All protocols must implement this method.
dataAddress
- address of the data point for which the data type is being
requestedPrototocolPrimitiveDataTypes
ProtocolDataAddressInvalidException
- the requested data address is not mappedpublic boolean[] readBooleans(int dataAddress, int count) throws ProtocolDataAddressInvalidException, ProtocolDataTypeInvalidException, ProtocolNotConnectedException, ProtocolTransactionFailureException, ProtocolMethodNotSupportedException
Protocols are not required to implement this method.
dataAddress
- first point to readcount
- count of points to readProtocolDataAddressInvalidException
- at least one of the points in the inclusive range of
addresses is not mappedProtocolDataTypeInvalidException
- at least one of the points in the inclusive range of
addresses is not of type booleanProtocolNotConnectedException
- current connection is in a status other than CONNECTEDProtocolTransactionFailureException
- should include a protocol specific message to help clarify
the cause of the exceptionProtocolMethodNotSupportedException
- exception always thrown by default methodpublic byte[] readBytes(int dataAddress, int count) throws ProtocolDataAddressInvalidException, ProtocolDataTypeInvalidException, ProtocolNotConnectedException, ProtocolTransactionFailureException, ProtocolMethodNotSupportedException
Protocols are not required to implement this method.
dataAddress
- first point to readcount
- count of points to readProtocolDataAddressInvalidException
- at least one of the points in the inclusive range of
addresses is not mappedProtocolDataTypeInvalidException
- at least one of the points in the inclusive range of
addresses is not of type byteProtocolNotConnectedException
- current connection is in a status other than CONNECTEDProtocolTransactionFailureException
- should include a protocol specific message to help clarify
the cause of the exceptionProtocolMethodNotSupportedException
- exception always thrown by default methodpublic char[] readChars(int dataAddress, int count) throws ProtocolDataAddressInvalidException, ProtocolDataTypeInvalidException, ProtocolNotConnectedException, ProtocolTransactionFailureException, ProtocolMethodNotSupportedException
Protocols are not required to implement this method.
dataAddress
- first point to readcount
- count of points to readProtocolDataAddressInvalidException
- at least one of the points in the inclusive range of
addresses is not mappedProtocolDataTypeInvalidException
- at least one of the points in the inclusive range of
addresses is not of type charProtocolNotConnectedException
- current connection is in a status other than CONNECTEDProtocolTransactionFailureException
- should include a protocol specific message to help clarify
the cause of the exceptionProtocolMethodNotSupportedException
- exception always thrown by default methodpublic double[] readDoubles(int dataAddress, int count) throws ProtocolDataAddressInvalidException, ProtocolDataTypeInvalidException, ProtocolNotConnectedException, ProtocolTransactionFailureException, ProtocolMethodNotSupportedException
Protocols are not required to implement this method.
dataAddress
- first point to readcount
- count of points to readProtocolDataAddressInvalidException
- at least one of the points in the inclusive range of
addresses is not mappedProtocolDataTypeInvalidException
- at least one of the points in the inclusive range of
addresses is not of type doubleProtocolNotConnectedException
- current connection is in a status other than CONNECTEDProtocolTransactionFailureException
- should include a protocol specific message to help clarify
the cause of the exceptionProtocolMethodNotSupportedException
- exception always thrown by default methodpublic float[] readFloats(int dataAddress, int count) throws ProtocolDataAddressInvalidException, ProtocolDataTypeInvalidException, ProtocolNotConnectedException, ProtocolTransactionFailureException, ProtocolMethodNotSupportedException
Protocols are not required to implement this method.
dataAddress
- first point to readcount
- count of points to readProtocolDataAddressInvalidException
- at least one of the points in the inclusive range of
addresses is not mappedProtocolDataTypeInvalidException
- at least one of the points in the inclusive range of
addresses is not of type floatProtocolNotConnectedException
- current connection is in a status other than CONNECTEDProtocolTransactionFailureException
- should include a protocol specific message to help clarify
the cause of the exceptionProtocolMethodNotSupportedException
- exception always thrown by default methodpublic int[] readInts(int dataAddress, int count) throws ProtocolDataAddressInvalidException, ProtocolDataTypeInvalidException, ProtocolNotConnectedException, ProtocolTransactionFailureException, ProtocolMethodNotSupportedException
Protocols are not required to implement this method.
dataAddress
- first point to readcount
- count of points to readProtocolDataAddressInvalidException
- at least one of the points in the inclusive range of
addresses is not mappedProtocolDataTypeInvalidException
- at least one of the points in the inclusive range of
addresses is not of type intProtocolNotConnectedException
- current connection is in a status other than CONNECTEDProtocolTransactionFailureException
- should include a protocol specific message to help clarify
the cause of the exceptionProtocolMethodNotSupportedException
- exception always thrown by default methodpublic long[] readUnsignedInts(int dataAddress, int count) throws ProtocolDataAddressInvalidException, ProtocolDataTypeInvalidException, ProtocolNotConnectedException, ProtocolTransactionFailureException, ProtocolMethodNotSupportedException
Protocols are not required to implement this method.
dataAddress
- first point to readcount
- count of points to readProtocolDataAddressInvalidException
- at least one of the points in the inclusive range of
addresses is not mappedProtocolDataTypeInvalidException
- at least one of the points in the inclusive range of
addresses is not of type intProtocolNotConnectedException
- current connection is in a status other than CONNECTEDProtocolTransactionFailureException
- should include a protocol specific message to help clarify
the cause of the exceptionProtocolMethodNotSupportedException
- exception always thrown by default methodpublic long[] readLongs(int dataAddress, int count) throws ProtocolDataAddressInvalidException, ProtocolDataTypeInvalidException, ProtocolNotConnectedException, ProtocolTransactionFailureException, ProtocolMethodNotSupportedException
Protocols are not required to implement this method.
dataAddress
- first point to readcount
- count of points to readProtocolDataAddressInvalidException
- at least one of the points in the inclusive range of
addresses is not mappedProtocolDataTypeInvalidException
- at least one of the points in the inclusive range of
addresses is not of type longProtocolNotConnectedException
- current connection is in a status other than CONNECTEDProtocolTransactionFailureException
- should include a protocol specific message to help clarify
the cause of the exceptionProtocolMethodNotSupportedException
- exception always thrown by default methodpublic java.lang.Object readObject(int dataAddress) throws ProtocolDataAddressInvalidException, ProtocolNotConnectedException, ProtocolTransactionFailureException, ProtocolMethodNotSupportedException
Protocols are not required to implement this method.
dataAddress
- used to reference an object of some type to be readProtocolDataAddressInvalidException
- the dataAddress is not mappedProtocolNotConnectedException
- current connection is in a status other than CONNECTEDProtocolTransactionFailureException
- should include a protocol specific message to help clarify
the cause of the exceptionProtocolMethodNotSupportedException
- exception always thrown by default methodpublic short[] readShorts(int dataAddress, int count) throws ProtocolDataAddressInvalidException, ProtocolDataTypeInvalidException, ProtocolNotConnectedException, ProtocolTransactionFailureException, ProtocolMethodNotSupportedException
Protocols are not required to implement this method.
dataAddress
- first point to readcount
- count of points to readProtocolDataAddressInvalidException
- at least one of the points in the inclusive range of
addresses is not mappedProtocolDataTypeInvalidException
- at least one of the points in the inclusive range of
addresses is not of type shortProtocolNotConnectedException
- current connection is in a status other than CONNECTEDProtocolTransactionFailureException
- should include a protocol specific message to help clarify
the cause of the exceptionProtocolMethodNotSupportedException
- exception always thrown by default methodpublic int[] readUnsignedShorts(int dataAddress, int count) throws ProtocolDataAddressInvalidException, ProtocolDataTypeInvalidException, ProtocolNotConnectedException, ProtocolTransactionFailureException, ProtocolMethodNotSupportedException
Protocols are not required to implement this method.
dataAddress
- first point to readcount
- count of points to readProtocolDataAddressInvalidException
- at least one of the points in the inclusive range of
addresses is not mappedProtocolDataTypeInvalidException
- at least one of the points in the inclusive range of
addresses is not of type shortProtocolNotConnectedException
- current connection is in a status other than CONNECTEDProtocolTransactionFailureException
- should include a protocol specific message to help clarify
the cause of the exceptionProtocolMethodNotSupportedException
- exception always thrown by default methodpublic void writeBooleans(int dataAddress, boolean[] data) throws ProtocolDataAddressInvalidException, ProtocolDataTypeInvalidException, ProtocolNotConnectedException, ProtocolTransactionFailureException, ProtocolMethodNotSupportedException
Protocols are not required to implement this method.
dataAddress
- first address to write todata
- array of 1 or more booleans to write. The data will be written
to consecutive addresses starting with dataAddress.ProtocolDataAddressInvalidException
- at least one of the points in the inclusive range of
addresses is not mappedProtocolDataTypeInvalidException
- at least one of the points in the inclusive range of
addresses is not of type booleanProtocolNotConnectedException
- current connection is in a status other than CONNECTEDProtocolTransactionFailureException
- should include a protocol specific message to help clarify
the cause of the exceptionProtocolMethodNotSupportedException
- exception always thrown by default methodpublic void writeBytes(int dataAddress, byte[] data) throws ProtocolDataAddressInvalidException, ProtocolDataTypeInvalidException, ProtocolNotConnectedException, ProtocolTransactionFailureException, ProtocolMethodNotSupportedException
Protocols are not required to implement this method.
dataAddress
- first address to write todata
- array of 1 or more bytes to write. The data will be written to
consecutive addresses starting with dataAddress.ProtocolDataAddressInvalidException
- at least one of the points in the inclusive range of
addresses is not mappedProtocolDataTypeInvalidException
- at least one of the points in the inclusive range of
addresses is not of type byteProtocolNotConnectedException
- current connection is in a status other than CONNECTEDProtocolTransactionFailureException
- should include a protocol specific message to help clarify
the cause of the exceptionProtocolMethodNotSupportedException
- exception always thrown by default methodpublic void writeChars(int dataAddress, char[] data) throws ProtocolDataAddressInvalidException, ProtocolDataTypeInvalidException, ProtocolNotConnectedException, ProtocolTransactionFailureException, ProtocolMethodNotSupportedException
Protocols are not required to implement this method.
dataAddress
- first address to write todata
- array of 1 or more chars to write. The data will be written to
consecutive addresses starting with dataAddress.ProtocolDataAddressInvalidException
- at least one of the points in the inclusive range of
addresses is not mappedProtocolDataTypeInvalidException
- at least one of the points in the inclusive range of
addresses is not of type charProtocolNotConnectedException
- current connection is in a status other than CONNECTEDProtocolTransactionFailureException
- should include a protocol specific message to help clarify
the cause of the exceptionProtocolMethodNotSupportedException
- exception always thrown by default methodpublic void writeDoubles(int dataAddress, double[] data) throws ProtocolDataAddressInvalidException, ProtocolDataTypeInvalidException, ProtocolNotConnectedException, ProtocolTransactionFailureException, ProtocolMethodNotSupportedException
Protocols are not required to implement this method.
dataAddress
- first address to write todata
- array of 1 or more doubles to write. The data will be written
to consecutive addresses starting with dataAddress.ProtocolDataAddressInvalidException
- at least one of the points in the inclusive range of
addresses is not mappedProtocolDataTypeInvalidException
- at least one of the points in the inclusive range of
addresses is not of type doubleProtocolNotConnectedException
- current connection is in a status other than CONNECTEDProtocolTransactionFailureException
- should include a protocol specific message to help clarify
the cause of the exceptionProtocolMethodNotSupportedException
- exception always thrown by default methodpublic void writeFloats(int dataAddress, float[] data) throws ProtocolDataAddressInvalidException, ProtocolDataTypeInvalidException, ProtocolNotConnectedException, ProtocolTransactionFailureException, ProtocolMethodNotSupportedException
Protocols are not required to implement this method.
dataAddress
- first address to write todata
- array of 1 or more floats to write. The data will be written
to consecutive addresses starting with dataAddress.ProtocolDataAddressInvalidException
- at least one of the points in the inclusive range of
addresses is not mappedProtocolDataTypeInvalidException
- at least one of the points in the inclusive range of
addresses is not of type floatProtocolNotConnectedException
- current connection is in a status other than CONNECTEDProtocolTransactionFailureException
- should include a protocol specific message to help clarify
the cause of the exceptionProtocolMethodNotSupportedException
- exception always thrown by default methodpublic void writeInts(int dataAddress, int[] data) throws ProtocolDataAddressInvalidException, ProtocolDataTypeInvalidException, ProtocolNotConnectedException, ProtocolTransactionFailureException, ProtocolMethodNotSupportedException
Protocols are not required to implement this method.
dataAddress
- first address to write todata
- array of 1 or more ints to write. The data will be written to
consecutive addresses starting with dataAddress.ProtocolDataAddressInvalidException
- at least one of the points in the inclusive range of
addresses is not mappedProtocolDataTypeInvalidException
- at least one of the points in the inclusive range of
addresses is not of type intProtocolNotConnectedException
- current connection is in a status other than CONNECTEDProtocolTransactionFailureException
- should include a protocol specific message to help clarify
the cause of the exceptionProtocolMethodNotSupportedException
- exception always thrown by default methodpublic void writeUnsignedInts(int dataAddress, long[] data) throws ProtocolDataAddressInvalidException, ProtocolDataTypeInvalidException, ProtocolNotConnectedException, ProtocolTransactionFailureException, ProtocolMethodNotSupportedException
Protocols are not required to implement this method.
dataAddress
- first address to write todata
- array of 1 or more longs to write. The data will be written to
consecutive addresses starting with dataAddress.ProtocolDataAddressInvalidException
- at least one of the points in the inclusive range of
addresses is not mappedProtocolDataTypeInvalidException
- at least one of the points in the inclusive range of
addresses is not of type intProtocolNotConnectedException
- current connection is in a status other than CONNECTEDProtocolTransactionFailureException
- should include a protocol specific message to help clarify
the cause of the exceptionProtocolMethodNotSupportedException
- exception always thrown by default methodpublic void writeLongs(int dataAddress, long[] data) throws ProtocolDataAddressInvalidException, ProtocolDataTypeInvalidException, ProtocolNotConnectedException, ProtocolTransactionFailureException, ProtocolMethodNotSupportedException
Protocols are not required to implement this method.
dataAddress
- first address to write todata
- array of 1 or more longs to write. The data will be written to
consecutive addresses starting with dataAddress.ProtocolDataAddressInvalidException
- at least one of the points in the inclusive range of
addresses is not mappedProtocolDataTypeInvalidException
- at least one of the points in the inclusive range of
addresses is not of type longProtocolNotConnectedException
- current connection is in a status other than CONNECTEDProtocolMethodNotSupportedException
- exception always thrown by default methodProtocolTransactionFailureException
public void writeObject(int dataAddress, java.lang.Object data) throws ProtocolDataAddressInvalidException, ProtocolNotConnectedException, ProtocolTransactionFailureException, ProtocolMethodNotSupportedException
Protocols are not required to implement this method.
dataAddress
- used to reference an object of some type to be writtendata
- an Object who's class is protocol dependentProtocolDataAddressInvalidException
- at least one of the points in the inclusive range of
addresses is not mappedProtocolNotConnectedException
- current connection is in a status other than CONNECTEDProtocolTransactionFailureException
- should include a protocol specific message to help clarify
the cause of the exceptionProtocolMethodNotSupportedException
- exception always thrown by default methodpublic void writeShorts(int dataAddress, short[] data) throws ProtocolDataAddressInvalidException, ProtocolDataTypeInvalidException, ProtocolNotConnectedException, ProtocolTransactionFailureException, ProtocolMethodNotSupportedException
Protocols are not required to implement this method.
dataAddress
- first address to write todata
- array of 1 or more shorts to write. The data will be written
to consecutive addresses starting with dataAddress.ProtocolDataAddressInvalidException
- at least one of the points in the inclusive range of
addresses is not mappedProtocolDataTypeInvalidException
- at least one of the points in the inclusive range of
addresses is not of type shortProtocolNotConnectedException
- current connection is in a status other than CONNECTEDProtocolTransactionFailureException
- should include a protocol specific message to help clarify
the cause of the exceptionProtocolMethodNotSupportedException
- exception always thrown by default methodpublic void writeUnsignedShorts(int dataAddress, int[] data) throws ProtocolDataAddressInvalidException, ProtocolDataTypeInvalidException, ProtocolNotConnectedException, ProtocolTransactionFailureException, ProtocolMethodNotSupportedException
Protocols are not required to implement this method.
dataAddress
- first address to write todata
- array of 1 or more ints to write. The data will be written to
consecutive addresses starting with dataAddress.ProtocolDataAddressInvalidException
- at least one of the points in the inclusive range of
addresses is not mappedProtocolDataTypeInvalidException
- at least one of the points in the inclusive range of
addresses is not of type shortProtocolNotConnectedException
- current connection is in a status other than CONNECTEDProtocolTransactionFailureException
- should include a protocol specific message to help clarify
the cause of the exceptionProtocolMethodNotSupportedException
- exception always thrown by default methodCopyright © 2009 Eurotech Inc. All rights reserved.