org.postgresql.core

Class PGStream

java.lang.Object

org.postgresql.core.PGStream

public class PGStream
extends Object

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(HostSpec hostSpec) Deprecated. use PGStream(org.postgresql.util.HostSpec, int)
PGStream(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	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()
Socket	getSocket()
boolean	hasMessagePending() Check for pending backend messages without blocking.
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
int	ReceiveChar() Receives a single character from the backend
void	ReceiveEOF() Consume an expected EOF from the backend
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.
byte[][]	ReceiveTupleV2(int nf, boolean bin) Read a tuple from the back end.
byte[][]	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	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	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(HostSpec hostSpec,
                int timeout)
         throws IOException

Constructor: Connect to the PostgreSQL back end and return a stream connection.

Parameters:

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(HostSpec hostSpec)
         throws IOException

Deprecated. use PGStream(org.postgresql.util.HostSpec, int)

Constructor: Connect to the PostgreSQL back end and return a stream connection.

Parameters:

hostSpec - the host and port to connect to

Throws:

IOException - if an IOException occurs below it.

Method Detail

getHostSpec

public HostSpec getHostSpec()

getSocket

public Socket getSocket()

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

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

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

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

ReceiveTupleV3

public byte[][] ReceiveTupleV3()
                        throws IOException,
                               OutOfMemoryError

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:

null if the current response has no more tuples, otherwise an array of bytearrays

Throws:

IOException - if a data I/O error occurs

OutOfMemoryError

ReceiveTupleV2

public byte[][] ReceiveTupleV2(int nf,
                               boolean bin)
                        throws IOException,
                               OutOfMemoryError

Read a tuple from the back end. A tuple is a two dimensional array of bytes. This variant reads the V2 protocol's tuple representation.

Parameters:

nf - the number of fields expected

bin - true if the tuple is a binary tuple

Returns:

null if the current response has no more tuples, otherwise an array of bytearrays

Throws:

IOException - if a data I/O error occurs

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.

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

Throws:

IOException - if an I/O Error occurs