com.zebra.sdk.comm

Class MultichannelConnection

Object

com.zebra.sdk.comm.MultichannelConnection

All Implemented Interfaces:

Connection, ConnectionWithWriteLogging

Direct Known Subclasses:

MultichannelRemoteConnection, MultichannelTcpConnection

public abstract class MultichannelConnection
extends Object
implements ConnectionWithWriteLogging

Base class for Link-OS printers which support separate printing and status channels. This class conforms to a standard Connection and if only the Connection methods are used, the SDK will attempt to open both the printing and status channels. MultichannelConnection will use the raw Connection when a method is called directly. Furthermore, when using a ZebraPrinterLinkOs in conjunction with a MultichannelConnection, the ZebraPrinterLinkOs will attempt to use whichever connection is the most efficient. If you wish to only open up a specific channel, use either the openPrintingChannel() or openStatusChannel() method and their corresponding closePrintingChannel() and closeStatusChannel() method.

Method Summary

Methods

Modifier and Type	Method and Description
void	addWriteLogStream(java.io.OutputStream logStream) Adds the OutputStream to the connection to log all data written to the connected device.
int	bytesAvailable() Returns an estimate of the number of bytes that can be read from this connection without blocking.
void	close() Closes both the printing and status channels of this MultichannelConnection.
void	closePrintingChannel() Closes the printing channel of this MultichannelConnection.
void	closeStatusChannel() Closes the status channel of this MultichannelConnection.
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 on the printing channel.
Connection	getPrintingChannel() Returns the underlying printing Connection of this MultichannelConnection.
StatusConnection	getStatusChannel() Returns the underlying status StatusConnection of this MultichannelConnection.
int	getTimeToWaitForMoreData() Returns the maximum time, in milliseconds, to wait in-between reads after the initial read for the printing channel.
boolean	isConnected() Returns true if the connection is open.
void	open() Opens both the printing and status channel of this Multichannel connection.
void	openPrintingChannel() Opens the printing channel of this Multichannel connection.
void	openStatusChannel() Opens the status channel of this Multichannel connection.
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.
void	waitForData(int maxTimeout) Causes the currently executing thread to sleep until Connection.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.

Methods inherited from class Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.zebra.sdk.comm.Connection

getSimpleConnectionName, toString

Method Detail

open

public void open()
          throws ConnectionException

Opens both the printing and status channel of this Multichannel connection. If neither channel can be opened, then a ConnectionException is thrown. When this Multichannel connection is no longer needed, you must call Connection.close() to free up system resources.

Specified by:

open in interface Connection

Throws:

ConnectionException - if the connection cannot be established.

openPrintingChannel

public void openPrintingChannel()
                         throws ConnectionException

Opens the printing channel of this Multichannel connection. If this method is called when this channel has already been opened, the call is ignored. When this channel is no longer needed, you must call either Connection.close() or closePrintingChannel() to free up system resources.

Throws:

ConnectionException - if the connection cannot be established.

openStatusChannel

public void openStatusChannel()
                       throws ConnectionException

Opens the status channel of this Multichannel connection. If this method is called when this channel has already been opened, the call is ignored. When this channel is no longer needed, you must call either Connection.close() or closeStatusChannel() to free up system resources.

Throws:

ConnectionException

close

public void close()
           throws ConnectionException

Closes both the printing and status channels of this MultichannelConnection. Releases any system resources associated with the connection. If the connection is already closed then invoking this method has no effect.

Specified by:

close in interface Connection

Throws:

ConnectionException - if an I/O error occurs.

closePrintingChannel

public void closePrintingChannel()
                          throws ConnectionException

Closes the printing channel of this MultichannelConnection. Releases any system resources associated with the channel. If the channel is already closed then invoking this method has no effect.

Throws:

ConnectionException - if an I/O error occurs.

closeStatusChannel

public void closeStatusChannel()
                        throws ConnectionException

Closes the status channel of this MultichannelConnection. Releases any system resources associated with the channel. If the channel is already closed then invoking this method has no effect.

Throws:

ConnectionException - if an I/O error occurs.

write

public void write(byte[] data)
           throws ConnectionException

Description copied from interface: Connection

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.

Specified by:

write in interface Connection

Parameters:

data - the data.

Throws:

ConnectionException - if an I/O error occurs.

See Also:

Connection.write(byte[])

write

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

Description copied from interface: Connection

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.

Specified by:

write in interface Connection

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:

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

write

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

Description copied from interface: Connection

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.

Specified by:

write in interface Connection

Parameters:

dataSource - the data.

Throws:

ConnectionException - if an I/O error occurs.

See Also:

Connection.write(java.io.InputStream)

read

public byte[] read()
            throws ConnectionException

Description copied from interface: Connection

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

 byte[] data = printerConnection.read();
 

Specified by:

read in interface Connection

Returns:

the bytes read from the connection.

Throws:

ConnectionException - if an I/O error occurs.

See Also:

Connection.read()

read

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

Description copied from interface: Connection

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

Specified by:

read in interface Connection

Parameters:

destinationStream - for read data

Throws:

ConnectionException - if an I/O error occurs.

See Also:

Connection.read(java.io.OutputStream)

readChar

public int readChar()
             throws ConnectionException

Description copied from interface: Connection

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();
 

Specified by:

readChar in interface Connection

Returns:

the next byte from the connection

Throws:

ConnectionException - if an I/O error occurs.

See Also:

Connection.readChar()

isConnected

public boolean isConnected()

Description copied from interface: Connection

Returns true if the connection is open.

Specified by:

isConnected in interface Connection

Returns:

true if this connection is open.

See Also:

Connection.isConnected()

bytesAvailable

public int bytesAvailable()
                   throws ConnectionException

Description copied from interface: Connection

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

Specified by:

bytesAvailable in interface Connection

Returns:

estimated number of bytes available.

Throws:

ConnectionException - if an I/O error occurs.

See Also:

Connection.bytesAvailable()

waitForData

public void waitForData(int maxTimeout)
                 throws ConnectionException

Description copied from interface: Connection

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

Specified by:

waitForData in interface Connection

Parameters:

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

Throws:

ConnectionException - if an I/O error occurs.

See Also:

Connection.waitForData(int)

getMaxTimeoutForRead

public int getMaxTimeoutForRead()

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

Specified by:

getMaxTimeoutForRead in interface Connection

Returns:

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

getTimeToWaitForMoreData

public int getTimeToWaitForMoreData()

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

Specified by:

getTimeToWaitForMoreData in interface Connection

Returns:

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

setMaxTimeoutForRead

public void setMaxTimeoutForRead(int maxTimeoutForRead)

Set the maximum time, in milliseconds, to wait for any data to be received. This sets the timeout for the printing and status channels.

Specified by:

setMaxTimeoutForRead in interface Connection

Parameters:

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

setTimeToWaitForMoreData

public void setTimeToWaitForMoreData(int timeToWaitForMoreData)

Set the maximum time, in milliseconds, to wait in-between reads after the initial read. This sets the timeout for the printing and status channels.

Specified by:

setTimeToWaitForMoreData in interface Connection

Parameters:

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

sendAndWaitForResponse

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

Description copied from interface: Connection

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.

Specified by:

sendAndWaitForResponse in interface Connection

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.

See Also:

Connection.sendAndWaitForResponse(byte[], int, int, java.lang.String)

sendAndWaitForResponse

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

Description copied from interface: Connection

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.

Specified by:

sendAndWaitForResponse in interface Connection

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.

See Also:

Connection.sendAndWaitForResponse(java.io.OutputStream, java.io.InputStream, int, int, java.lang.String)

sendAndWaitForValidResponse

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

Description copied from interface: Connection

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.

Specified by:

sendAndWaitForValidResponse in interface Connection

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.

See Also:

Connection.sendAndWaitForValidResponse(byte[], int, int, com.zebra.sdk.comm.ResponseValidator)

sendAndWaitForValidResponse

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

Description copied from interface: Connection

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.

Specified by:

sendAndWaitForValidResponse in interface Connection

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.

See Also:

Connection.sendAndWaitForValidResponse(java.io.OutputStream, java.io.InputStream, int, int, com.zebra.sdk.comm.ResponseValidator)

getPrintingChannel

public Connection getPrintingChannel()

Returns the underlying printing Connection of this MultichannelConnection.

Returns:

the printing channel.

getStatusChannel

public StatusConnection getStatusChannel()

Returns the underlying status StatusConnection of this MultichannelConnection.

Returns:

the status channel.

getConnectionReestablisher

public ConnectionReestablisher getConnectionReestablisher(long thresholdTime)
                                                   throws ConnectionException

Description copied from interface: Connection

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).

Specified by:

getConnectionReestablisher in interface Connection

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.

See Also:

Connection.getConnectionReestablisher(long thresholdTime)

addWriteLogStream

public void addWriteLogStream(java.io.OutputStream logStream)

Description copied from interface: ConnectionWithWriteLogging

Adds the OutputStream to the connection to log all data written to the connected device.

Specified by:

addWriteLogStream in interface ConnectionWithWriteLogging

Parameters:

logStream - log all write data to this stream.

See Also:

ConnectionWithWriteLogging.addWriteLogStream(OutputStream)