Package org.apache.sshd.server.channel

Class PipeDataReceiver

java.lang.Object

org.apache.sshd.common.util.logging.AbstractLoggingBean

org.apache.sshd.server.channel.PipeDataReceiver

All Implemented Interfaces:

Closeable, AutoCloseable, ChannelDataReceiver

public class PipeDataReceiver
extends AbstractLoggingBean
implements ChannelDataReceiver

ChannelDataReceiver that buffers the received data into byte buffer and provides an InputStream to consume them.

Author:

Kohsuke Kawaguchi

Field Summary

Fields inherited from class org.apache.sshd.common.util.logging.AbstractLoggingBean

log

Constructor Summary

Constructors

Constructor	Description
PipeDataReceiver(PropertyResolver resolver, LocalWindow localWindow)

Method Summary

Modifier and Type	Method	Description
void	close()
int	data(ChannelSession channel, byte[] buf, int start, int len)	Called when the server receives additional bytes from the client.
InputStream	getIn()

Methods inherited from class org.apache.sshd.common.util.logging.AbstractLoggingBean

debug, debug, debug, debug, debug, error, error, error, error, error, getSimplifiedLogger, info, info, warn, warn, warn, warn, warn, warn, warn, warn

Methods inherited from class java.lang.Object

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

Constructor Details

PipeDataReceiver

public PipeDataReceiver(PropertyResolver resolver,
 LocalWindow localWindow)

Method Details

getIn

public InputStream getIn()

close

public void close()
           throws IOException

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Throws:

IOException

data

public int data(ChannelSession channel,
 byte[] buf,
 int start,
 int len)
         throws IOException

Description copied from interface: ChannelDataReceiver

Called when the server receives additional bytes from the client. When Closeable.close()-d then indicates EOF - The client will no longer send us any more data.

SSH channels use the windowing mechanism to perform flow control, much like TCP does. The server gives the client the initial window size, which represents the number of bytes the client can send to the server. As the server receives data, it can send a message to the client to allow it to send more data.

The return value from this method is used to control this behaviour. Intuitively speaking, the callee returns the number of bytes consumed by this method, by the time this method returns. Picture a one-way long bridge (for example Golden Gate Bridge) with toll plazas on both sides. The window size is the maximum number of cars allowed on the bridge. Here we are on the receiving end, so our job here is to count the number of cars as it leaves the bridge, and if enough of them left, we'll signal the sending end that they can let in more cars. The return value of this method counts the number of cars that are leaving in this batch.

In simple cases, where the callee has consumed the bytes before it returns, the return value must be the same value as the 'len' parameter given.

On the other hand, if the callee is queueing up the received bytes somewhere to be consumed later (for example by another thread), then this method should return 0, for the bytes aren't really consumed yet. And when at some later point the bytes are actually used, then you'll invoke channel.getLocalWindow().consumeAndCheck(len) to let the channel know that bytes are consumed.

This behaviour will result in a better flow control, as the server will not allow the SSH client to overflow its buffer. If instead you always return the value passed in the 'len' parameter, the place where you are queueing up bytes may overflow.

In either case, the callee must account for every bytes it receives in this method. Returning 0 and failing to call back channel.getLocalWindow().consumeAndCheck(len) later will dry up the window size, and eventually the client will stop sending you any data.

In the SSH protocol, this method invocation is triggered by a SSH_MSG_CHANNEL_DATA message.

Specified by:

data in interface ChannelDataReceiver

Parameters:

channel - The caller to which this ChannelDataReceiver is assigned. Never null.

buf - Holds the bytes received. This buffer belongs to the caller, and it might get reused by the caller as soon as this method returns.

start - buf[start] is the first byte that received from the client.

len - the length of the bytes received. Can be zero.

Returns:

The number of bytes consumed, for the purpose of the flow control. For a simple use case, you return the value given by the 'len' parameter. See the method javadoc for more details.

Throws:

IOException - if failed to consume the data