Class PGStream

  • All Implemented Interfaces:
    java.io.Closeable, java.io.Flushable, java.lang.AutoCloseable

    public class PGStream
    extends java.lang.Object
    implements java.io.Closeable, java.io.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 Detail

      • PGStream

        @Deprecated
        public PGStream​(javax.net.SocketFactory socketFactory,
                        HostSpec hostSpec,
                        int timeout)
                 throws java.io.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
        Throws:
        java.io.IOException - if an IOException occurs below it.
      • PGStream

        public PGStream​(javax.net.SocketFactory socketFactory,
                        HostSpec hostSpec,
                        int timeout,
                        int maxSendBufferSize)
                 throws java.io.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:
        java.io.IOException - if an IOException occurs below it.
      • PGStream

        public PGStream​(PGStream pgStream,
                        int timeout)
                 throws java.io.IOException
        Throws:
        java.io.IOException
      • PGStream

        @Deprecated
        public PGStream​(javax.net.SocketFactory socketFactory,
                        HostSpec hostSpec)
                 throws java.io.IOException
        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:
        java.io.IOException - if an IOException occurs below it.
    • Method Detail

      • isGssEncrypted

        public boolean isGssEncrypted()
      • setSecContext

        public void setSecContext​(org.ietf.jgss.GSSContext secContext)
                           throws org.ietf.jgss.GSSException
        Throws:
        org.ietf.jgss.GSSException
      • getHostSpec

        public HostSpec getHostSpec()
      • getSocket

        public java.net.Socket getSocket()
      • getSocketFactory

        public javax.net.SocketFactory getSocketFactory()
      • hasMessagePending

        public boolean hasMessagePending()
                                  throws java.io.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:
        java.io.IOException - if something wrong happens
      • setMinStreamAvailableCheckDelay

        public void setMinStreamAvailableCheckDelay​(int delay)
      • changeSocket

        public void changeSocket​(java.net.Socket socket)
                          throws java.io.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:
        java.io.IOException - if something goes wrong
      • getEncoding

        public Encoding getEncoding()
      • setEncoding

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

        public java.io.Writer getEncodingWriter()
                                         throws java.io.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:
        java.io.IOException - if something goes wrong.
      • sendChar

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

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

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

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

        public void send​(byte[] buf,
                         int siz)
                  throws java.io.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:
        java.io.IOException - if an I/O error occurs
      • send

        public void send​(byte[] buf,
                         int off,
                         int siz)
                  throws java.io.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:
        java.io.IOException - if an I/O error occurs
      • send

        public void send​(ByteStreamWriter writer)
                  throws java.io.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:
        java.io.IOException - if an I/O error occurs
      • peekChar

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

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

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

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

        public java.lang.String receiveString​(int len)
                                       throws java.io.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:
        java.io.IOException - if something wrong happens
      • receiveErrorString

        public EncodingPredictor.DecodeResult receiveErrorString​(int len)
                                                          throws java.io.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:
        java.io.IOException - if something wrong happens
      • receiveString

        public java.lang.String receiveString()
                                       throws java.io.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:
        java.io.IOException - if an I/O error occurs, or end of file
      • receiveCanonicalString

        public java.lang.String receiveCanonicalString()
                                                throws java.io.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:
        java.io.IOException - if an I/O error occurs, or end of file
        See Also:
        Encoding.decodeCanonicalized(byte[], int, int)
      • receiveCanonicalStringIfPresent

        public java.lang.String receiveCanonicalStringIfPresent()
                                                         throws java.io.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:
        java.io.IOException - if an I/O error occurs, or end of file
        See Also:
        Encoding.decodeCanonicalizedIfPresent(byte[], int, int)
      • receiveTupleV3

        public Tuple receiveTupleV3()
                             throws java.io.IOException,
                                    java.lang.OutOfMemoryError,
                                    java.sql.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:
        java.io.IOException - if a data I/O error occurs
        java.sql.SQLException - if read more bytes than set maxResultBuffer
        java.lang.OutOfMemoryError
      • receive

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

        public void receive​(byte[] buf,
                            int off,
                            int siz)
                     throws java.io.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:
        java.io.IOException - if a data I/O error occurs
      • skip

        public void skip​(int size)
                  throws java.io.IOException
        Throws:
        java.io.IOException
      • sendStream

        public void sendStream​(java.io.InputStream inStream,
                               int remaining)
                        throws java.io.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:
        java.io.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 java.io.IOException
        Writes the given amount of zero bytes to the output stream
        Parameters:
        length - the number of zeros to write
        Throws:
        java.io.IOException - in case writing to the output stream fails
        SourceStreamIOException - in case reading from the source stream fails
      • flush

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

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

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

        public void setNetworkTimeout​(int milliseconds)
                               throws java.io.IOException
        Throws:
        java.io.IOException
      • getNetworkTimeout

        public int getNetworkTimeout()
                              throws java.io.IOException
        Throws:
        java.io.IOException
      • setMaxResultBuffer

        public void setMaxResultBuffer​(java.lang.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.
      • setProtocolVersion

        public void setProtocolVersion​(ProtocolVersion protocolVersion)
      • isClosed

        public boolean isClosed()