com.maverick.sshd

Class SessionChannel

java.lang.Object

com.maverick.sshd.Channel

com.maverick.sshd.SessionChannel

All Implemented Interfaces:

IdleStateListener

Direct Known Subclasses:

NativeSession, ProxySession, UnsupportedSession, VirtualShell

public abstract class SessionChannel
extends Channel
implements IdleStateListener

This class provides an abstract session, it handles all the requests defined in the SSH Connection protocol for a session channel and passes the request to the concrete implementation through its abstract methods.

When creating a session implementation your processStdinData(byte[]) will receive data from the client and process as session input. To send stdout data for your session you should use the sendStdoutData(byte[]) method and any sdterr output should be send using sendStderrData(byte[]) method.

As the server uses an asynchronous framework expensive blocking operations SHOULD NOT be performed within your session as this will cause a deadlock on the server.

The basic process of establishing a session is this

• 1. The session is opened


• 2. The client possibly sends requests for a pseudo terminal or setting of environment variables


• 3. The client requests to either start a shell or execute a command. Once this has been requested the interactive session starts and data can be sent or received.


• 4. Data is sent/received until the command has completed. Once completed the session should close the channel and optionally sent the exit status of the command using sendExitStatus(int).


• 5. At anytime throughout the open session the client may send a signal. See the SSH Connection Protocol specification for more information on this advanced topic.

Author:

Lee David Painter

Nested Class Summary

Nested classes/interfaces inherited from class com.maverick.sshd.Channel

Channel.DataBlock, Channel.QueuedData

Field Summary

Fields

Modifier and Type	Field and Description
static String	CHANNEL_TYPE
protected int	maximumWindowSpace
protected int	minimumWindowSpace
static int	SSH_EXTENDED_DATA_STDERR

Fields inherited from class com.maverick.sshd.Channel

connection, localwindow, localWindowLock

Constructor Summary

Constructors

Constructor and Description
SessionChannel()
SessionChannel(int maximumPacket, int maximumWindowSpace)
SessionChannel(int maximumPacket, int maximumWindowSpace, int minimumWindowSpace)

Method Summary

Modifier and Type	Method and Description
protected abstract boolean	allocatePseudoTerminal(String term, int cols, int rows, int width, int height, byte[] modes) If the client requests a pseudo terminal for the session this method will be invoked before the shell, exec or subsystem is started.
protected abstract void	changeWindowDimensions(int cols, int rows, int width, int height) When the window (terminal) size changes on the client side, it MAY send notification in which case this method will be invoked to notify the session that a change has occurred.
protected void	close(boolean forceClose) This method closes the channel and free's its resources.
protected byte[]	createChannel() Called when the channel is being created.
protected void	evaluateWindowSpace(int remaining) Called to evaluate the window space available.
protected abstract boolean	executeCommand(String cmd) Invoked when the user wants to execute a command
protected void	executeTask(ConnectionAwareTask task)
int	getMaximumWindowSpace()
int	getMinimumWindowSpace()
Subsystem	getSubsystem()
void	haltIncomingData()
boolean	idle() Process an idle event.
boolean	isAgentForwardingRequested()
boolean	isIncomingDataHalted()
protected void	onChannelClosing() Called when the channel is closing.
protected void	onChannelData(byte[] data) Called when data arrives on the channel.
protected void	onChannelFree() Free the session and its resources.
protected void	onChannelOpen() Called once the channel has been opened.
protected void	onChannelOpenConfirmation() Called when the channel is confirmed as open
protected void	onChannelRequest(String type, boolean wantreply, byte[] requestdata) Process session requests and invoke the relevant abstract methods of this class to handle the requests.
protected void	onExtendedData(byte[] data, int type) Called when extended data arrives on the channel - for a session channel this would not normally be called.
protected void	onRemoteEOF() The remote side has reported EOF so no more data will be received.
protected abstract void	onSessionOpen() Called once the session is open and data can be sent/received.
protected byte[]	openChannel(byte[] data) Called when the channel is being opened.
protected abstract void	processSignal(String signal) A signal can be delivered to the process by the client.
protected abstract void	processStdinData(byte[] data) Data has arrived on the session's stdin stream.
protected boolean	requestAgentForwarding(String requestType) Implement this method to support agent forwarding.
void	resumeIncomingData()
void	sendExitStatus(int exitcode) When a command or shell exits its possible to send the client the exit code of the process.
void	sendStderrData(byte[] data) Send stderr data to the remote client.
void	sendStderrData(byte[] data, int off, int len) Sends stderr data to the remote client.
void	sendStdoutData(byte[] data) Sends stdout data to the remote client
void	sendStdoutData(byte[] data, int off, int len) Sends stdout data to the remote client.
protected abstract boolean	setEnvironmentVariable(String name, String value) If the client requests that an environment variable be set this method will be invoked.
void	setMaximumWindowSpace(int maximumWindowSpace)
void	setMinimumWindowSpace(int minimumWindowSpace)
protected abstract boolean	startShell() Invoked when the user wants to start a shell.
protected boolean	startSubsystem(String name)

Methods inherited from class com.maverick.sshd.Channel

addEventListener, addInputListener, addOutputListener, canClose, clearIdleState, close, consumeWindowSpace, createCloseTask, getChannelType, getConnection, getContext, getLocalId, getLocalPacket, getLocalWindow, getQueueSize, getRemoteId, getRemotePacket, getRemoteWindow, getSessionIdentifier, isClosed, isClosing, isEOF, isOpen, isSelfManagedWindowSpace, markEOF, onChannelClosed, onChannelOpenFailure, onLocalEOF, onRemoteClose, onWindowAdjust, queueSize, registerExtendedData, resetIdleState, sendChannelData, sendChannelData, sendChannelData, sendChannelData, sendChannelDataAndBlock, sendChannelRequest, sendEOF, sendExtendedData, sendExtendedData, sendRequestResponse, sendWindowAdjust

Methods inherited from class java.lang.Object

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

Field Detail

maximumWindowSpace

protected int maximumWindowSpace

minimumWindowSpace

protected int minimumWindowSpace

SSH_EXTENDED_DATA_STDERR

public static final int SSH_EXTENDED_DATA_STDERR

See Also:

Constant Field Values

CHANNEL_TYPE

public static final String CHANNEL_TYPE

See Also:

Constant Field Values

Constructor Detail

SessionChannel

public SessionChannel()

SessionChannel

public SessionChannel(int maximumPacket,
                      int maximumWindowSpace)

SessionChannel

public SessionChannel(int maximumPacket,
                      int maximumWindowSpace,
                      int minimumWindowSpace)

Method Detail

getSubsystem

public Subsystem getSubsystem()

createChannel

protected final byte[] createChannel()
                              throws IOException

Description copied from class: Channel

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

Specified by:

createChannel in class Channel

Returns:

byte[]

Throws:

IOException

allocatePseudoTerminal

protected abstract boolean allocatePseudoTerminal(String term,
                                                  int cols,
                                                  int rows,
                                                  int width,
                                                  int height,
                                                  byte[] modes)

If the client requests a pseudo terminal for the session this method will be invoked before the shell, exec or subsystem is started.

Parameters:

term -

cols -

rows -

width -

height -

modes -

Returns:

boolean

changeWindowDimensions

protected abstract void changeWindowDimensions(int cols,
                                               int rows,
                                               int width,
                                               int height)

When the window (terminal) size changes on the client side, it MAY send notification in which case this method will be invoked to notify the session that a change has occurred.

Parameters:

cols -

rows -

width -

height -

processSignal

protected abstract void processSignal(String signal)

A signal can be delivered to the process by the client. If a signal is received this method will be invoked so that the session may evaluate and take the required action.

Parameters:

signal -

setEnvironmentVariable

protected abstract boolean setEnvironmentVariable(String name,
                                                  String value)

If the client requests that an environment variable be set this method will be invoked.

Parameters:

name -

value -

Returns:

true if the variable has been set, otherwise false

startShell

protected abstract boolean startShell()

Invoked when the user wants to start a shell.

Returns:

true if the shell has been started, otherwise false

executeCommand

protected abstract boolean executeCommand(String cmd)

Invoked when the user wants to execute a command

Parameters:

cmd -

Returns:

true if the cmd has been executed, otherwise false

processStdinData

protected abstract void processStdinData(byte[] data)

Data has arrived on the session's stdin stream.

Parameters:

data -

onSessionOpen

protected abstract void onSessionOpen()

Called once the session is open and data can be sent/received. This event happens once the user has either started the shell or executed a command.

onChannelOpen

protected void onChannelOpen()

Called once the channel has been opened.

Specified by:

onChannelOpen in class Channel

isAgentForwardingRequested

public boolean isAgentForwardingRequested()

idle

public boolean idle()

Description copied from interface: IdleStateListener

Process an idle event.

Specified by:

idle in interface IdleStateListener

Returns:

true if this listener should be cancelled.

onChannelRequest

protected void onChannelRequest(String type,
                                boolean wantreply,
                                byte[] requestdata)

Process session requests and invoke the relevant abstract methods of this class to handle the requests. If you overide this method make sure that you call the super method.

Specified by:

onChannelRequest in class Channel

Parameters:

type - String

wantreply - boolean

requestdata - byte[]

requestAgentForwarding

protected boolean requestAgentForwarding(String requestType)

Implement this method to support agent forwarding.

Returns:

startSubsystem

protected boolean startSubsystem(String name)
                          throws IOException

Throws:

IOException

onChannelOpenConfirmation

protected void onChannelOpenConfirmation()

Called when the channel is confirmed as open

Specified by:

onChannelOpenConfirmation in class Channel

onRemoteEOF

protected void onRemoteEOF()

The remote side has reported EOF so no more data will be received. This will force the channel to close. If this behaviour is not required you can override this method

Specified by:

onRemoteEOF in class Channel

executeTask

protected void executeTask(ConnectionAwareTask task)

Overrides:

executeTask in class Channel

close

protected void close(boolean forceClose)

Description copied from class: Channel

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

Overrides:

close in class Channel

onChannelFree

protected void onChannelFree()

Free the session and its resources. If you override this method make sure that you call the super method to ensure that the resources of the abstract class are freed.

Specified by:

onChannelFree in class Channel

onChannelClosing

protected void onChannelClosing()

Called when the channel is closing. If you override this method make sure that you call the super method.

Specified by:

onChannelClosing in class Channel

onChannelData

protected void onChannelData(byte[] data)

Called when data arrives on the channel.

Specified by:

onChannelData in class Channel

Parameters:

data - byte[]

onExtendedData

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

Called when extended data arrives on the channel - for a session channel this would not normally be called.

Specified by:

onExtendedData in class Channel

Parameters:

data - byte[]

type - int

sendStdoutData

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

Sends stdout data to the remote client.

Parameters:

data -

off -

len -

sendStdoutData

public void sendStdoutData(byte[] data)

Sends stdout data to the remote client

Parameters:

data -

sendStderrData

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

Sends stderr data to the remote client.

Parameters:

data -

off -

len -

sendStderrData

public void sendStderrData(byte[] data)

Send stderr data to the remote client.

Parameters:

data -

sendExitStatus

public void sendExitStatus(int exitcode)

When a command or shell exits its possible to send the client the exit code of the process. Use this method before the channel is closed.

Parameters:

exitcode -

evaluateWindowSpace

protected final void evaluateWindowSpace(int remaining)

Description copied from class: Channel

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

Specified by:

evaluateWindowSpace in class Channel

isIncomingDataHalted

public boolean isIncomingDataHalted()

haltIncomingData

public void haltIncomingData()

resumeIncomingData

public void resumeIncomingData()

openChannel

protected final byte[] openChannel(byte[] data)
                            throws WriteOperationRequest,
                                   ChannelOpenException

Description copied from class: Channel

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

Specified by:

openChannel in class Channel

Returns:

byte[]

Throws:

WriteOperationRequest

ChannelOpenException

getMaximumWindowSpace

public int getMaximumWindowSpace()

setMaximumWindowSpace

public void setMaximumWindowSpace(int maximumWindowSpace)

getMinimumWindowSpace

public int getMinimumWindowSpace()

setMinimumWindowSpace

public void setMinimumWindowSpace(int minimumWindowSpace)