com.zebra.sdk.comm

Interface Connection

All Known Subinterfaces:

ConnectionWithWriteLogging

All Known Implementing Classes:

ConnectionA, TcpConnection, UsbConnection

public interface Connection

A connection to a device.

Method Summary

Methods

Modifier and Type	Method and Description
int	bytesAvailable() Returns an estimate of the number of bytes that can be read from this connection without blocking.
void	close() Closes this connection and releases any system resources associated with the connection.
com.zebra.sdk.comm.ConnectionReestablisher	getConnectionReestablisher(long thresholdTime) Returns a ConnectionReestablisher which allows for easy recreation of a connection which may have been closed.
int	getMaxTimeoutForRead() Returns the maximum time, in milliseconds, to wait for any data to be received.
String	getSimpleConnectionName() Return a human-readable description of the connection.
int	getTimeToWaitForMoreData() Returns the maximum time, in milliseconds, to wait in-between reads after the initial read.
boolean	isConnected() Returns true if the connection is open.
void	open() Opens the connection to a device.
byte[]	read() Reads all the available data from the connection.
void	read(java.io.OutputStream destinationStream) Reads all the available data from the connection.
int	readChar() Reads the next byte of data from the connection, similar to a Java InputStream.
byte[]	sendAndWaitForResponse(byte[] dataToSend, int initialResponseTimeout, int responseCompletionTimeout, String terminator) Sends dataToSend and returns the response data.
void	sendAndWaitForResponse(java.io.OutputStream destinationStream, java.io.InputStream sourceStream, int initialResponseTimeout, int responseCompletionTimeout, String terminator) Sends data from sourceStream and writes the response data to destinationStream.
byte[]	sendAndWaitForValidResponse(byte[] dataToSend, int initialResponseTimeout, int responseCompletionTimeout, ResponseValidator validator) Sends dataToSend and returns the response data.
void	sendAndWaitForValidResponse(java.io.OutputStream destinationStream, java.io.InputStream sourceStream, int initialResponseTimeout, int responseCompletionTimeout, ResponseValidator validator) Sends data from sourceStream and writes the response data to destinationStream.
void	setMaxTimeoutForRead(int maxTimeoutForRead) Set the maximum time, in milliseconds, to wait for any data to be received
void	setTimeToWaitForMoreData(int timeToWaitForMoreData) Set the maximum time, in milliseconds, to wait in-between reads after the initial read.
String	toString() See the classes which implement this method for the format of the description string.
void	waitForData(int maxTimeout) Causes the currently executing thread to sleep until bytesAvailable() > 0, or for a maximum of maxTimeout milliseconds.
void	write(byte[] data) Writes data.length bytes from the specified byte array to this output stream.
void	write(byte[] data, int offset, int length) Writes length bytes from data starting at offset.
void	write(java.io.InputStream dataSource) Writes all available bytes from the data source to this output stream.

Method Detail

open

void open()
          throws ConnectionException

Opens the connection to a device. If the open method is called when this connection has already been opened, this call is ignored. When a handle to the connection is no longer needed, you must call close() to free up system resources.

Throws:

ConnectionException - if the connection cannot be established.

close

void close()
           throws ConnectionException

Closes this connection and releases any system resources associated with the connection. If the connection is already closed then invoking this method has no effect.

Throws:

ConnectionException - if an I/O error occurs.

write

void write(byte[] data)
           throws ConnectionException

Writes data.length bytes from the specified byte array to this output stream. The connection must be open before this method is called. If write is called when a connection is closed, a ConnectionException is thrown.

Parameters:

data - the data.

Throws:

ConnectionException - if an I/O error occurs.

See Also:

OutputStream.write(byte[])

write

void write(byte[] data,
         int offset,
         int length)
           throws ConnectionException

Writes length bytes from data starting at offset. The connection must be open before this method is called. If write is called when a connection is closed, a ConnectionException is thrown.

Parameters:

data - the data.

offset - the start offset in the data.

length - number of bytes to write.

Throws:

ConnectionException - if an I/O error occurs.

See Also:

OutputStream.write(byte[], int, int)

write

void write(java.io.InputStream dataSource)
           throws ConnectionException

Writes all available bytes from the data source to this output stream. The connection must be open before this method is called. If write is called when a connection is closed, a ConnectionException is thrown.

Parameters:

dataSource - the data.

Throws:

ConnectionException - if an I/O error occurs.

read

byte[] read()
            throws ConnectionException

Reads all the available data from the connection. This call is non-blocking.

 byte[] data = printerConnection.read();
 

Returns:

the bytes read from the connection.

Throws:

ConnectionException - if an I/O error occurs.

readChar

int readChar()
             throws ConnectionException

Reads the next byte of data from the connection, similar to a Java InputStream. The value byte is returned as an int in the range of 0 to 255. If no byte is available on the connection the value -1 is returned.

 int singleCharacter = printerConnection.readChar();
 

Returns:

the next byte from the connection

Throws:

ConnectionException - if an I/O error occurs.

read

void read(java.io.OutputStream destinationStream)
          throws ConnectionException

Reads all the available data from the connection. This call is non-blocking.

Parameters:

destinationStream - for read data

Throws:

ConnectionException - if an I/O error occurs.

isConnected

boolean isConnected()

Returns true if the connection is open.

Returns:

true if this connection is open.

bytesAvailable

int bytesAvailable()
                   throws ConnectionException

Returns an estimate of the number of bytes that can be read from this connection without blocking.

Returns:

estimated number of bytes available.

Throws:

ConnectionException - if an I/O error occurs.

toString

String toString()

See the classes which implement this method for the format of the description string.

Overrides:

toString in class Object

Returns:

the connection description string.

getSimpleConnectionName

String getSimpleConnectionName()

Return a human-readable description of the connection.

Returns:

a human-readable description of the connection.

waitForData

void waitForData(int maxTimeout)
                 throws ConnectionException

Causes the currently executing thread to sleep until bytesAvailable() > 0, or for a maximum of maxTimeout milliseconds.

Parameters:

maxTimeout - maximum time in milliseconds to wait for an initial response from the printer.

Throws:

ConnectionException - if an I/O error occurs.

getMaxTimeoutForRead

int getMaxTimeoutForRead()

Returns the maximum time, in milliseconds, to wait for any data to be received.

Returns:

the maximum time, in milliseconds, to wait for any data to be received.

getTimeToWaitForMoreData

int getTimeToWaitForMoreData()

Returns the maximum time, in milliseconds, to wait in-between reads after the initial read.

Returns:

the maximum time, in milliseconds, to wait in-between reads after the initial read.

setMaxTimeoutForRead

void setMaxTimeoutForRead(int maxTimeoutForRead)

Set the maximum time, in milliseconds, to wait for any data to be received

Parameters:

maxTimeoutForRead - the maximum time, in milliseconds, to wait for any data to be received.

setTimeToWaitForMoreData

void setTimeToWaitForMoreData(int timeToWaitForMoreData)

Set the maximum time, in milliseconds, to wait in-between reads after the initial read.

Parameters:

timeToWaitForMoreData - the maximum time, in milliseconds, to wait in-between reads after the initial read.

sendAndWaitForResponse

byte[] sendAndWaitForResponse(byte[] dataToSend,
                            int initialResponseTimeout,
                            int responseCompletionTimeout,
                            String terminator)
                              throws ConnectionException

Sends dataToSend and returns the response data. The software returns immediately if the data received contains terminator. The connection must be open before this method is called. If sendAndWaitForResponse is called when a connection is closed, a ConnectionException is thrown.

Parameters:

dataToSend - byte array of data to send

initialResponseTimeout - The maximum time, in milliseconds, to wait for the initial response to be received. If no data is received during this time, the function returns a zero length array.

responseCompletionTimeout - After the initial response, if no data is received for this period of time, the input is considered complete and the method returns.

terminator - If the response contains this string, the input is considered complete and the method returns. May be used to avoid waiting for more data when the response is always terminated with a known string. Use null if no terminator is desired.

Returns:

received data

Throws:

ConnectionException - if an I/O error occurs.

sendAndWaitForResponse

void sendAndWaitForResponse(java.io.OutputStream destinationStream,
                          java.io.InputStream sourceStream,
                          int initialResponseTimeout,
                          int responseCompletionTimeout,
                          String terminator)
                            throws ConnectionException

Sends data from sourceStream and writes the response data to destinationStream. The software returns immediately if the data received contains terminator. The connection must be open before this method is called. If sendAndWaitForResponse is called when a connection is closed, a ConnectionException is thrown.

Parameters:

destinationStream - Destination for response.

sourceStream - Source of data to be sent.

initialResponseTimeout - The maximum time, in milliseconds, to wait for the initial response to be received. If no data is received during this time, the function does not write any data to the destination stream.

responseCompletionTimeout - After the initial response, if no data is received for this period of time, the input is considered complete and the method returns.

terminator - If the response contains this string, the input is considered complete and the method returns. May be used to avoid waiting for more data when the response is always terminated with a known string. Use null if no terminator is desired.

Throws:

ConnectionException - if an I/O error occurs.

sendAndWaitForValidResponse

byte[] sendAndWaitForValidResponse(byte[] dataToSend,
                                 int initialResponseTimeout,
                                 int responseCompletionTimeout,
                                 ResponseValidator validator)
                                   throws ConnectionException

Sends dataToSend and returns the response data. The software returns immediately if the data received satisfies validator. The connection must be open before this method is called. If sendAndWaitForResponse is called when a connection is closed, a ConnectionException is thrown.

Parameters:

dataToSend - byte array of data to send

initialResponseTimeout - The maximum time, in milliseconds, to wait for the initial response to be received. If no data is received during this time, the function returns a zero length array.

responseCompletionTimeout - After the initial response, if no data is received for this period of time, the input is considered complete and the method returns.

validator - If the response satisfies this validator, the input is considered complete and the method returns. May be used to avoid waiting for more data when the response follows a known format.

Returns:

received data

Throws:

ConnectionException - if an I/O error occurs.

sendAndWaitForValidResponse

void sendAndWaitForValidResponse(java.io.OutputStream destinationStream,
                               java.io.InputStream sourceStream,
                               int initialResponseTimeout,
                               int responseCompletionTimeout,
                               ResponseValidator validator)
                                 throws ConnectionException

Sends data from sourceStream and writes the response data to destinationStream. The software returns immediately if the data received satisfies validator. The connection must be open before this method is called. If sendAndWaitForResponse is called when a connection is closed, a ConnectionException is thrown.

Parameters:

destinationStream - Destination for response.

sourceStream - Source of data to be sent.

initialResponseTimeout - The maximum time, in milliseconds, to wait for the initial response to be received. If no data is received during this time, the function does not write any data to the destination stream.

responseCompletionTimeout - After the initial response, if no data is received for this period of time, the input is considered complete and the method returns.

validator - If the response satisfies this validator, the input is considered complete and the method returns. May be used to avoid waiting for more data when the response follows a known format. If validator is null, no validation is performed. When performing validation, this method will use enough memory to hold the entire response.

Throws:

ConnectionException - if an I/O error occurs.

getConnectionReestablisher

com.zebra.sdk.comm.ConnectionReestablisher getConnectionReestablisher(long thresholdTime)
                                                                      throws ConnectionException

Returns a ConnectionReestablisher which allows for easy recreation of a connection which may have been closed.

• This call should be made while there is still an active connection to the printer (prior to issuing a command which will make the printer non-responsive).

Parameters:

thresholdTime - how long the Connection reestablisher will wait before attempting to reconnection to the printer

Returns:

ConnectionReestablisher

Throws:

ConnectionException - if the ConnectionReestablisher could not be created.