org.apache.thrift.transport

## Class TSaslClientTransport

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

-     public class TSaslClientTransport
      extends TTransport

  Wraps another Thrift `TTransport`, but performs SASL client 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
    --- | ---
    `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
    `TSaslClientTransport(javax.security.sasl.SaslClient saslClient, TTransport transport)` Uses the given `SaslClient`.
    `TSaslClientTransport(java.lang.String mechanism, java.lang.String authorizationId, 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 `SaslClient` using the given SASL-specific parameters.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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 client 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

    - #### TSaslClientTransport

          public TSaslClientTransport(javax.security.sasl.SaslClient saslClient,
                              TTransport transport)

      Uses the given `SaslClient`.
      Parameters:
        `saslClient` - The `SaslClient` to use for the subsequent SASL negotiation.
        `transport` - Transport underlying this one.

    - #### TSaslClientTransport

          public TSaslClientTransport(java.lang.String mechanism,
                              java.lang.String authorizationId,
                              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)
                               throws javax.security.sasl.SaslException

      Creates a `SaslClient` using the given SASL-specific parameters. See the Java documentation for `Sasl.createSaslClient` for the details of the parameters.
      Parameters:
        `transport` - The underlying Thrift transport.
      Throws:
        `javax.security.sasl.SaslException`

  - ### Method Detail

    - #### getRole

          protected TSaslTransport.SaslRole getRole()

    - #### handleSaslStartMessage

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

      Performs the client side of the initial portion of the Thrift SASL protocol. Generates and sends the initial response to the server, including which mechanism this client wants to use.
      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.