com.alien.enterpriseRFID.reader
Class AbstractReader

java.lang.Object
  extended bycom.alien.enterpriseRFID.reader.AbstractReader
Direct Known Subclasses:
AlienClass1Reader

public abstract class AbstractReader
extends java.lang.Object

Provides basic functionality for a generic Reader class, handling serial and network communications, and low-level methods for sending commands to a reader and receiving back replies.

AbstractReader is, as it's name suggests, an abstract class, and therefore cannot be instantiated as an object. It's direct subclass, AlienClass1Reader supports all of the passive Alien readers. AlienClassBPTReader, which itself subclasses and inherits from AlienClass1Reader, supports Alien's Battery-Powered Tag readers.

Typically the Reader object will be obtained from a DiscoveryItem object, which is acquired through one of the reader discovery mechanisms (NetworkDiscoveryListenerService and SerialDiscoveryListenerService). However if the location (either serial port name or network address) is known, a Reader object can be instantiated directly without the need of any discovery classes.

Once a valid reader object is available, it offers the user a number of simple methods that implement the full command set described by the Nanoscanner Developers Guide.

Version:
1.6 Feb 2009
Author:
David Krull

Field Summary
static int DEBUG_BYTES
          Specifies the debug level is set to BYTES.
static int DEBUG_OFF
          Specifies the debug level is OFF.
static int DEBUG_TEXT
          Specifies the debug level is set to TEXT.
static int DEFAULT_TIMEOUT
          Specifies the default communication timeout value.
static int TIMEOUTMODE_CHARACTER
          Specifies the receive timeout is for each character of data read.
static int TIMEOUTMODE_COMMAND
          Specifies the receive timeout is for the entire command response.
 
Constructor Summary
AbstractReader()
          Sets the default debug level, the reader timeout, whether to validate an reader when it is opened, and creates a SerialManager if the serial comm libraries are present.
 
Method Summary
 int bringIntoRange(int value, int min, int max)
          Brings an integer value into range.
 void clearInputBuffer()
          Clears data from the input buffer.
 void close()
          Closes the connection with the reader.
 java.lang.String doReaderCommand(java.lang.String command)
          Sends an arbitrary string to the reader, and returns the reader's reply.
 java.lang.String getAddress()
          Returns a human-friendly string describing the reader's address.
 int getDebugLevel()
          Returns the current Debug Level setting.
 java.io.InputStream getInputStream()
          Returns the InputStream that is used to receive replies from the reader.
 java.io.OutputStream getOutputStream()
          Get the OutputStream as a OutputStream
 java.lang.String getReaderReply()
          Returns the full contents of the reader's most recent reply, which generally takes the form of a "keyword=value" phrase.
 java.lang.String getReaderReplyKeyword()
          Returns the "keyword" portion of the reader's most recent reply.
 int getReaderReplyValueInt()
          Returns the "value" portion of the reader's most recent reply, parsed as an int.
 java.lang.String getReaderReplyValueString()
          Returns the "value" portion of the reader's most recent reply, parsed as a String.
 int getTimeOutMilliseconds()
          Returns the maximum time to wait for a reader's reply, in milliseconds.
 int getTimeOutMode()
           
 boolean isOpen()
          Returns true if a connection to the reader has been established.
 boolean isValidateOpen()
          Returns true if the reader is being validated every time it is opened for communication.
 void open()
          Opens a connection to the reader.
 java.lang.String receiveLine()
          Receives a line of string data from the reader.
 java.lang.String receiveString(boolean blockForInput)
          Receives string data from the reader.
 void sendString(java.lang.String text)
          Sends string data to the reader.
 void setAddress(java.lang.String address, int port)
          Set the address for this reader.
 void setConnection(java.lang.String connectionMethod)
          Specifies a reader's connection method, given as a single string.
 void setConnection(java.lang.String networkAddress, int networkPort)
          Sets a reader's connection method to TCP/IP, specifying both address and port.
 void setDebugLevel(int debugLevel)
          Sets the current Debug Level.
 void setInputStream(java.io.InputStream inputStream)
          Set the InputStream as a InputStream
 void setNetworkConnection(java.lang.String networkAddress, int networkPort)
          Specifies the IP Address and Command Channel Port for this reader.
 void setOutputStream(java.io.OutputStream outputStream)
          Set the OutputStream as a OutputStream
 void setSerialBaudRate(int serialBaudRate)
          Tells the Serial Manager to communicate with the reader at a specified baud rate.
 void setSerialConnection(java.lang.String serialPortName)
          Use the serial port given by serialPortName to communicate with this reader.
 void setTimeOutMilliseconds(int timeOutMilliseconds)
          Sets the maximum time to wait for a reader's reply before giving up.
 void setTimeOutMode(int timeoutMode)
           
 void setValidateOpen(boolean validateOpen)
          Specify if the reader should be validated every time it is opened for communications.
 void test()
          Test opens up a connection to the reader and try to communicate with it.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEBUG_OFF

public static final int DEBUG_OFF
Specifies the debug level is OFF.

See Also:
Constant Field Values

DEBUG_TEXT

public static final int DEBUG_TEXT
Specifies the debug level is set to TEXT.

See Also:
Constant Field Values

DEBUG_BYTES

public static final int DEBUG_BYTES
Specifies the debug level is set to BYTES.

See Also:
Constant Field Values

DEFAULT_TIMEOUT

public static final int DEFAULT_TIMEOUT
Specifies the default communication timeout value.

See Also:
Constant Field Values

TIMEOUTMODE_COMMAND

public static final int TIMEOUTMODE_COMMAND
Specifies the receive timeout is for the entire command response.

See Also:
Constant Field Values

TIMEOUTMODE_CHARACTER

public static final int TIMEOUTMODE_CHARACTER
Specifies the receive timeout is for each character of data read.

See Also:
Constant Field Values
Constructor Detail

AbstractReader

public AbstractReader()
Sets the default debug level, the reader timeout, whether to validate an reader when it is opened, and creates a SerialManager if the serial comm libraries are present.

AbstractReader is an abstract class, so the constructor is only called when a subclass is instantiated.

See Also:
AlienClass1Reader, AlienClassBPTReader
Method Detail

getDebugLevel

public int getDebugLevel()
Returns the current Debug Level setting.

Possible values are enumerated by DEBUG_OFF, DEBUG_TEXT, and DEBUT_BYTES.

Returns:
the current level of debugging

setDebugLevel

public void setDebugLevel(int debugLevel)
Sets the current Debug Level.

Setting the Debug Level to DEBUG_TEXT causes the text of every reader command/response to be echoed to stdout. For example, calling getReaderName() with Debug Level set to DEBUG_TEXT displays the following:

      Write: Get ReaderName
      Read: ReaderName = Alien RFID Reader
 
Setting the Debug Level to DEBUG_BYTES causes the raw hex data of every reader command/response to be echoed to stdout. For example, the same getReaderName() call with Debug Level set to DEBUG_BYTES displays the following:
      Write: 01 47 65 74 20 52 65 61 64 65 72 4E 61 6D 65 0D 0A
      Read: 52 65 61 64 65 72 4E 61
      Read: 6D 65 20 3D 20 41 6C 69
      Read: 65 6E 20 52 46 49 44 20
      Read: 52 65 61 64 65 72 0D 0A
      Read: 00
 
This Debug Level shows the additional bytes sent to and received from the reader that are used to prefix and terminate commands and responses.

Setting the Debug Level to DEBUG_OFF turns off these diagnostic messages, which is the default state.

Parameters:
debugLevel - the new Debug Level setting

isValidateOpen

public boolean isValidateOpen()
Returns true if the reader is being validated every time it is opened for communication.

Returns:
true if the reader is validated upon opening, false otherwise

setValidateOpen

public void setValidateOpen(boolean validateOpen)
Specify if the reader should be validated every time it is opened for communications. Validation entails clearing the receive buffer from the reader, then issuing a "get ReaderType" command. A valid reader responds with "Alien" in its ReaderType.

If set to false, just open a connection.
If set to true, open a connection and test for a reader

Parameters:
validateOpen - the new ValidateOpen setting

getTimeOutMilliseconds

public int getTimeOutMilliseconds()
Returns the maximum time to wait for a reader's reply, in milliseconds.

Returns:
the reader timeout, in milliseconds

setTimeOutMilliseconds

public void setTimeOutMilliseconds(int timeOutMilliseconds)
Sets the maximum time to wait for a reader's reply before giving up. If an expected reply from a reader doesn't arrive before the timeout, an exception will be thrown.

Parameters:
timeOutMilliseconds - the length of time to wait, in milliseconds, before a communication attempt fails.

setTimeOutMode

public void setTimeOutMode(int timeoutMode)

getTimeOutMode

public int getTimeOutMode()

setAddress

public void setAddress(java.lang.String address,
                       int port)
Set the address for this reader. If port is greater than zero, assume a network connection. Otherwise assume it is a serial connection, and ignore the port value.

Parameters:
address - either the IP Address (if networked), or "COMx" for serial
port - the port number of the reader's command channel, if networked.

getAddress

public java.lang.String getAddress()
Returns a human-friendly string describing the reader's address.

If connected via a network, returns "Network: xxx.xxx.xxx.xxx:yyy".
If connected via serial, returns "Serial: COMx".
If the connection method is unknown, returns "Unknown".

Returns:
the reader's connection address

setSerialConnection

public void setSerialConnection(java.lang.String serialPortName)
Use the serial port given by serialPortName to communicate with this reader.

serialPortName is of the form "COMx", where x is the com port number.

Parameters:
serialPortName - the serial port that the reader is connected to

setSerialBaudRate

public void setSerialBaudRate(int serialBaudRate)
Tells the Serial Manager to communicate with the reader at a specified baud rate. The default is 115200 bps.

Parameters:
serialBaudRate - the new baud rate for the serial port

setNetworkConnection

public void setNetworkConnection(java.lang.String networkAddress,
                                 int networkPort)
Specifies the IP Address and Command Channel Port for this reader.

Parameters:
networkAddress - the IP Address of the reader
networkPort - the port number of the reader's Command Channel

setConnection

public void setConnection(java.lang.String connectionMethod)
Specifies a reader's connection method, given as a single string.

If connectionMethod contains a colon, it is assumed to be a network address. In this case, connectionMethod is split at the colon, and the resulting two strings are passed to setNetworkConnection(String, int).

Otherwise, it is assumed to be a COM port setting, and the entire string is passed to setSerialConnection(String).

Parameters:
connectionMethod - the "xxx.xxx.xxx.xxx:yyy" or "COMx" version of the address

setConnection

public void setConnection(java.lang.String networkAddress,
                          int networkPort)
Sets a reader's connection method to TCP/IP, specifying both address and port.

Parameters:
networkAddress - the IP Address of the reader
networkPort - the port number of the reader to use for the command channel

open

public void open()
          throws AlienReaderNotValidException,
                 AlienReaderTimeoutException,
                 AlienReaderConnectionRefusedException,
                 AlienReaderConnectionException
Opens a connection to the reader. The connection method is specified by calling setSerialConnection(String) or setNetworkConnection(String, int), or the more general setConnection(String).

A reader must be opened before it is queried for information, or commands are issued.

Throws:
AlienReaderConnectionRefusedException - if the reader refuses the connection
AlienReaderConnectionException - if a connection cannot otherwise be established
AlienReaderNotValidException - if it is not an Alien reader
AlienReaderTimeoutException - if the communication times out
See Also:
close()

isOpen

public boolean isOpen()
Returns true if a connection to the reader has been established. A connection is known to exist if there is a socket open, or if the SerialManager exists and has a serial port assigned.

Returns:
true if a reader connection is open

test

public void test()
          throws AlienReaderConnectionException
Test opens up a connection to the reader and try to communicate with it.

Throws:
AlienReaderConnectionException - if the test failed

close

public void close()
Closes the connection with the reader. There is some overhead involved in opening and closing a connection, so it is recommended that sequences of reader commands be grouped together and bracketed by a single set of open() and close() commands.


getInputStream

public java.io.InputStream getInputStream()
Returns the InputStream that is used to receive replies from the reader. The InputStream is assigned when a network or serial connection is established.

Returns:
inputStream

setInputStream

public void setInputStream(java.io.InputStream inputStream)
Set the InputStream as a InputStream

Parameters:
inputStream - InputStream as a InputStream

getOutputStream

public java.io.OutputStream getOutputStream()
Get the OutputStream as a OutputStream

Returns:
outputStream as a OutputStream

setOutputStream

public void setOutputStream(java.io.OutputStream outputStream)
Set the OutputStream as a OutputStream

Parameters:
outputStream - OutputStream as a OutputStream

doReaderCommand

public java.lang.String doReaderCommand(java.lang.String command)
                                 throws AlienReaderTimeoutException,
                                        AlienReaderConnectionException,
                                        AlienReaderCommandErrorException
Sends an arbitrary string to the reader, and returns the reader's reply.

Not every possible reader command is surfaced in the Alien RFID Java API. This command fills that gap, as well as providing extensibility with the current API if the reader's capabilities change. Under the hood, all reader commands coming from the API use this method to talk to the reader.

The return value for this command is the raw reply string from the reader. If the reply is of the form Keyword=Value, methods exist for extracting just the Keyword or Value portions of the reply.

Parameters:
command - the command string to send (CR/LF will be added automatically)
Returns:
the reader's entire reply string
Throws:
AlienReaderConnectionException - if communication failed
AlienReaderTimeoutException - if communication times out
AlienReaderCommandErrorException - if the reader responds with an error
See Also:
getReaderReply(), getReaderReplyKeyword(), getReaderReplyValueString(), getReaderReplyValueInt()

getReaderReply

public java.lang.String getReaderReply()
Returns the full contents of the reader's most recent reply, which generally takes the form of a "keyword=value" phrase. For example, if the most recent command was setReaderName("foo"), this method will return the reader's reply: "ReaderName = foo"

To get just the "keyword" portion of the reply, use getReaderReplyKeyword().

To get just the "value" portion of the reply, use getReaderReplyValueString() or getReaderReplyValueInt(), depending on the expected data type of the reply.

Returns:
the entire contents of the reader's most recent reply
See Also:
getReaderReplyKeyword(), getReaderReplyValueString(), getReaderReplyValueInt()

getReaderReplyKeyword

public java.lang.String getReaderReplyKeyword()
Returns the "keyword" portion of the reader's most recent reply. For example, if the most recent command was setReaderName("foo"), the expected reply from the reader would be "ReaderName = foo". This method would return "ReaderName".

To get the entire reply, use getReaderReply().

To get just the "value" portion of the reply, use getReaderReplyValueString() or getReaderReplyValueInt(), depending on the expected data type of the reply.

Returns:
the "keyword" portion of the reader's most recent reply
See Also:
getReaderReply(), getReaderReplyValueString(), getReaderReplyValueInt()

getReaderReplyValueString

public java.lang.String getReaderReplyValueString()
Returns the "value" portion of the reader's most recent reply, parsed as a String. For example, if the most recent command was setReaderName("foo"), the expected reply from the reader would be "ReaderName = foo". This method would return "foo".

To get the entire reply, use getReaderReply().

To get just the keyword portion of the reply, use getReaderReplyKeyword().

To get just the "value" portion of the reply as an int, use getReaderReplyValueInt().

Returns:
the "value" portion of the reader's most recent reply, as a String
See Also:
getReaderReply(), getReaderReplyKeyword(), getReaderReplyValueInt()

getReaderReplyValueInt

public int getReaderReplyValueInt()
Returns the "value" portion of the reader's most recent reply, parsed as an int. For example, if the most recent command was setAutoStopTimer(1000), the expected reply from the reader would be "AutoStopTimer (ms) = 1000". This method would return 1000.

To get the entire reply, use getReaderReply().

To get just the keyword portion of the reply, use getReaderReplyKeyword().

To get just the "value" portion of the reply as a String, use getReaderReplyValueString().

Returns:
the "value" portion of the reader's most recent reply, as an int
See Also:
getReaderReply(), getReaderReplyKeyword(), getReaderReplyValueString()

clearInputBuffer

public void clearInputBuffer()
Clears data from the input buffer. If sendString() is used without corresponding receiveString() calls, the input buffer will contain all of the reader's responses. Use this method to clear the input buffer.


sendString

public void sendString(java.lang.String text)
                throws AlienReaderConnectionException
Sends string data to the reader.

Parameters:
text - the text string to send
Throws:
AlienReaderConnectionException - if communication fails

receiveString

public java.lang.String receiveString(boolean blockForInput)
                               throws AlienReaderTimeoutException,
                                      AlienReaderCommandErrorException
Receives string data from the reader. If blockForInput is set, this method will wait for input, terminated by a null character before returning or timing out. If blockForInput is false, this method will return immediately with any data in the input buffer.

Parameters:
blockForInput - true means wait for a terminating null character
Returns:
the text string read (may be a multiline string)
Throws:
AlienReaderTimeoutException - if reader communication times out
AlienReaderCommandErrorException - if the reader returns a error in response

receiveLine

public java.lang.String receiveLine()
                             throws AlienReaderTimeoutException,
                                    AlienReaderCommandErrorException
Receives a line of string data from the reader. A line of data ends in a [cr][lf] sequence.

Returns:
the text string read (may be a multiline string)
Throws:
AlienReaderTimeoutException - if reader communication times out
AlienReaderCommandErrorException - if the reader returns a error in response

bringIntoRange

public int bringIntoRange(int value,
                          int min,
                          int max)
Brings an integer value into range. If value is less than min then min is returned. If value is greater than max then max is returned. Otherwise, value is returned unchanged.

Parameters:
value - the integer value to test
min - the minimum value
max - the maximum value
Returns:
the value withing the given range