Interface ClientChannel

All Superinterfaces:
AttributeRepository, AttributeStore, AutoCloseable, Channel, Channel, ChannelIdentifier, ChannelListenerManager, ChannelStreamWriterResolver, ChannelStreamWriterResolverManager, ClientSessionHolder, Closeable, Closeable, PropertyResolver, SessionContextHolder, SessionHolder<Session>, StreamingChannel
All Known Implementing Classes:
AbstractClientChannel, AgentForwardedChannel, AgentForwardedChannel, ChannelDirectTcpip, ChannelExec, ChannelForwardedX11, ChannelSession, ChannelShell, ChannelSubsystem, DefaultSftpClient.SftpChannelSubsystem, PtyCapableChannelSession, TcpipClientChannel

public interface ClientChannel extends Channel, StreamingChannel, ClientSessionHolder
A client channel used to communicate with the SSH server. Client channels can be shells, simple commands or subsystems. Note: client channels may be associated with a server session if they are opened by the server - e.g., for agent proxy, port forwarding, etc..
  • Method Details

    • getClientSession

      default ClientSession getClientSession()
      Specified by:
      getClientSession in interface ClientSessionHolder
      Returns:
      The underlying ClientSession used
    • getChannelType

      String getChannelType()
      Returns:
      The type of channel reported when it was created
    • getAsyncIn

      IoOutputStream getAsyncIn()
    • getAsyncOut

      IoInputStream getAsyncOut()
    • getAsyncErr

      IoInputStream getAsyncErr()
    • getInvertedIn

      OutputStream getInvertedIn()
      Obtains an OutputStream to send data directly to the remote end of the channel. This can be used instead of using setIn(InputStream) method and having the channel polling for data in that stream.

      When the channel closes, it will close the returned stream.

      This method should be called only after the channel has been opened.

      Returns:
      an OutputStream for sending data, or null if an input stream was set via setIn(InputStream)
      See Also:
    • getInvertedOut

      InputStream getInvertedOut()
      Obtains an InputStream to read received SshConstants.SSH_MSG_CHANNEL_DATA data directly from the channel. This is an alternative to setOut(OutputStream). If the error stream is redirected to the output stream via setRedirectErrorStream(true), this stream will also receive SshConstants.SSH_MSG_CHANNEL_EXTENDED_DATA data.

      When the channel closes, it will not close the returned stream. It is the caller's responsibility to close the returned stream if needed. Closing the stream while the channel is open may cause the channel to be closed forcibly if more data arrives. The stream remains open after the channel has closed, so that the caller can read the last arrived data even afterwards.

      As with all external processes, the application should read this stream to avoid that the channel blocks when the stream's buffer is full. The buffer size for the returned stream is bounded by the channel's local window size. If the caller does not read this stream, the channel will block once the local window is exhausted.

      This method should be called only after the channel has been opened.

      Returns:
      an InputStream for reading received data, or null if an output stream was set via setOut(OutputStream)
      See Also:
    • getInvertedErr

      InputStream getInvertedErr()
      Obtains an InputStream to read received SshConstants.SSH_MSG_CHANNEL_EXTENDED_DATA data directly from the channel. This is an alternative to setErr(OutputStream). If the error stream is redirected to the output stream via setRedirectErrorStream(true), the returned stream will not receive any data and be always at EOF.

      When the channel closes, it will not close the returned stream. It is the caller's responsibility to close the returned stream if needed. Closing the stream while the channel is open may cause the channel to be closed forcibly if more data arrives. The stream remains open after the channel has closed, so that the caller can read the last arrived data even afterwards.

      As with all external processes, the application should read this stream (unless it was redirected) to avoid that the channel blocks when the stream's buffer is full. The buffer size for the returned stream is bounded by the channel's local window size. If the caller does not read this stream, the channel will block once the local window is exhausted.

      This method should be called only after the channel has been opened.

      Returns:
      an InputStream for reading received data, or null if an output stream was set via setErr(OutputStream)
      See Also:
    • setIn

      void setIn(InputStream in)
      Sets an InputStream that will be read by this channel and forwarded to the remote channel. Note that using such a stream will create an additional thread for pumping the stream which will only be able to end when that stream is actually closed or EOF on the stream is reached. It is recommended to use the getInvertedIn() method instead and write data directly.

      The stream must be set before the channel is opened. When the channel closes, it will close the given stream. If the stream should not be closed (for instance, if it is System.in), wrap it in an NoCloseInputStream.

      Parameters:
      in - an InputStream to be polled and forwarded
      See Also:
    • setOut

      void setOut(OutputStream out)
      Sets an output stream for the channel to write received SshConstants.SSH_MSG_CHANNEL_DATA data to. For remote command execution, this is typically the remote command's stdout. If the error stream is redirected to the output stream via setRedirectErrorStream(true), this stream will also receive SshConstants.SSH_MSG_CHANNEL_EXTENDED_DATA data.

      The stream must be set before the channel is opened. When the channel closes, it will close the given stream.

      If no stream is set by the time the channel is opened, the channel will internally forward data to a stream that can be read via the InputStream obtained via getInvertedOut().

      Parameters:
      out - the OutputStream
      See Also:
    • setErr

      void setErr(OutputStream err)
      Sets an output stream for the channel to write received SshConstants.SSH_MSG_CHANNEL_EXTENDED_DATA data to. For remote command execution, this is typically the remote command's stderr.

      The stream must be set before the channel is opened. When the channel closes, it will close the given stream.

      If no stream is set by the time the channel is opened, the channel will internally forward data to a stream that can be read via the InputStream obtained via getInvertedErr(). (Or it might forward the data to the output stream if setRedirectErrorStream(true) is set.)

      Parameters:
      err - the OutputStream
      See Also:
    • setRedirectErrorStream

      void setRedirectErrorStream(boolean redirectErrorStream)
      Defines whether to redirect the error stream into the output stream; has no effect if setErr(OutputStream) has also been called by the time the channel is opened.
      Parameters:
      redirectErrorStream - whether to redirect the error stream to the output stream.
    • open

      OpenFuture open() throws IOException
      Throws:
      IOException
    • getChannelState

      Set<ClientChannelEvent> getChannelState()
      Returns:
      A snapshot of the current channel state
      See Also:
    • waitFor

      Set<ClientChannelEvent> waitFor(Collection<ClientChannelEvent> mask, long timeout)
      Waits until any of the specified events in the mask is signaled
      Parameters:
      mask - The ClientChannelEvents mask
      timeout - The timeout to wait (msec.) - if non-positive then forever
      Returns:
      The actual signaled event - includes ClientChannelEvent.TIMEOUT if timeout expired before the expected event was signaled
    • waitFor

      default Set<ClientChannelEvent> waitFor(Collection<ClientChannelEvent> mask, Duration timeout)
      Waits until any of the specified events in the mask is signaled
      Parameters:
      mask - The ClientChannelEvents mask
      timeout - The timeout to wait - if null then forever
      Returns:
      The actual signaled event - includes ClientChannelEvent.TIMEOUT if timeout expired before the expected event was signaled
    • getExitStatus

      Integer getExitStatus()
      Returns:
      The signaled exit status via "exit-status" request - null if not signaled
    • getExitSignal

      String getExitSignal()
      Returns:
      The signaled exit signal via "exit-signal" - null if not signaled
    • validateCommandExitStatusCode

      static void validateCommandExitStatusCode(String command, Integer exitStatus) throws RemoteException
      Makes sure remote command exit status has been provided and it is zero
      Parameters:
      command - The command string - used only for exception text
      exitStatus - The exit status value
      Throws:
      RemoteException - If exitStatus is null or non-zero