ResponseStream (jTDS API)
Date: 2013-06-08

net.sourceforge.jtds.jdbc

## Class ResponseStream

- java.lang.Object
- - net.sourceforge.jtds.jdbc.ResponseStream

-     public class ResponseStream
      extends java.lang.Object

  Implements an input stream for the server response.

  Implementation note:
  1. This class contains methods to read different types of data from the server response stream in TDS format.
  2. Character translation of String items is carried out.
  Version:
    $Id: ResponseStream.java,v 1.20 2005-10-27 13:22:33 alin_sinpalean Exp $
  Author:
    Mike Hutchinson.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `private static class` | `ResponseStream.TdsInputStream` Simple inner class implementing an `InputStream` over the server response.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private SharedSocket.VirtualSocket` | `_VirtualSocket` The `SharedSocket.VirtualSocket` used by this stream.
    `private byte[]` | `buffer` The Input packet buffer.
    `private int` | `bufferLen` The length of current input packet.
    `private int` | `bufferPtr` The offset of the next byte to read.
    `private byte[]` | `byteBuffer` A shared byte buffer.
    `private char[]` | `charBuffer` A shared char buffer.
    `private boolean` | `isClosed` True if stream is closed.
    `private SharedSocket` | `socket` The shared network socket.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ResponseStream(SharedSocket socket, SharedSocket.VirtualSocket vsock, int bufferSize)` Constructs a `RequestStream` object.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `(package private) void` | `close()` Closes this response stream.
    `(package private) java.io.InputStream` | `getInputStream(int len)` Creates a simple `InputStream` over the server response.
    `private void` | `getPacket()` Read the next TDS packet from the network.
    `(package private) int` | `getServerType()` Retrieves the server type.
    `(package private) int` | `getTdsVersion()` Retrieves the TDS version number.
    `(package private) SharedSocket.VirtualSocket` | `getVirtualSocket()` Retrieves the `SharedSocket.VirtualSocket` used by this stream id.
    `(package private) int` | `peek()` Retrieves the next input byte without reading forward.
    `(package private) int` | `read()` Reads the next input byte from the server response stream.
    `(package private) int` | `read(byte[] b)` Reads a byte array from the server response stream.
    `(package private) int` | `read(byte[] b, int off, int len)` Reads a byte array from the server response stream, specifying a start offset and length.
    `(package private) int` | `read(char[] c)` Reads a char array from the server response stream.
    `(package private) int` | `readInt()` Reads an `int` value from the server response stream.
    `(package private) long` | `readLong()` Reads a `long` value from the server response stream.
    `(package private) java.lang.String` | `readNonUnicodeString(int len)` Reads a non Unicode `String` from the server response stream, creating the `String` from a translated `byte` array.
    `(package private) java.lang.String` | `readNonUnicodeString(int len, CharsetInfo charsetInfo)` Reads a `String` from the server response stream, translating it from a `byte` array using the specified character set.
    `(package private) short` | `readShort()` Reads a `short` value from the server response stream.
    `(package private) java.lang.String` | `readString(int len)` Reads a `String` object from the server response stream.
    `(package private) java.lang.String` | `readString(int len, CharsetInfo info)` Reads a `String` from the server response stream, creating it from a translated `byte` array.
    `(package private) java.lang.String` | `readUnicodeString(int len)` Reads a UCS2-LE (Unicode) encoded String object from the server response stream.
    `(package private) java.math.BigDecimal` | `readUnsignedLong()` Reads an `unsigned long` value from the server response stream.
    `(package private) int` | `skip(int skip)` Discards bytes from the server response stream.
    `(package private) void` | `skipString(int len)` Skips a `String` from the server response stream.
    `(package private) void` | `skipToEnd()` Consumes the rest of the server response, without parsing it.

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

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

- - ### Field Detail

    - #### socket

          private final SharedSocket socket

      The shared network socket.

    - #### buffer

          private byte[] buffer

      The Input packet buffer.

    - #### bufferPtr

          private int bufferPtr

      The offset of the next byte to read.

    - #### bufferLen

          private int bufferLen

      The length of current input packet.

    - #### _VirtualSocket

          private final SharedSocket.VirtualSocket _VirtualSocket

      The `SharedSocket.VirtualSocket` used by this stream.

    - #### isClosed

          private boolean isClosed

      True if stream is closed.

    - #### byteBuffer

          private final byte[] byteBuffer

      A shared byte buffer.

    - #### charBuffer

          private final char[] charBuffer

      A shared char buffer.

  - ### Constructor Detail

    - #### ResponseStream

          ResponseStream(SharedSocket socket,
                        SharedSocket.VirtualSocket vsock,
                        int bufferSize)

      Constructs a `RequestStream` object.
      Parameters:
        `socket` - the shared socket object to write to
        `vsock` - the `SharedSocket.VirtualSocket` used by this stream (from ResponseStream)
        `bufferSize` - the initial buffer size

  - ### Method Detail

    - #### getVirtualSocket

          SharedSocket.VirtualSocket getVirtualSocket()

      Retrieves the `SharedSocket.VirtualSocket` used by this stream id.
      Returns:
        the unique stream id as an `int`

    - #### peek

          int peek()
             throws java.io.IOException

      Retrieves the next input byte without reading forward.
      Returns:
        the next byte in the input stream as an `int`
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### read

          int read()
             throws java.io.IOException

      Reads the next input byte from the server response stream.
      Returns:
        the next byte in the input stream as an `int`
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### read

          int read(byte[] b)
             throws java.io.IOException

      Reads a byte array from the server response stream.
      Parameters:
        `b` - the byte array to read into
      Returns:
        the number of bytes read as an `int`
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### read

          int read(byte[] b,
                 int off,
                 int len)
             throws java.io.IOException

      Reads a byte array from the server response stream, specifying a start offset and length.
      Parameters:
        `b` - the byte array
        `off` - the starting offset in the array
        `len` - the number of bytes to read
      Returns:
        the number of bytes read as an `int`
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### read

          int read(char[] c)
             throws java.io.IOException

      Reads a char array from the server response stream.
      Parameters:
        `c` - the char array
      Returns:
        the byte array as a `byte[]`
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### readString

          java.lang.String readString(int len)
                                throws java.io.IOException

      Reads a `String` object from the server response stream. If the TDS protocol version is 4.2 or 5.0 decode the string use the default server charset, otherwise use UCS2-LE (Unicode).
      Parameters:
        `len` - the length of the string to read in bytes in the case of TDS 4.2/5.0 and in characters for TDS 7.0+ (UCS2-LE encoded strings)
      Returns:
        the result as a `String`
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### skipString

          void skipString(int len)
                    throws java.io.IOException

      Skips a `String` from the server response stream. If the TDS protocol version is 4.2 or 5.0 `len` is the length in bytes, otherwise it's the length in UCS2-LE characters (length in bytes == 2 * `len`).
      Parameters:
        `len` - the length of the string to skip in bytes in the case of TDS 4.2/5.0 and in characters for TDS 7.0+ (UCS2-LE encoded strings)
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### readUnicodeString

          java.lang.String readUnicodeString(int len)
                                       throws java.io.IOException

      Reads a UCS2-LE (Unicode) encoded String object from the server response stream.
      Parameters:
        `len` - the length of the string to read in characters
      Returns:
        the result as a `String`
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### readNonUnicodeString

          java.lang.String readNonUnicodeString(int len)
                                          throws java.io.IOException

      Reads a non Unicode `String` from the server response stream, creating the `String` from a translated `byte` array.
      Parameters:
        `len` - the length of the string to read in bytes
      Returns:
        the result as a `String`
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### readNonUnicodeString

          java.lang.String readNonUnicodeString(int len,
                                              CharsetInfo charsetInfo)
                                          throws java.io.IOException

      Reads a `String` from the server response stream, translating it from a `byte` array using the specified character set.
      Parameters:
        `len` - the length of the string to read in bytes
      Returns:
        the result as a `String`
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### readString

          java.lang.String readString(int len,
                                    CharsetInfo info)
                                throws java.io.IOException

      Reads a `String` from the server response stream, creating it from a translated `byte` array.
      Parameters:
        `len` - the length of the string to read in bytes
        `info` - descriptor of the charset to use
      Returns:
        the result as a `String`
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### readShort

          short readShort()
                    throws java.io.IOException

      Reads a `short` value from the server response stream.
      Returns:
        the result as a `short`
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### readInt

          int readInt()
                throws java.io.IOException

      Reads an `int` value from the server response stream.
      Returns:
        the result as a `int`
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### readLong

          long readLong()
                  throws java.io.IOException

      Reads a `long` value from the server response stream.
      Returns:
        the result as a `long`
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### readUnsignedLong

          java.math.BigDecimal readUnsignedLong()
                                          throws java.io.IOException

      Reads an `unsigned long` value from the server response stream.
      Returns:
        the result as a `BigDecimal`
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### skip

          int skip(int skip)
             throws java.io.IOException

      Discards bytes from the server response stream.
      Parameters:
        `skip` - the number of bytes to discard
      Returns:
        the number of bytes skipped
      Throws:
        `java.io.IOException`

    - #### skipToEnd

          void skipToEnd()

      Consumes the rest of the server response, without parsing it.

      Note: Use only in extreme cases, packets will not be parsed and could leave the connection in an inconsistent state.

    - #### close

          void close()

      Closes this response stream. The stream id is unlinked from the underlying shared socket as well.

    - #### getTdsVersion

          int getTdsVersion()

      Retrieves the TDS version number.
      Returns:
        the TDS version as an `int`

    - #### getServerType

          int getServerType()

      Retrieves the server type.
      Returns:
        the server type as an `int`

    - #### getInputStream

          java.io.InputStream getInputStream(int len)

      Creates a simple `InputStream` over the server response.

      This method can be used to obtain a stream which can be passed to `InputStreamReader`s to assist in reading multi byte character sets.
      Parameters:
        `len` - the number of bytes available in the server response
      Returns:
        the `InputStream` built over the server response

    - #### getPacket

          private void getPacket()
                          throws java.io.IOException

      Read the next TDS packet from the network.
      Throws:
        `java.io.IOException` - if an I/O error occurs

Generated on June 8 2013