com.maverick.sshd
Class Channel

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

All Implemented Interfaces:

com.maverick.ssh.components.SshComponent

Direct Known Subclasses:

ForwardingChannel, SessionChannel

public abstract class Channel
extends Object
implements com.maverick.ssh.components.SshComponent

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 long	localwindow
protected Object	localWindowLock
protected int	state

Constructor Summary

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

Method Summary

void	addEventListener(ChannelEventListener listener) Enable other objects to receive channel events
void	addInputListener(OutputStream out) Add an OutputStream to receive all channel data input from the remote side of the connection.
void	addOutputListener(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(long remaining) Called to evaluate the window space available.
ConnectionProtocol	getConnection() Returns the ConnectionProtocol associated with this channel.
SshContext	getContext() Get the current configuration from the underlying connection.
abstract String	getInformation()
int	getLocalId() The local channel id
int	getLocalPacket() The maximum size of a single packet that the local side will accept.
long	getLocalWindow() The current size of the local data window.
String	getName() The name of this channel.
int	getQueueSize()
int	getRemoteId() The remote sides channel id
int	getRemotePacket() The maximum size of a single packet that the remote side will accept.
long	getRemoteWindow() The current size of the remote data window.
String	getSessionIdentifier() Get the session id for the current connection.
protected boolean	hasQueuedData()
protected void	idle(org.apache.mina.core.session.IdleStatus status)
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).
boolean	isLocalEOF()
boolean	isOpen() Get the open state of the channel.
boolean	isRemoteEOF()
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(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	removeEventListener(ChannelEventListener listener)
void	sendChannelData(org.apache.mina.core.buffer.IoBuffer buf) Send channel data to the remote side of the channel.
void	sendChannelData(org.apache.mina.core.buffer.IoBuffer buf, Runnable r)
protected void	sendChannelRequest(String type, boolean wantreply, byte[] requestdata) Send a channel request.
protected void	sendEOF() You can send EOF when you have no more data to send.
protected void	sendExtendedData(org.apache.mina.core.buffer.IoBuffer buf, int type) Send extended channel data.
protected void	sendRequestResponse(boolean succeeded) Send a channel request.
protected void	sendWindowAdjust(long 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 long localwindow

localWindowLock

protected Object localWindowLock

state

protected int state

Constructor Detail

Channel

public Channel(String channelType,
               int maximumPacketSize,
               long 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

isLocalEOF

public boolean isLocalEOF()

isRemoteEOF

public boolean isRemoteEOF()

getInformation

public abstract String getInformation()

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

addEventListener

public void addEventListener(ChannelEventListener listener)

Enable other objects to receive channel events

Parameters:

listener -

removeEventListener

public void removeEventListener(ChannelEventListener listener)

addInputListener

public void addInputListener(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(OutputStream out)

Add an OutputStream to receive all of the channels output.

Parameters:

out - OutputStream

getName

public String getName()

The name of this channel.

Specified by:

getName in interface com.maverick.ssh.components.SshComponent

Returns:

String

getRemoteWindow

public long getRemoteWindow()

The current size of the remote data window.

Returns:

int

getLocalWindow

public long 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 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:

IOException

getSessionIdentifier

public String 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(org.apache.mina.core.buffer.IoBuffer buf)

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(org.apache.mina.core.buffer.IoBuffer buf,
                            Runnable r)

getContext

public SshContext getContext()

Get the current configuration from the underlying connection.

Returns:

ConfigurationContext

sendExtendedData

protected void sendExtendedData(org.apache.mina.core.buffer.IoBuffer buf,
                                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(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 IOException,
                                        com.maverick.ssh.ChannelOpenException

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:

IOException

com.maverick.ssh.ChannelOpenException

openChannel

protected abstract byte[] openChannel(byte[] requestdata)
                               throws WriteOperationRequest,
                                      com.maverick.ssh.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

com.maverick.ssh.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(String type,
                                         boolean wantreply,
                                         byte[] requestdata)

Called when a channel request is received.

Parameters:

type -

wantreply -

requestdata -

evaluateWindowSpace

protected abstract void evaluateWindowSpace(long 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.

sendEOF

protected void sendEOF()

You can send EOF when you have no more data to send. The channel will still remain open until a close message is received. NOTE: this is never used

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

public 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(long count)

Adjust the local window by adding more bytes.

Parameters:

count -

idle

protected void idle(org.apache.mina.core.session.IdleStatus status)