Package org.postgresql.core

# Class PGStream

java.lang.Object
org.postgresql.core.PGStream

All Implemented Interfaces:
  `Closeable`, `Flushable`, `AutoCloseable`

public class PGStream extends Object implements Closeable, Flushable
Wrapper around the raw connection to the server that implements some basic primitives (reading/writing formatted data, doing string encoding, etc).

In general, instances of PGStream are not threadsafe; the caller must ensure that only one thread at a time is accessing a particular PGStream instance.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `PGStream(SocketFactory socketFactory, HostSpec hostSpec)`
  Deprecated.
  use `PGStream(SocketFactory, org.postgresql.util.HostSpec, int, int)`
  `PGStream(SocketFactory socketFactory, HostSpec hostSpec, int timeout)`
  Deprecated.
  use `PGStream(SocketFactory, org.postgresql.util.HostSpec, int, int)`
  `PGStream(SocketFactory socketFactory, HostSpec hostSpec, int timeout, int maxSendBufferSize)`
  Constructor: Connect to the PostgreSQL back end and return a stream connection.
  `PGStream(PGStream pgStream, int timeout)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `changeSocket(Socket socket)`
  Switch this stream to using a new socket.
  `void`
  `clearMaxRowSizeBytes()`
  Clear value of max row size noticed so far.
  `void`
  `clearResultBufferCount()`
  Clear count of byte buffer.
  `void`
  `close()`
  Closes the connection.
  `void`
  `flush()`
  Flush any pending output to the backend.
  `Encoding`
  `getEncoding()`
  `Writer`
  `getEncodingWriter()`
  Get a Writer instance that encodes directly onto the underlying stream.
  `HostSpec`
  `getHostSpec()`
  `long`
  `getMaxResultBuffer()`
  Get MaxResultBuffer from PGStream.
  `int`
  `getMaxRowSizeBytes()`
  Get actual max row size noticed so far.
  `int`
  `getNetworkTimeout()`
  `@Nullable ProtocolVersion`
  `getProtocolVersion()`
  `Socket`
  `getSocket()`
  `SocketFactory`
  `getSocketFactory()`
  `boolean`
  `hasMessagePending()`
  Check for pending backend messages without blocking.
  `boolean`
  `isClosed()`
  `boolean`
  `isGssEncrypted()`
  `int`
  `peekChar()`
  Receives a single character from the backend, without advancing the current protocol stream position.
  `void`
  `receive(byte[] buf, int off, int siz)`
  Reads in a given number of bytes from the backend.
  `byte[]`
  `receive(int siz)`
  Reads in a given number of bytes from the backend.
  `String`
  `receiveCanonicalString()`
  Receives a null-terminated string from the backend and attempts to decode to a `canonical` `String`.
  `String`
  `receiveCanonicalStringIfPresent()`
  Receives a null-terminated string from the backend and attempts to decode to a `canonical` `String`.
  `int`
  `receiveChar()`
  Receives a single character from the backend.
  `void`
  `receiveEOF()`
  Consume an expected EOF from the backend.
  `EncodingPredictor.DecodeResult`
  `receiveErrorString(int len)`
  Receives a fixed-size string from the backend, and tries to avoid "UTF-8 decode failed" errors.
  `int`
  `receiveInteger2()`
  Receives a two byte integer from the backend as an unsigned integer (0..65535).
  `int`
  `receiveInteger4()`
  Receives a four byte integer from the backend.
  `String`
  `receiveString()`
  Receives a null-terminated string from the backend.
  `String`
  `receiveString(int len)`
  Receives a fixed-size string from the backend.
  `Tuple`
  `receiveTupleV3()`
  Read a tuple from the back end.
  `void`
  `send(byte[] buf)`
  Send an array of bytes to the backend.
  `void`
  `send(byte[] buf, int siz)`
  Send a fixed-size array of bytes to the backend.
  `void`
  `send(byte[] buf, int off, int siz)`
  Send a fixed-size array of bytes to the backend.
  `void`
  `send(ByteStreamWriter writer)`
  Send a fixed-size array of bytes to the backend.
  `void`
  `sendChar(int val)`
  Sends a single character to the back end.
  `void`
  `sendInteger2(int val)`
  Sends a 2-byte integer (short) to the back end.
  `void`
  `sendInteger4(int val)`
  Sends a 4-byte integer to the back end.
  `void`
  `sendStream(InputStream inStream, int remaining)`
  Copy data from an input stream to the connection.
  `void`
  `sendZeros(int length)`
  Writes the given amount of zero bytes to the output stream
  `void`
  `setEncoding(Encoding encoding)`
  Change the encoding used by this connection.
  `void`
  `setMaxResultBuffer(@Nullable String value)`
  Method to set MaxResultBuffer inside PGStream.
  `void`
  `setMaxRowSizeBytes(int rowSizeBytes)`
  The idea behind this method is to keep in maxRowSize the size of biggest read data row.
  `void`
  `setMinStreamAvailableCheckDelay(int delay)`
  `void`
  `setNetworkTimeout(int milliseconds)`
  `void`
  `setProtocolVersion(ProtocolVersion protocolVersion)`
  `void`
  `setSecContext(GSSContext secContext)`
  `void`
  `skip(int size)`

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

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

- ## Constructor Details

  - ### PGStream

    @Deprecated public PGStream(SocketFactory socketFactory, HostSpec hostSpec, int timeout) throws IOException
    Deprecated.
    use `PGStream(SocketFactory, org.postgresql.util.HostSpec, int, int)`
    Constructor: Connect to the PostgreSQL back end and return a stream connection.
    Parameters:
      `socketFactory` - socket factory to use when creating sockets
      `hostSpec` - the host and port to connect to
      `timeout` - timeout in milliseconds, or 0 if no timeout set
    Throws:
      `IOException` - if an IOException occurs below it.

  - ### PGStream

    public PGStream(SocketFactory socketFactory, HostSpec hostSpec, int timeout, int maxSendBufferSize) throws IOException
    Constructor: Connect to the PostgreSQL back end and return a stream connection.
    Parameters:
      `socketFactory` - socket factory to use when creating sockets
      `hostSpec` - the host and port to connect to
      `timeout` - timeout in milliseconds, or 0 if no timeout set
      `maxSendBufferSize` - maximum amount of bytes buffered before sending to the backend
    Throws:
      `IOException` - if an IOException occurs below it.

  - ### PGStream

    public PGStream(PGStream pgStream, int timeout) throws IOException
    Throws:
      `IOException`

  - ### PGStream

    @Deprecated public PGStream(SocketFactory socketFactory, HostSpec hostSpec) throws IOException
    Deprecated.
    use `PGStream(SocketFactory, org.postgresql.util.HostSpec, int, int)`
    Constructor: Connect to the PostgreSQL back end and return a stream connection.
    Parameters:
      `socketFactory` - socket factory
      `hostSpec` - the host and port to connect to
    Throws:
      `IOException` - if an IOException occurs below it.

- ## Method Details

  - ### isGssEncrypted

    public boolean isGssEncrypted()

  - ### setSecContext

    public void setSecContext(GSSContext secContext) throws GSSException
    Throws:
      `GSSException`

  - ### getHostSpec

    public HostSpec getHostSpec()

  - ### getSocket

    public Socket getSocket()

  - ### getSocketFactory

    public SocketFactory getSocketFactory()

  - ### hasMessagePending

    public boolean hasMessagePending() throws IOException
    Check for pending backend messages without blocking. Might return false when there actually are messages waiting, depending on the characteristics of the underlying socket. This is used to detect asynchronous notifies from the backend, when available.
    Returns:
      true if there is a pending backend message
    Throws:
      `IOException` - if something wrong happens

  - ### setMinStreamAvailableCheckDelay

    public void setMinStreamAvailableCheckDelay(int delay)

  - ### changeSocket

    public void changeSocket(Socket socket) throws IOException
    Switch this stream to using a new socket. Any existing socket is not closed; it's assumed that we are changing to a new socket that delegates to the original socket (e.g. SSL).
    Parameters:
      `socket` - the new socket to change to
    Throws:
      `IOException` - if something goes wrong

  - ### getEncoding

    public Encoding getEncoding()

  - ### setEncoding

    public void setEncoding(Encoding encoding) throws IOException
    Change the encoding used by this connection.
    Parameters:
      `encoding` - the new encoding to use
    Throws:
      `IOException` - if something goes wrong

  - ### getEncodingWriter

    public Writer getEncodingWriter() throws IOException
    Get a Writer instance that encodes directly onto the underlying stream.

    The returned Writer should not be closed, as it's a shared object. Writer.flush needs to be called when switching between use of the Writer and use of the PGStream write methods, but it won't actually flush output all the way out -- call `flush()` to actually ensure all output has been pushed to the server.

    Returns:
      the shared Writer instance
    Throws:
      `IOException` - if something goes wrong.

  - ### sendChar

    public void sendChar(int val) throws IOException
    Sends a single character to the back end.
    Parameters:
      `val` - the character to be sent
    Throws:
      `IOException` - if an I/O error occurs

  - ### sendInteger4

    public void sendInteger4(int val) throws IOException
    Sends a 4-byte integer to the back end.
    Parameters:
      `val` - the integer to be sent
    Throws:
      `IOException` - if an I/O error occurs

  - ### sendInteger2

    public void sendInteger2(int val) throws IOException
    Sends a 2-byte integer (short) to the back end.
    Parameters:
      `val` - the integer to be sent
    Throws:
      `IOException` - if an I/O error occurs or `val` cannot be encoded in 2 bytes

  - ### send

    public void send(byte[] buf) throws IOException
    Send an array of bytes to the backend.
    Parameters:
      `buf` - The array of bytes to be sent
    Throws:
      `IOException` - if an I/O error occurs

  - ### send

    public void send(byte[] buf, int siz) throws IOException
    Send a fixed-size array of bytes to the backend. If `buf.length < siz`, pad with zeros. If `buf.length > siz`, truncate the array.
    Parameters:
      `buf` - the array of bytes to be sent
      `siz` - the number of bytes to be sent
    Throws:
      `IOException` - if an I/O error occurs

  - ### send

    public void send(byte[] buf, int off, int siz) throws IOException
    Send a fixed-size array of bytes to the backend. If `length < siz`, pad with zeros. If `length > siz`, truncate the array.
    Parameters:
      `buf` - the array of bytes to be sent
      `off` - offset in the array to start sending from
      `siz` - the number of bytes to be sent
    Throws:
      `IOException` - if an I/O error occurs

  - ### send

    public void send(ByteStreamWriter writer) throws IOException
    Send a fixed-size array of bytes to the backend. If `length < siz`, pad with zeros. If `length > siz`, truncate the array.
    Parameters:
      `writer` - the stream writer to invoke to send the bytes
    Throws:
      `IOException` - if an I/O error occurs

  - ### peekChar

    public int peekChar() throws IOException
    Receives a single character from the backend, without advancing the current protocol stream position.
    Returns:
      the character received
    Throws:
      `IOException` - if an I/O Error occurs

  - ### receiveChar

    public int receiveChar() throws IOException
    Receives a single character from the backend.
    Returns:
      the character received
    Throws:
      `IOException` - if an I/O Error occurs

  - ### receiveInteger4

    public int receiveInteger4() throws IOException
    Receives a four byte integer from the backend.
    Returns:
      the integer received from the backend
    Throws:
      `IOException` - if an I/O error occurs

  - ### receiveInteger2

    public int receiveInteger2() throws IOException
    Receives a two byte integer from the backend as an unsigned integer (0..65535).
    Returns:
      the integer received from the backend
    Throws:
      `IOException` - if an I/O error occurs

  - ### receiveString

    public String receiveString(int len) throws IOException
    Receives a fixed-size string from the backend.
    Parameters:
      `len` - the length of the string to receive, in bytes.
    Returns:
      the decoded string
    Throws:
      `IOException` - if something wrong happens

  - ### receiveErrorString

    public EncodingPredictor.DecodeResult receiveErrorString(int len) throws IOException
    Receives a fixed-size string from the backend, and tries to avoid "UTF-8 decode failed" errors.
    Parameters:
      `len` - the length of the string to receive, in bytes.
    Returns:
      the decoded string
    Throws:
      `IOException` - if something wrong happens

  - ### receiveString

    public String receiveString() throws IOException
    Receives a null-terminated string from the backend. If we don't see a null, then we assume something has gone wrong.
    Returns:
      string from back end
    Throws:
      `IOException` - if an I/O error occurs, or end of file

  - ### receiveCanonicalString

    public String receiveCanonicalString() throws IOException
    Receives a null-terminated string from the backend and attempts to decode to a `canonical` `String`. If we don't see a null, then we assume something has gone wrong.
    Returns:
      string from back end
    Throws:
      `IOException` - if an I/O error occurs, or end of file
    See Also:
      - `Encoding.decodeCanonicalized(byte[], int, int)`

  - ### receiveCanonicalStringIfPresent

    public String receiveCanonicalStringIfPresent() throws IOException
    Receives a null-terminated string from the backend and attempts to decode to a `canonical` `String`. If we don't see a null, then we assume something has gone wrong.
    Returns:
      string from back end
    Throws:
      `IOException` - if an I/O error occurs, or end of file
    See Also:
      - `Encoding.decodeCanonicalizedIfPresent(byte[], int, int)`

  - ### receiveTupleV3

    public Tuple receiveTupleV3() throws IOException, OutOfMemoryError, SQLException
    Read a tuple from the back end. A tuple is a two dimensional array of bytes. This variant reads the V3 protocol's tuple representation.
    Returns:
      tuple from the back end
    Throws:
      `IOException` - if a data I/O error occurs
      `SQLException` - if read more bytes than set maxResultBuffer
      `OutOfMemoryError`

  - ### receive

    public byte[] receive(int siz) throws IOException
    Reads in a given number of bytes from the backend.
    Parameters:
      `siz` - number of bytes to read
    Returns:
      array of bytes received
    Throws:
      `IOException` - if a data I/O error occurs

  - ### receive

    public void receive(byte[] buf, int off, int siz) throws IOException
    Reads in a given number of bytes from the backend.
    Parameters:
      `buf` - buffer to store result
      `off` - offset in buffer
      `siz` - number of bytes to read
    Throws:
      `IOException` - if a data I/O error occurs

  - ### skip

    public void skip(int size) throws IOException
    Throws:
      `IOException`

  - ### sendStream

    public void sendStream(InputStream inStream, int remaining) throws IOException
    Copy data from an input stream to the connection.
    Parameters:
      `inStream` - the stream to read data from
      `remaining` - the number of bytes to copy
    Throws:
      `IOException` - if error occurs when writing the data to the output stream
      `SourceStreamIOException` - if error occurs when reading the data from the input stream

  - ### sendZeros

    public void sendZeros(int length) throws IOException
    Writes the given amount of zero bytes to the output stream
    Parameters:
      `length` - the number of zeros to write
    Throws:
      `IOException` - in case writing to the output stream fails
      `SourceStreamIOException` - in case reading from the source stream fails

  - ### flush

    public void flush() throws IOException
    Flush any pending output to the backend.
    Specified by:
      `flush` in interface `Flushable`
    Throws:
      `IOException` - if an I/O error occurs

  - ### receiveEOF

    public void receiveEOF() throws SQLException, IOException
    Consume an expected EOF from the backend.
    Throws:
      `IOException` - if an I/O error occurs
      `SQLException` - if we get something other than an EOF

  - ### close

    public void close() throws IOException
    Closes the connection.
    Specified by:
      `close` in interface `AutoCloseable`
    Specified by:
      `close` in interface `Closeable`
    Throws:
      `IOException` - if an I/O Error occurs

  - ### setNetworkTimeout

    public void setNetworkTimeout(int milliseconds) throws IOException
    Throws:
      `IOException`

  - ### getNetworkTimeout

    public int getNetworkTimeout() throws IOException
    Throws:
      `IOException`

  - ### setMaxResultBuffer

    public void setMaxResultBuffer(@Nullable String value) throws PSQLException
    Method to set MaxResultBuffer inside PGStream.
    Parameters:
      `value` - value of new max result buffer as string (cause we can expect % or chars to use multiplier)
    Throws:
      `PSQLException` - exception returned when occurred parsing problem.

  - ### getMaxResultBuffer

    public long getMaxResultBuffer()
    Get MaxResultBuffer from PGStream.
    Returns:
      size of MaxResultBuffer

  - ### setMaxRowSizeBytes

    public void setMaxRowSizeBytes(int rowSizeBytes)
    The idea behind this method is to keep in maxRowSize the size of biggest read data row. As there may be many data rows send after each other for a query, then value in maxRowSize would contain value noticed so far, because next data rows and their sizes are not read for that moment. We want it increasing, because the size of the biggest among data rows will be used during computing new adaptive fetch size for the query.
    Parameters:
      `rowSizeBytes` - new value to be set as maxRowSizeBytes

  - ### getMaxRowSizeBytes

    public int getMaxRowSizeBytes()
    Get actual max row size noticed so far.
    Returns:
      value of max row size

  - ### clearMaxRowSizeBytes

    public void clearMaxRowSizeBytes()
    Clear value of max row size noticed so far.

  - ### clearResultBufferCount

    public void clearResultBufferCount()
    Clear count of byte buffer.

  - ### getProtocolVersion

    public @Nullable ProtocolVersion getProtocolVersion()

  - ### setProtocolVersion

    public void setProtocolVersion(ProtocolVersion protocolVersion)

  - ### isClosed

    public boolean isClosed()