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 and Description
PGStream(PGStream pgStream, int timeout)
PGStream(SocketFactory socketFactory, HostSpec hostSpec) Deprecated. use PGStream(SocketFactory, org.postgresql.util.HostSpec, int)
PGStream(SocketFactory socketFactory, HostSpec hostSpec, int timeout) Constructor: Connect to the PostgreSQL back end and return a stream connection.

Method Summary

Modifier and Type	Method and 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()
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.
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	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	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 Detail

PGStream

public PGStream(SocketFactory socketFactory,
                HostSpec hostSpec,
                int timeout)
         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

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)

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 Detail

isGssEncrypted

public boolean isGssEncrypted()

setSecContext

public void setSecContext(GSSContext secContext)

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.lengh > 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.

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 a data I/O error occurs

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 Closeable

Specified by:

close in interface AutoCloseable

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.

isClosed

public boolean isClosed()