org.postgresql.core

Class PGStream

java.lang.Object

org.postgresql.core.PGStream

public class PGStream
extends java.lang.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(java.lang.String host, int port) Constructor: Connect to the PostgreSQL back end and return a stream connection.

Method Summary

Methods

Modifier and Type	Method and Description
void	changeSocket(java.net.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()
java.io.Writer	getEncodingWriter() Get a Writer instance that encodes directly onto the underlying stream.
java.lang.String	getHost()
int	getPort()
java.net.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
java.lang.String	ReceiveString() Receives a null-terminated string from the backend.
java.lang.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(java.io.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(java.lang.String host,
        int port)
         throws java.io.IOException

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

Parameters:

host - the hostname to connect to

port - the port number that the postmaster is sitting on

Throws:

java.io.IOException - if an IOException occurs below it.

Method Detail

getHost

public java.lang.String getHost()

getPort

public int getPort()

getSocket

public java.net.Socket getSocket()

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

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

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

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

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

ReceiveTupleV3

public byte[][] ReceiveTupleV3()
                        throws java.io.IOException,
                               java.lang.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:

java.io.IOException - if a data I/O error occurs

java.lang.OutOfMemoryError

ReceiveTupleV2

public byte[][] ReceiveTupleV2(int nf,
                      boolean bin)
                        throws java.io.IOException,
                               java.lang.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:

java.io.IOException - if a data I/O error occurs

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

flush

public void flush()
           throws java.io.IOException

Flush any pending output to the backend.

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.sql.SQLException - if we get something other than an EOF

java.io.IOException

close

public void close()
           throws java.io.IOException

Closes the connection

Throws:

java.io.IOException - if an I/O Error occurs