org.apache.thrift.transport

## Class TSaslServerTransport

- java.lang.Object
- - org.apache.thrift.transport.TTransport
  - - org.apache.thrift.transport.TSaslServerTransport

-     public class TSaslServerTransport
      extends TTransport

  Wraps another Thrift `TTransport`, but performs SASL server negotiation on the call to `open()`. This class will wrap ensuing communication over it, if a SASL QOP is negotiated with the other party.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `TSaslServerTransport.Factory` `TTransportFactory` to create `TSaslServerTransports.`
    `protected static class` | `TSaslTransport.NegotiationStatus` Status bytes used during the initial Thrift SASL handshake.
    `protected static class` | `TSaslTransport.SaslResponse` Used exclusively by readSaslMessage to return both a status and data.
    `protected static class` | `TSaslTransport.SaslRole`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected static int` | `DEFAULT_MAX_LENGTH`
    `protected static int` | `MECHANISM_NAME_BYTES`
    `protected static int` | `PAYLOAD_LENGTH_BYTES`
    `protected static int` | `STATUS_BYTES`
    `protected TTransport` | `underlyingTransport` Transport underlying this one.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `TSaslServerTransport(java.lang.String mechanism, java.lang.String protocol, java.lang.String serverName, java.util.Map<java.lang.String,java.lang.String> props, javax.security.auth.callback.CallbackHandler cbh, TTransport transport)` Creates a `SaslServer` using the given SASL-specific parameters.
    `TSaslServerTransport(TTransport transport)` Uses the given underlying transport.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addServerDefinition(java.lang.String mechanism, java.lang.String protocol, java.lang.String serverName, java.util.Map<java.lang.String,java.lang.String> props, javax.security.auth.callback.CallbackHandler cbh)` Add a supported server definition to this transport.
    `void` | `close()` Closes the underlying transport and disposes of the SASL implementation underlying this transport.
    `void` | `flush()` Flushes to the underlying transport.
    `protected TSaslTransport.SaslRole` | `getRole()`
    `javax.security.sasl.SaslClient` | `getSaslClient()` Get the underlying `SaslClient`.
    `javax.security.sasl.SaslServer` | `getSaslServer()` Get the underlying `SaslServer`.
    `TTransport` | `getUnderlyingTransport()` Get the underlying transport that Sasl is using.
    `protected void` | `handleSaslStartMessage()` Performs the server side of the initial portion of the Thrift SASL protocol.
    `boolean` | `isOpen()` True if the underlying transport is open and the SASL handshake is complete.
    `void` | `open()` Opens the underlying transport if it's not already open and then performs SASL negotiation.
    `int` | `read(byte[] buf, int off, int len)` Read from the underlying transport.
    `protected int` | `readLength()` Read a 4-byte word from the underlying transport and interpret it as an integer.
    `protected TSaslTransport.SaslResponse` | `receiveSaslMessage()` Read a complete Thrift SASL message.
    `protected void` | `sendAndThrowMessage(TSaslTransport.NegotiationStatus status, java.lang.String message)` Send a Thrift SASL message with the given status (usually BAD or ERROR) and string message, and then throw a TTransportException with the given message.
    `protected void` | `sendSaslMessage(TSaslTransport.NegotiationStatus status, byte[] payload)` Send a complete Thrift SASL message.
    `protected void` | `setSaslServer(javax.security.sasl.SaslServer saslServer)`
    `void` | `write(byte[] buf, int off, int len)` Write to the underlying transport.
    `protected void` | `writeLength(int length)` Write the given integer as 4 bytes to the underlying transport.

    - ### Methods inherited from class org.apache.thrift.transport.TTransport

      `consumeBuffer, getBuffer, getBufferPosition, getBytesRemainingInBuffer, peek, readAll, write`

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### DEFAULT_MAX_LENGTH

          protected static final int DEFAULT_MAX_LENGTH

      See Also:
        Constant Field Values

    - #### MECHANISM_NAME_BYTES

          protected static final int MECHANISM_NAME_BYTES

      See Also:
        Constant Field Values

    - #### STATUS_BYTES

          protected static final int STATUS_BYTES

      See Also:
        Constant Field Values

    - #### PAYLOAD_LENGTH_BYTES

          protected static final int PAYLOAD_LENGTH_BYTES

      See Also:
        Constant Field Values

    - #### underlyingTransport

          protected TTransport underlyingTransport

      Transport underlying this one.

  - ### Constructor Detail

    - #### TSaslServerTransport

          public TSaslServerTransport(TTransport transport)

      Uses the given underlying transport. Assumes that addServerDefinition is called later.
      Parameters:
        `transport` - Transport underlying this one.

    - #### TSaslServerTransport

          public TSaslServerTransport(java.lang.String mechanism,
                              java.lang.String protocol,
                              java.lang.String serverName,
                              java.util.Map<java.lang.String,java.lang.String> props,
                              javax.security.auth.callback.CallbackHandler cbh,
                              TTransport transport)

      Creates a `SaslServer` using the given SASL-specific parameters. See the Java documentation for `Sasl.createSaslServer` for the details of the parameters.
      Parameters:
        `transport` - The underlying Thrift transport.

  - ### Method Detail

    - #### addServerDefinition

          public void addServerDefinition(java.lang.String mechanism,
                                 java.lang.String protocol,
                                 java.lang.String serverName,
                                 java.util.Map<java.lang.String,java.lang.String> props,
                                 javax.security.auth.callback.CallbackHandler cbh)

      Add a supported server definition to this transport. See the Java documentation for `Sasl.createSaslServer` for the details of the parameters.

    - #### getRole

          protected TSaslTransport.SaslRole getRole()

    - #### handleSaslStartMessage

          protected void handleSaslStartMessage()
                                         throws TTransportException,
                                                javax.security.sasl.SaslException

      Performs the server side of the initial portion of the Thrift SASL protocol. Receives the initial response from the client, creates a SASL server using the mechanism requested by the client (if this server supports it), and sends the first challenge back to the client.
      Throws:
        `TTransportException`
        `javax.security.sasl.SaslException`

    - #### setSaslServer

          protected void setSaslServer(javax.security.sasl.SaslServer saslServer)

    - #### sendSaslMessage

          protected void sendSaslMessage(TSaslTransport.NegotiationStatus status,
                             byte[] payload)
                                  throws TTransportException

      Send a complete Thrift SASL message.
      Parameters:
        `status` - The status to send.
        `payload` - The data to send as the payload of this message.
      Throws:
        `TTransportException`

    - #### receiveSaslMessage

          protected TSaslTransport.SaslResponse receiveSaslMessage()
                                                            throws TTransportException

      Read a complete Thrift SASL message.
      Returns:
        The SASL status and payload from this message.
      Throws:
        `TTransportException` - Thrown if there is a failure reading from the underlying transport, or if a status code of BAD or ERROR is encountered.

    - #### sendAndThrowMessage

          protected void sendAndThrowMessage(TSaslTransport.NegotiationStatus status,
                                 java.lang.String message)
                                      throws TTransportException

      Send a Thrift SASL message with the given status (usually BAD or ERROR) and string message, and then throw a TTransportException with the given message.
      Parameters:
        `status` - The Thrift SASL status code to send. Usually BAD or ERROR.
        `message` - The optional message to send to the other side.
      Throws:
        `TTransportException` - Always thrown with the message provided.

    - #### open

          public void open()
                    throws TTransportException

      Opens the underlying transport if it's not already open and then performs SASL negotiation. If a QOP is negotiated during this SASL handshake, it used for all communication on this transport after this call is complete.
      Specified by:
        `open` in class `TTransport`
      Throws:
        `TTransportException` - if the transport could not be opened

    - #### getSaslClient

          public javax.security.sasl.SaslClient getSaslClient()

      Get the underlying `SaslClient`.
      Returns:
        The `SaslClient`, or `null` if this transport is backed by a `SaslServer`.

    - #### getUnderlyingTransport

          public TTransport getUnderlyingTransport()

      Get the underlying transport that Sasl is using.
      Returns:
        The `TTransport` transport

    - #### getSaslServer

          public javax.security.sasl.SaslServer getSaslServer()

      Get the underlying `SaslServer`.
      Returns:
        The `SaslServer`, or `null` if this transport is backed by a `SaslClient`.

    - #### readLength

          protected int readLength()
                            throws TTransportException

      Read a 4-byte word from the underlying transport and interpret it as an integer.
      Returns:
        The length prefix of the next SASL message to read.
      Throws:
        `TTransportException` - Thrown if reading from the underlying transport fails.

    - #### writeLength

          protected void writeLength(int length)
                              throws TTransportException

      Write the given integer as 4 bytes to the underlying transport.
      Parameters:
        `length` - The length prefix of the next SASL message to write.
      Throws:
        `TTransportException` - Thrown if writing to the underlying transport fails.

    - #### close

          public void close()

      Closes the underlying transport and disposes of the SASL implementation underlying this transport.
      Specified by:
        `close` in class `TTransport`

    - #### isOpen

          public boolean isOpen()

      True if the underlying transport is open and the SASL handshake is complete.
      Specified by:
        `isOpen` in class `TTransport`
      Returns:
        True if the transport is open.

    - #### read

          public int read(byte[] buf,
                 int off,
                 int len)
                   throws TTransportException

      Read from the underlying transport. Unwraps the contents if a QOP was negotiated during the SASL handshake.
      Specified by:
        `read` in class `TTransport`
      Parameters:
        `buf` - Array to read into
        `off` - Index to start reading at
        `len` - Maximum number of bytes to read
      Returns:
        The number of bytes actually read
      Throws:
        `TTransportException` - if there was an error reading data

    - #### write

          public void write(byte[] buf,
                   int off,
                   int len)
                     throws TTransportException

      Write to the underlying transport.
      Specified by:
        `write` in class `TTransport`
      Parameters:
        `buf` - The output data buffer
        `off` - The offset to start writing from
        `len` - The number of bytes to write
      Throws:
        `TTransportException` - if there was an error writing data

    - #### flush

          public void flush()
                     throws TTransportException

      Flushes to the underlying transport. Wraps the contents if a QOP was negotiated during the SASL handshake.
      Overrides:
        `flush` in class `TTransport`
      Throws:
        `TTransportException` - if there was an error writing out data.