Package org.apache.sshd.common.session

Interface Session

All Superinterfaces:
AttributeRepository, AttributeStore, AutoCloseable, Channel, ChannelListenerManager, ChannelStreamWriterResolver, ChannelStreamWriterResolverManager, Closeable, Closeable, ConnectionEndpointsIndicator, FactoryManagerHolder, KexExtensionHandlerManager, KexFactoryManager, MutableUserHolder, PortForwardingEventListenerManager, PortForwardingInformationProvider, PropertyResolver, ReservedSessionMessagesManager, SessionContext, SessionDisconnectHandlerManager, SessionHeartbeatController, SessionListenerManager, SignatureFactoriesHolder, SignatureFactoriesManager, UnknownChannelReferenceHandlerManager, UsernameHolder
All Known Subinterfaces:
ClientSession, ServerSession
All Known Implementing Classes:
AbstractClientSession, AbstractServerSession, AbstractSession, ClientSessionImpl, ServerSessionImpl, SessionHelper
public interface Session extends SessionContext, MutableUserHolder, KexFactoryManager, SessionListenerManager, ReservedSessionMessagesManager, SessionDisconnectHandlerManager, ChannelListenerManager, ChannelStreamWriterResolverManager, PortForwardingEventListenerManager, UnknownChannelReferenceHandlerManager, FactoryManagerHolder, PortForwardingInformationProvider
Represents an SSH session. Note: the associated username for the session may be null/empty if the session is not yet authenticated
Author:
Apache MINA SSHD Project

  • Method Details

    • createBuffer

      default Buffer createBuffer(byte cmd)
      Create a new buffer for the specified SSH packet and reserve the needed space (5 bytes) for the packet header.
      Parameters:
      cmd - the SSH command
      Returns:
      a new buffer (of unknown size) ready for write
      See Also:

    • createBuffer

      Buffer createBuffer(byte cmd, int estimatedSize)
      Create a new buffer for the specified SSH packet and reserve the needed space (5 bytes) for the packet header.
      Parameters:
      cmd - The SSH command to initialize the buffer with
      estimatedSize - Estimated number of bytes the buffer will hold, 0 if unknown.
      Returns:
      a new buffer ready for write
      See Also:

    • prepareBuffer

      Buffer prepareBuffer(byte cmd, Buffer buffer)
      Prepare a new "clean" buffer while reserving the needed space (5 bytes) for the packet header.
      Parameters:
      cmd - The SSH command to initialize the buffer with
      buffer - The Buffer instance to initialize
      Returns:
      The initialized buffer

    • sendDebugMessage

      IoWriteFuture sendDebugMessage(boolean display, Object msg, String lang) throws IOException
      Sends an SSH_MSG_DEBUG to the peer session
      Parameters:
      display - true if OK to display the message at the peer as-is
      msg - The message object whose toString() value to be used - if null then the "null" string is sent
      lang - The language - null/empty if some pre-agreed default is used
      Returns:
      An IoWriteFuture that can be used to check when the packet has actually been sent
      Throws:
      IOException - if an error occurred when encoding or sending the packet
      See Also:

    • sendIgnoreMessage

      IoWriteFuture sendIgnoreMessage(byte... data) throws IOException
      Sends an SSH_MSG_IGNORE to the peer session
      Parameters:
      data - The message data
      Returns:
      An IoWriteFuture that can be used to check when the packet has actually been sent
      Throws:
      IOException - if an error occurred when encoding or sending the packet
      See Also:

    • writePacket

      IoWriteFuture writePacket(Buffer buffer) throws IOException
      Encode and send the given buffer. The buffer has to have 5 bytes free at the beginning to allow the encoding to take place. Also, the write position of the buffer has to be set to the position of the last byte to write.
      Parameters:
      buffer - the buffer to encode and send
      Returns:
      An IoWriteFuture that can be used to check when the packet has actually been sent
      Throws:
      IOException - if an error occurred when encoding sending the packet

    • writePacket

      default IoWriteFuture writePacket(Buffer buffer, Duration timeout) throws IOException
      Encode and send the given buffer with the specified timeout. If the buffer could not be written before the timeout elapses, the returned IoWriteFuture will be set with a TimeoutException exception to indicate a timeout.
      Parameters:
      buffer - the buffer to encode and spend
      timeout - the (never null) timeout value - its milliseconds value will be used
      Returns:
      a future that can be used to check when the packet has actually been sent
      Throws:
      IOException - if an error occurred when encoding or sending the packet
      See Also:

    • writePacket

      default IoWriteFuture writePacket(Buffer buffer, long maxWaitMillis) throws IOException
      Encode and send the given buffer with the specified timeout. If the buffer could not be written before the timeout elapses, the returned IoWriteFuture will be set with a TimeoutException exception to indicate a timeout.
      Parameters:
      buffer - the buffer to encode and spend
      maxWaitMillis - the timeout in milliseconds
      Returns:
      a future that can be used to check when the packet has actually been sent
      Throws:
      IOException - if an error occurred when encoding or sending the packet

    • writePacket

      IoWriteFuture writePacket(Buffer buffer, long timeout, TimeUnit unit) throws IOException
      Encode and send the given buffer with the specified timeout. If the buffer could not be written before the timeout elapses, the returned IoWriteFuture will be set with a TimeoutException exception to indicate a timeout.
      Parameters:
      buffer - the buffer to encode and spend
      timeout - the timeout
      unit - the time unit of the timeout parameter
      Returns:
      a future that can be used to check when the packet has actually been sent
      Throws:
      IOException - if an error occurred when encoding or sending the packet

    • request

      default Buffer request(String request, Buffer buffer, long timeout, TimeUnit unit) throws IOException
      Send a global request and wait for the response, if the request is sent with want-reply = true.
      Parameters:
      request - the request name - used mainly for logging and debugging
      buffer - the buffer containing the global request
      timeout - The number of time units to wait - must be positive
      unit - The TimeUnit to wait for the response
      Returns:
      the return buffer if the request was successful, null otherwise.
      Throws:
      IOException - if an error occurred when encoding or sending the packet
      SocketTimeoutException - If no response received within specified timeout

    • request

      default Buffer request(String request, Buffer buffer, Duration timeout) throws IOException
      Send a global request and wait for the response, if the request is sent with want-reply = true.
      Parameters:
      request - the request name - used mainly for logging and debugging
      buffer - the buffer containing the global request
      timeout - The (never null) timeout to wait - its milliseconds value is used
      Returns:
      the return buffer if the request was successful, null otherwise.
      Throws:
      IOException - if an error occurred when encoding or sending the packet
      SocketTimeoutException - If no response received within specified timeout

    • request

      Buffer request(String request, Buffer buffer, long maxWaitMillis) throws IOException
      Send a global request and wait for the response, if the request is sent with want-reply = true.
      Parameters:
      request - the request name - used mainly for logging and debugging
      buffer - the buffer containing the global request
      maxWaitMillis - maximum time in milliseconds to wait for the request to finish - must be positive
      Returns:
      the return buffer if the request was successful, null otherwise.
      Throws:
      IOException - if an error occurred when encoding or sending the packet
      SocketTimeoutException - If no response received within specified timeout

    • request

      GlobalRequestFuture request(Buffer buffer, String request, GlobalRequestFuture.ReplyHandler replyHandler) throws IOException
      Send a global request and handle the reply asynchronously. If want-reply = true, pass the received Buffer to the given GlobalRequestFuture.ReplyHandler, which may execute in a different thread.
      want-reply == true && replyHandler != null
      The returned future is fulfilled with null when the request was sent, or with an exception if the request could not be sent. The replyHandler is invoked once the reply is received, with the SSH reply code and the data received.
      want-reply == true && replyHandler == null
      The returned future is fulfilled with an exception if the request could not be sent, or a failure reply was received. If a success reply was received, the future is fulfilled with the received data buffer.
      want-reply == false
      The returned future is fulfilled with an empty Buffer when the request was sent, or with an exception if the request could not be sent. If a reply handler is given, it is invoked with that empty buffer. The handler is not invoked if sending the request failed.
      Parameters:
      buffer - the Buffer containing the global request, with the want-reply flag set as appropriate
      request - the request name
      replyHandler - GlobalRequestFuture.ReplyHandler for handling the reply; may be null
      Returns:
      Created GlobalRequestFuture
      Throws:
      IOException - if an error occurred while encoding or sending the packet

    • exceptionCaught

      void exceptionCaught(Throwable t)
      Handle any exceptions that occurred on this session. The session will be closed and a disconnect packet will be sent before if the given exception is an SshException with a positive error code
      Parameters:
      t - the exception to process

    • reExchangeKeys

      KeyExchangeFuture reExchangeKeys() throws IOException
      Initiate a new key exchange.
      Returns:
      A KeyExchangeFuture for awaiting the completion of the exchange
      Throws:
      IOException - If failed to request keys re-negotiation

    • getService

      <T extends Service> T getService(Class<T> clazz)
      Get the service of the specified type. If the service is not of the specified class, an IllegalStateException will be thrown.
      Type Parameters:
      T - The generic Service type
      Parameters:
      clazz - The service class
      Returns:
      The service instance
      Throws:
      IllegalStateException - If failed to find a matching service

    • getIoSession

      IoSession getIoSession()
      Returns:
      The IoSession associated to this session

    • getLocalAddress

      default SocketAddress getLocalAddress()
      Specified by:
      getLocalAddress in interface ConnectionEndpointsIndicator

    • getRemoteAddress

      default SocketAddress getRemoteAddress()
      Specified by:
      getRemoteAddress in interface ConnectionEndpointsIndicator

    • getTimeoutStatus

      TimeoutIndicator getTimeoutStatus()
      Check if timeout has occurred.
      Returns:
      the timeout status - never null

    • getIdleTimeout

      Duration getIdleTimeout()
      Returns:
      Timeout value in milliseconds for communication

    • getIdleTimeoutStart

      Instant getIdleTimeoutStart()
      Returns:
      The timestamp value (milliseconds since EPOCH) when timer was started

    • resetIdleTimeout

      Instant resetIdleTimeout()
      Re-start idle timeout timer
      Returns:
      The timestamp value (milliseconds since EPOCH) when timer was started
      See Also:

    • getAuthTimeout

      Duration getAuthTimeout()
      Returns:
      Timeout value in milliseconds for authentication stage

    • getAuthTimeoutStart

      Instant getAuthTimeoutStart()
      Returns:
      The timestamp value (milliseconds since EPOCH) when timer was started

    • resetAuthTimeout

      Instant resetAuthTimeout()
      Re-start the authentication timeout timer
      Returns:
      The timestamp value (milliseconds since EPOCH) when timer was started
      See Also:

    • setAuthenticated

      void setAuthenticated() throws IOException
      Throws:
      IOException

    • getKex

      KeyExchange getKex()
      Returns:
      The current KeyExchange in progress - null if KEX not started or successfully completed

    • disconnect

      void disconnect(int reason, String msg) throws IOException
      Send a disconnect packet with the given reason and message. Once the packet has been sent, the session will be closed asynchronously.
      Parameters:
      reason - the reason code for this disconnect
      msg - the text message
      Throws:
      IOException - if an error occurred sending the packet

    • startService

      void startService(String name, Buffer buffer) throws Exception
      Parameters:
      name - Service name
      buffer - Extra information provided when the service start request was received
      Throws:
      Exception - If failed to start it

    • resolveAttribute

      default <T> T resolveAttribute(AttributeRepository.AttributeKey<T> key)
      Specified by:
      resolveAttribute in interface AttributeRepository

    • resolveAttribute

      static <T> T resolveAttribute(Session session, AttributeRepository.AttributeKey<T> key)
      Attempts to use the session's attribute, if not found then tries the factory manager
      Type Parameters:
      T - The generic attribute type
      Parameters:
      session - The Session - ignored if null
      key - The attribute key - never null
      Returns:
      Associated value - null if not found
      See Also: