Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.alien.enterpriseRFID.reader
Class AbstractReader

    java.lang.Object
      com.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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD