com.maverick.sshd
Class Channel

java.lang.Object
  com.maverick.sshd.Channel

Direct Known Subclasses:

ForwardingChannel, SessionChannel

public abstract class Channel

extends java.lang.Object

This abstract class provides the basic functions of an SSH2 channel. All terminal sessions, forwarded connections etc, are channels. Either side may open a channel and multiple channels are multiplexed into a single connection. Channels are flow-controlled so that no data may be sent to a channel until a message is received to indicate that a window space is available.

Channel implementations are identified by name and to support the opening of a channel your server should add the channel's unique name to the com.maverick.sshd.ConfigurationContext#supportedChannels(). This can be completed in your com.maverick.sshd.SshDaemon#configure(ConfigurationContext) method.

 protected void configure(ConfigurationContext context) {
    context.supportedChannels().add(
        "chat@sshtools.com",
        Class.forName("com.sshtools.ChatChannel"));
 }
 

Data sent by the channel is buffered and sent when window space is available on the remote side. The incoming window space is decremented whenever data is received with the abstract evaluateWindowSpace(int) method being called to enable the channel implementation to add further window space should it require.

Author:

Lee David Painter

Nested Class Summary

protected class

Channel.QueuedData

Field Summary

protected ConnectionProtocol	connection The Connection Protocol instance managing this session, use this instance to disconnect the session or obtain the ip address of the remote client.
protected int	localwindow
protected java.lang.Object	localWindowLock

Constructor Summary

Channel(java.lang.String channelType, int maximumPacketSize, int initialWindowSize)
Construct a channel with the specified settings.

Method Summary

void	addEventListener(ChannelEventListener listener) Enable other objects to receive channel events
void	addInputListener(java.io.OutputStream out) Add an OutputStream to receive all channel data input from the remote side of the connection.
void	addOutputListener(java.io.OutputStream out) Add an OutputStream to receive all of the channels output.
protected boolean	canClose() Can this channel close?
void	close() This method closes the channel and free's its resources.
protected abstract byte[]	createChannel() Called when the channel is being created.
protected abstract void	evaluateWindowSpace(int remaining) Called to evaluate the window space available.
java.lang.String	getChannelType() The name of this channel.
ConnectionProtocol	getConnection() Returns the ConnectionProtocol associated with this channel.
SshContext	getContext() Get the current configuration from the underlying connection.
int	getLocalId() The local channel id
int	getLocalPacket() The maximum size of a single packet that the local side will accept.
int	getLocalWindow() The current size of the local data window.
int	getQueueSize()
int	getRemoteId() The remote sides channel id
int	getRemotePacket() The maximum size of a single packet that the remote side will accept.
int	getRemoteWindow() The current size of the remote data window.
byte[]	getSessionIdentifier() Get the session id for the current connection.
protected boolean	hasQueuedData()
boolean	isClosed() Indicates the channel has been closed
boolean	isClosing() Indicates whether the channel is currently performing a close operation
boolean	isEOF() Indicates that the channel is EOF (it will not be receiving any more data from the remote side).
protected boolean	isOpen() Get the open state of the channel.
protected abstract void	onChannelClosed() Called when the channel has been closed to enable resources to be freed.
protected abstract void	onChannelClosing() Called before the channel is closed
protected abstract void	onChannelData(byte[] data) Called by the channel when data arrives from the remote side.
protected abstract void	onChannelFree() This method is called when the channel has been closed and all its resources are no longer required.
protected abstract void	onChannelOpen() Called when the channel has been opened - this method is only called when the remote side requests a channel open.
protected abstract void	onChannelOpenConfirmation() Called when the channel has been confirmed as open by the remote side - this method is only called when the channel has been requested by this side of the connection
protected void	onChannelOpenFailure() Called when the remote side fails to open a channel in response to our request.
protected abstract void	onChannelRequest(java.lang.String type, boolean wantreply, byte[] requestdata) Called when a channel request is received.
protected abstract void	onExtendedData(byte[] data, int type) Called by the channel when extended data arrives
protected abstract void	onLocalEOF() Called when the local side is EOF.
protected void	onRemoteClose() Called when the remote side closes the channel.
protected abstract void	onRemoteEOF() Called when the remote side reports its OutputStream as EOF.
protected void	onWindowAdjust(int count)
protected abstract byte[]	openChannel(byte[] requestdata) Called when the channel is being opened.
protected int	queueSize()
protected void	registerExtendedData(int type) Call this method to register an extended data type.
void	resetIdleState(IdleStateListener listener) Allows a channel to register and receive idle state events.
void	sendChannelData(byte[] data) Send channel data to the remote side of the channel.
void	sendChannelData(byte[] data, int off, int len) Send channel data to the remote side of the channel.
void	sendChannelData(byte[] data, int off, int len, java.lang.Runnable r)
void	sendChannelData(byte[] data, java.lang.Runnable r)
void	sendChannelDataWithBuffering(byte[] data) Send channel data to the remote side of the channel and block until the data has been added to the local buffer.
void	sendChannelDataWithBuffering(byte[] data, int off, int len) Send channel data to the remote side of the channel and block until the data has been sent.
protected void	sendChannelRequest(java.lang.String type, boolean wantreply, byte[] requestdata) Send a channel request.
protected void	sendExtendedData(byte[] data, int type) Send extended channel data.
protected void	sendExtendedData(byte[] data, int off, int len, int type) Send extended channel data.
protected void	sendRequestResponse(boolean succeeded) Send a channel request.
protected void	sendWindowAdjust(int count) Adjust the local window by adding more bytes.

Methods inherited from class java.lang.Object

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

Field Detail

connection

protected ConnectionProtocol connection

The Connection Protocol instance managing this session, use this instance to disconnect the session or obtain the ip address of the remote client.

localwindow

protected int localwindow

localWindowLock

protected java.lang.Object localWindowLock

Constructor Detail

Channel

public Channel(java.lang.String channelType,
               int maximumPacketSize,
               int initialWindowSize)

Construct a channel with the specified settings.

Parameters:

channelType - the name of the channel, for example "session" or "tcpip-forward"

maximumPacketSize - the maximum size of an individual packet that the remote side can send through the channel

initialWindowSize - the initial size of the local window.

Method Detail

isClosed

public boolean isClosed()

Indicates the channel has been closed

Returns:

boolean

isEOF

public boolean isEOF()

Indicates that the channel is EOF (it will not be receiving any more data from the remote side).

Returns:

boolean

getQueueSize

public int getQueueSize()

resetIdleState

public void resetIdleState(IdleStateListener listener)

Allows a channel to register and receive idle state events. Call this method to reset the idle state of a channel (i.e when activity has occurred). The IdleStateListener instance passed as a parameter will receive notification once the channel reaches an idle state.

Parameters:

listener - IdleStateListener

addEventListener

public void addEventListener(ChannelEventListener listener)

Enable other objects to receive channel events

Parameters:

listener -

addInputListener

public void addInputListener(java.io.OutputStream out)

Add an OutputStream to receive all channel data input from the remote side of the connection.

Parameters:

out - OutputStream

addOutputListener

public void addOutputListener(java.io.OutputStream out)

Add an OutputStream to receive all of the channels output.

Parameters:

out - OutputStream

getChannelType

public java.lang.String getChannelType()

The name of this channel.

Returns:

String

getRemoteWindow

public int getRemoteWindow()

The current size of the remote data window.

Returns:

int

getLocalWindow

public int getLocalWindow()

The current size of the local data window.

Returns:

int

getLocalPacket

public int getLocalPacket()

The maximum size of a single packet that the local side will accept.

Returns:

int

getRemotePacket

public int getRemotePacket()

The maximum size of a single packet that the remote side will accept.

Returns:

int

getLocalId

public int getLocalId()

The local channel id

Returns:

int

getRemoteId

public int getRemoteId()

The remote sides channel id

Returns:

int

queueSize

protected int queueSize()

registerExtendedData

protected void registerExtendedData(int type)
                             throws java.io.IOException

Call this method to register an extended data type. This must be performed when using extended data so that the server can buffer data individually for each extended data type. It is recommended that extended data be registered when the channel is being created or opened.

Parameters:

type -

Throws:

java.io.IOException

getSessionIdentifier

public byte[] getSessionIdentifier()

Get the session id for the current connection.

Returns:

byte[]

onWindowAdjust

protected void onWindowAdjust(int count)

hasQueuedData

protected boolean hasQueuedData()

getConnection

public ConnectionProtocol getConnection()

Returns the ConnectionProtocol associated with this channel.

Returns:

ConnectionProtocol

sendChannelData

public void sendChannelData(byte[] data)

Send channel data to the remote side of the channel. The byte array passed into this method will be sent asynchronously so ensure that no other class has access to this after this method returns, failing to do so may cause data corruption.

Parameters:

data -

sendChannelData

public void sendChannelData(byte[] data,
                            java.lang.Runnable r)

sendChannelData

public void sendChannelData(byte[] data,
                            int off,
                            int len)

Send channel data to the remote side of the channel. The byte array passed into this method will be sent asynchronously so ensure that no other class has access to this after this method returns, failing to do so may cause data corruption.

Parameters:

data -

off -

len -

sendChannelData

public void sendChannelData(byte[] data,
                            int off,
                            int len,
                            java.lang.Runnable r)

sendChannelDataWithBuffering

public void sendChannelDataWithBuffering(byte[] data)

Send channel data to the remote side of the channel and block until the data has been added to the local buffer. The local buffer is 131072 bytes in length and has been designed to overcome the problem of external threads adding too much data to the queue. DO NOT call this method if the current thread is the same as the selector thread as this will cause a deadlock.

Parameters:

data - byte[]

sendChannelDataWithBuffering

public void sendChannelDataWithBuffering(byte[] data,
                                         int off,
                                         int len)

Send channel data to the remote side of the channel and block until the data has been sent. DO NOT call this method if the current thread is the same as the selector thread.

Parameters:

data - byte[]

off - int

len - int

getContext

public SshContext getContext()

Get the current configuration from the underlying connection.

Returns:

ConfigurationContext

sendExtendedData

protected void sendExtendedData(byte[] data,
                                int type)

Send extended channel data. This data is sent as an extended 'type' which should be known by the channel at the remote side. For example within a session channel an extended data type is used to transfer stderr data from the server to the client.

Parameters:

data -

type -

sendExtendedData

protected void sendExtendedData(byte[] data,
                                int off,
                                int len,
                                int type)

Send extended channel data. This data is sent as an extended 'type' which should be known by the channel at the remote side. For example within a session channel an extended data type is used to transfer stderr data from the server to the client.

Parameters:

data -

off -

len -

type -

onChannelData

protected abstract void onChannelData(byte[] data)

Called by the channel when data arrives from the remote side.

Parameters:

data -

onExtendedData

protected abstract void onExtendedData(byte[] data,
                                       int type)

Called by the channel when extended data arrives

Parameters:

data -

sendChannelRequest

protected void sendChannelRequest(java.lang.String type,
                                  boolean wantreply,
                                  byte[] requestdata)

Send a channel request. Many channel types have extensions that are specific to that particular channel type. An example is requresting a pty (pseudo terminal) for an interactive session. This method enables the sending of channel requests but does not support receiving responses. This should not present a problem as server implementations tend to send messages as one way information, for example the exit-status request of an interactive session.

To handle requests from a client implement onChannelRequest(String,boolean,byte[]).

Parameters:

type -

wantreply -

requestdata -

onChannelOpenFailure

protected void onChannelOpenFailure()

Called when the remote side fails to open a channel in response to our request. It only makes sense for some channel types to override this method. A local forwarding channel will never receive this message for example.

onRemoteClose

protected void onRemoteClose()

Called when the remote side closes the channel. Override this method to change the default behaviour of instantly closing the channel unless there is buffered data remaining

isClosing

public boolean isClosing()

Indicates whether the channel is currently performing a close operation

Returns:

boolean

close

public void close()

This method closes the channel and free's its resources.

onChannelFree

protected abstract void onChannelFree()

This method is called when the channel has been closed and all its resources are no longer required.

createChannel

protected abstract byte[] createChannel()
                                 throws java.io.IOException

Called when the channel is being created. You can return data to be sent in the channel open request, or null for none.

Returns:

byte[]

Throws:

java.io.IOException

openChannel

protected abstract byte[] openChannel(byte[] requestdata)
                               throws WriteOperationRequest,
                                      ChannelOpenException

Called when the channel is being opened. You can retrun data to be sent in the channel open confirmation message, or null for none.

Parameters:

requestdata -

Returns:

byte[]

Throws:

WriteOperationRequest

ChannelOpenException

onChannelOpenConfirmation

protected abstract void onChannelOpenConfirmation()

Called when the channel has been confirmed as open by the remote side - this method is only called when the channel has been requested by this side of the connection

onChannelClosed

protected abstract void onChannelClosed()

Called when the channel has been closed to enable resources to be freed.

onChannelOpen

protected abstract void onChannelOpen()

Called when the channel has been opened - this method is only called when the remote side requests a channel open.

onChannelClosing

protected abstract void onChannelClosing()

Called before the channel is closed

onChannelRequest

protected abstract void onChannelRequest(java.lang.String type,
                                         boolean wantreply,
                                         byte[] requestdata)

Called when a channel request is received.

Parameters:

type -

wantreply -

requestdata -

evaluateWindowSpace

protected abstract void evaluateWindowSpace(int remaining)

Called to evaluate the window space available. Send a window adjust message if there if the minimum amount of space is not available.

Parameters:

remaining -

onRemoteEOF

protected abstract void onRemoteEOF()

Called when the remote side reports its OutputStream as EOF.

canClose

protected boolean canClose()

Can this channel close?

Returns:

true if there is no queued data, else false

onLocalEOF

protected abstract void onLocalEOF()

Called when the local side is EOF.

isOpen

protected boolean isOpen()

Get the open state of the channel.

Returns:

boolean

sendRequestResponse

protected void sendRequestResponse(boolean succeeded)

Send a channel request.

Parameters:

succeeded -

sendWindowAdjust

protected void sendWindowAdjust(int count)

Adjust the local window by adding more bytes.

Parameters:

count -