Top Description Methods
org.postgresql.core

public Interface ParameterList

Known Direct Subinterfaces
org.postgresql.core.v3.V3ParameterList
Imports
org.postgresql.util.ByteStreamWriter, org.checkerframework.checker.index.qual.NonNegative, .Positive, org.checkerframework.checker.nullness.qual.Nullable, java.io.InputStream, java.sql.SQLException

Abstraction of a list of parameters to be substituted into a Query. The protocol-specific details of how to efficiently store and stream the parameters is hidden behind implementations of this interface.

In general, instances of ParameterList are associated with a particular Query object (the one that created them) and shouldn't be used against another Query.

Parameter indexes are 1-based to match JDBC's PreparedStatement, i.e. the first parameter has index 1.

Author
Oliver Jowett ([email protected])

Method Summary

Modifier and TypeMethod and Description
public void
appendAll(ParameterList
of parameters to append with.
list)

Use this operation to append more parameters to the current list.

public void
clear()

Unbind all parameter values bound in this list.

public ParameterList

Returns:

a new ParameterList instance
copy()

Perform a shallow copy of this ParameterList, returning a new instance (still suitable for passing to the owning Query).

public @NonNegative int

Returns:

the number of IN parameters in this list
getInParameterCount()

Get the number of IN parameters in this list.

public @NonNegative int

Returns:

the number of OUT parameters in this list
getOutParameterCount()

Get the number of OUT parameters in this list.

public @NonNegative int

Returns:

the number of parameters in this list.
getParameterCount()

Get the number of parameters in this list.

public int[]

Returns:

oids of the parameters
getTypeOIDs()

Return the oids of the parameters in this list.

public @Nullable @Nullable Object[]

Returns:

Object array containing the parameter values.
getValues()

Returns the bound parameter values.

public void
registerOutParameter(@Positive int index, int sqlType)

public void
setBinaryParameter(@Positive int
the 1-based parameter index to bind.
index, byte[]
the bytes to send.
value, int
the type OID of the parameter.
oid)

Binds given byte[] value to a parameter.

public void
setBytea(@Positive int
the 1-based parameter index to bind.
index, byte[]
an array containing the raw data value
data, @NonNegative int
the offset within data of the start of the parameter data.
offset, @NonNegative int
the number of bytes of parameter data within data to use.
length)

Binds a binary bytea value stored as a bytearray to a parameter.

public void
setBytea(@Positive int
the 1-based parameter index to bind.
index, InputStream
a stream containing the parameter data.
stream, @NonNegative int
the number of bytes of parameter data to read from stream.
length)

Binds a binary bytea value stored as an InputStream.

public void
setBytea(@Positive int
the 1-based parameter index to bind.
index, InputStream
a stream containing the parameter data.
stream)

Binds a binary bytea value stored as an InputStream.

public void
setBytea(@Positive int
the 1-based parameter index to bind.
index, ByteStreamWriter
a writer that can write the bytes for the parameter
writer)

Binds a binary bytea value stored as a ByteStreamWriter.

public void
setIntParameter(@Positive int
the 1-based parameter index to bind.
index, int
the integer value to use.
value)

Binds an integer value to a parameter.

public void
setLiteralParameter(@Positive int
the 1-based parameter index to bind.
index, String
the unquoted literal string to use.
value, int
the type OID of the parameter, or 0 to infer the type.
oid)

Binds a String value that is an unquoted literal to the server's query parser (for example, a bare integer) to a parameter.

public void
setNull(@Positive int
the 1-based parameter index to bind.
index, int
the type OID of the parameter, or 0 to infer the type.
oid)

Binds a SQL NULL value to a parameter.

public void
setStringParameter(@Positive int
the 1-based parameter index to bind.
index, String
the quoted string to use.
value, int
the type OID of the parameter, or 0 to infer the type.
oid)

Binds a String value that needs to be quoted for the server's parser to understand (for example, a timestamp) to a parameter.

public void
setText(@Positive int
the 1-based parameter index to bind.
index, InputStream
a stream containing the parameter data.
stream)

Binds a text value stored as an InputStream that is a valid UTF-8 byte stream.

public String

Returns:

a string representation of the parameter.
toString(@Positive int
the 1-based parameter index to bind.
index, boolean
true if \ is not an escape character in strings literals
standardConformingStrings)

Return a human-readable representation of a particular parameter in this ParameterList.

Method Detail

appendAllback to summary
public void appendAll(ParameterList list) throws SQLException

Use this operation to append more parameters to the current list.

Parameters
list:ParameterList

of parameters to append with.

Exceptions
SQLException:
fault raised if driver or back end throw an exception
clearback to summary
public void clear()

Unbind all parameter values bound in this list.

copyback to summary
public ParameterList copy()

Perform a shallow copy of this ParameterList, returning a new instance (still suitable for passing to the owning Query). If this ParameterList is immutable, copy() may return the same immutable object.

Returns:ParameterList

a new ParameterList instance

getInParameterCountback to summary
public @NonNegative int getInParameterCount()

Get the number of IN parameters in this list.

Returns:@NonNegative int

the number of IN parameters in this list

getOutParameterCountback to summary
public @NonNegative int getOutParameterCount()

Get the number of OUT parameters in this list.

Returns:@NonNegative int

the number of OUT parameters in this list

getParameterCountback to summary
public @NonNegative int getParameterCount()

Get the number of parameters in this list. This value never changes for a particular instance, and might be zero.

Returns:@NonNegative int

the number of parameters in this list.

getTypeOIDsback to summary
public int[] getTypeOIDs()

Return the oids of the parameters in this list. May be null for a ParameterList that does not support typing of parameters.

Returns:int[]

oids of the parameters

getValuesback to summary
public @Nullable @Nullable Object[] getValues()

Returns the bound parameter values.

Returns:@Nullable @Nullable Object[]

Object array containing the parameter values.

registerOutParameterback to summary
public void registerOutParameter(@Positive int index, int sqlType) throws SQLException
setBinaryParameterback to summary
public void setBinaryParameter(@Positive int index, byte[] value, int oid) throws SQLException

Binds given byte[] value to a parameter. The bytes must already be in correct format matching the OID.

Parameters
index:@Positive int

the 1-based parameter index to bind.

value:byte[]

the bytes to send.

oid:int

the type OID of the parameter.

Exceptions
SQLException:
on error or if index is out of range
setByteaback to summary
public void setBytea(@Positive int index, byte[] data, @NonNegative int offset, @NonNegative int length) throws SQLException

Binds a binary bytea value stored as a bytearray to a parameter. The parameter's type is implicitly set to 'bytea'. The bytearray's contains should remain unchanged until query execution has completed.

Parameters
index:@Positive int

the 1-based parameter index to bind.

data:byte[]

an array containing the raw data value

offset:@NonNegative int

the offset within data of the start of the parameter data.

length:@NonNegative int

the number of bytes of parameter data within data to use.

Exceptions
SQLException:
on error or if index is out of range
setByteaback to summary
public void setBytea(@Positive int index, InputStream stream, @NonNegative int length) throws SQLException

Binds a binary bytea value stored as an InputStream. The parameter's type is implicitly set to 'bytea'. The stream should remain valid until query execution has completed.

Parameters
index:@Positive int

the 1-based parameter index to bind.

stream:InputStream

a stream containing the parameter data.

length:@NonNegative int

the number of bytes of parameter data to read from stream.

Exceptions
SQLException:
on error or if index is out of range
setByteaback to summary
public void setBytea(@Positive int index, InputStream stream) throws SQLException

Binds a binary bytea value stored as an InputStream. The parameter's type is implicitly set to 'bytea'. The stream should remain valid until query execution has completed.

Parameters
index:@Positive int

the 1-based parameter index to bind.

stream:InputStream

a stream containing the parameter data.

Exceptions
SQLException:
on error or if index is out of range
setByteaback to summary
public void setBytea(@Positive int index, ByteStreamWriter writer) throws SQLException

Binds a binary bytea value stored as a ByteStreamWriter. The parameter's type is implicitly set to 'bytea'. The stream should remain valid until query execution has completed.

Parameters
index:@Positive int

the 1-based parameter index to bind.

writer:ByteStreamWriter

a writer that can write the bytes for the parameter

Exceptions
SQLException:
on error or if index is out of range
setIntParameterback to summary
public void setIntParameter(@Positive int index, int value) throws SQLException

Binds an integer value to a parameter. The type of the parameter is implicitly 'int4'.

Parameters
index:@Positive int

the 1-based parameter index to bind.

value:int

the integer value to use.

Exceptions
SQLException:
on error or if index is out of range
setLiteralParameterback to summary
public void setLiteralParameter(@Positive int index, String value, int oid) throws SQLException

Binds a String value that is an unquoted literal to the server's query parser (for example, a bare integer) to a parameter. Associated with the parameter is a typename for the parameter that should correspond to an entry in pg_types.

Parameters
index:@Positive int

the 1-based parameter index to bind.

value:String

the unquoted literal string to use.

oid:int

the type OID of the parameter, or 0 to infer the type.

Exceptions
SQLException:
on error or if index is out of range
setNullback to summary
public void setNull(@Positive int index, int oid) throws SQLException

Binds a SQL NULL value to a parameter. Associated with the parameter is a typename for the parameter that should correspond to an entry in pg_types.

Parameters
index:@Positive int

the 1-based parameter index to bind.

oid:int

the type OID of the parameter, or 0 to infer the type.

Exceptions
SQLException:
on error or if index is out of range
setStringParameterback to summary
public void setStringParameter(@Positive int index, String value, int oid) throws SQLException

Binds a String value that needs to be quoted for the server's parser to understand (for example, a timestamp) to a parameter. Associated with the parameter is a typename for the parameter that should correspond to an entry in pg_types.

Parameters
index:@Positive int

the 1-based parameter index to bind.

value:String

the quoted string to use.

oid:int

the type OID of the parameter, or 0 to infer the type.

Exceptions
SQLException:
on error or if index is out of range
setTextback to summary
public void setText(@Positive int index, InputStream stream) throws SQLException

Binds a text value stored as an InputStream that is a valid UTF-8 byte stream. Any byte-order marks (BOM) in the stream are passed to the backend. The parameter's type is implicitly set to 'text'. The stream should remain valid until query execution has completed.

Parameters
index:@Positive int

the 1-based parameter index to bind.

stream:InputStream

a stream containing the parameter data.

Exceptions
SQLException:
on error or if index is out of range
toStringback to summary
public String toString(@Positive int index, boolean standardConformingStrings)

Return a human-readable representation of a particular parameter in this ParameterList. If the parameter is not bound, returns "?".

Parameters
index:@Positive int

the 1-based parameter index to bind.

standardConformingStrings:boolean

true if \ is not an escape character in strings literals

Returns:String

a string representation of the parameter.