/*
* Copyright (c) 2004, PostgreSQL Global Development Group
* See the LICENSE file in the project root for more information.
*/
// Copyright (c) 2004, Open Cloud Limited.
package org.postgresql.core;
import java.io.InputStream;
import 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 (oliver@opencloud.com)
/**
* <p>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.</p>
*
* <p>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.</p>
*
* <p>Parameter indexes are 1-based to match JDBC's PreparedStatement, i.e. the first parameter has
* index 1.</p>
*
* @author Oliver Jowett (oliver@opencloud.com)
*/
public interface ParameterList {
void registerOutParameter(int index, int sqlType) throws SQLException;
Get the number of parameters in this list. This value never changes for a particular instance,
and might be zero.
Returns: the number of parameters in this list.
/**
* Get the number of parameters in this list. This value never changes for a particular instance,
* and might be zero.
*
* @return the number of parameters in this list.
*/
int getParameterCount();
Get the number of IN parameters in this list.
Returns: the number of IN parameters in this list
/**
* Get the number of IN parameters in this list.
*
* @return the number of IN parameters in this list
*/
int getInParameterCount();
Get the number of OUT parameters in this list.
Returns: the number of OUT parameters in this list
/**
* Get the number of OUT parameters in this list.
*
* @return the number of OUT parameters in this list
*/
int getOutParameterCount();
Return the oids of the parameters in this list. May be null for a ParameterList that does not
support typing of parameters.
Returns: oids of the parameters
/**
* Return the oids of the parameters in this list. May be null for a ParameterList that does not
* support typing of parameters.
*
* @return oids of the parameters
*/
int[] getTypeOIDs();
Binds an integer value to a parameter. The type of the parameter is implicitly 'int4'.
Params: - index – the 1-based parameter index to bind.
- value – the integer value to use.
Throws: - SQLException – on error or if
index
is out of range
/**
* Binds an integer value to a parameter. The type of the parameter is implicitly 'int4'.
*
* @param index the 1-based parameter index to bind.
* @param value the integer value to use.
* @throws SQLException on error or if <code>index</code> is out of range
*/
void setIntParameter(int index, int value) 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.
Params: - index – the 1-based parameter index to bind.
- value – the unquoted literal string to use.
- oid – the type OID of the parameter, or
0
to infer the type.
Throws: - SQLException – on error or if
index
is out of range
/**
* 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.
*
* @param index the 1-based parameter index to bind.
* @param value the unquoted literal string to use.
* @param oid the type OID of the parameter, or <code>0</code> to infer the type.
* @throws SQLException on error or if <code>index</code> is out of range
*/
void setLiteralParameter(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.
Params: - index – the 1-based parameter index to bind.
- value – the quoted string to use.
- oid – the type OID of the parameter, or
0
to infer the type.
Throws: - SQLException – on error or if
index
is out of range
/**
* 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.
*
* @param index the 1-based parameter index to bind.
* @param value the quoted string to use.
* @param oid the type OID of the parameter, or <code>0</code> to infer the type.
* @throws SQLException on error or if <code>index</code> is out of range
*/
void setStringParameter(int index, String value, int oid) 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.
Params: - index – the 1-based parameter index to bind.
- data – an array containing the raw data value
- offset – the offset within
data
of the start of the parameter data. - length – the number of bytes of parameter data within
data
to use.
Throws: - SQLException – on error or if
index
is out of range
/**
* 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.
*
* @param index the 1-based parameter index to bind.
* @param data an array containing the raw data value
* @param offset the offset within <code>data</code> of the start of the parameter data.
* @param length the number of bytes of parameter data within <code>data</code> to use.
* @throws SQLException on error or if <code>index</code> is out of range
*/
void setBytea(int index, byte[] data, int offset, 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.
Params: - index – the 1-based parameter index to bind.
- stream – a stream containing the parameter data.
- length – the number of bytes of parameter data to read from
stream
.
Throws: - SQLException – on error or if
index
is out of range
/**
* 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.
*
* @param index the 1-based parameter index to bind.
* @param stream a stream containing the parameter data.
* @param length the number of bytes of parameter data to read from <code>stream</code>.
* @throws SQLException on error or if <code>index</code> is out of range
*/
void setBytea(int index, InputStream stream, 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.
Params: - index – the 1-based parameter index to bind.
- stream – a stream containing the parameter data.
Throws: - SQLException – on error or if
index
is out of range
/**
* 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.
*
* @param index the 1-based parameter index to bind.
* @param stream a stream containing the parameter data.
* @throws SQLException on error or if <code>index</code> is out of range
*/
void setBytea(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.
Params: - index – the 1-based parameter index to bind.
- stream – a stream containing the parameter data.
Throws: - SQLException – on error or if
index
is out of range
/**
* 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.
*
* @param index the 1-based parameter index to bind.
* @param stream a stream containing the parameter data.
* @throws SQLException on error or if <code>index</code> is out of range
*/
void setText(int index, InputStream stream) throws SQLException;
Binds given byte[] value to a parameter. The bytes must already be in correct format matching
the OID.
Params: - index – the 1-based parameter index to bind.
- value – the bytes to send.
- oid – the type OID of the parameter.
Throws: - SQLException – on error or if
index
is out of range
/**
* Binds given byte[] value to a parameter. The bytes must already be in correct format matching
* the OID.
*
* @param index the 1-based parameter index to bind.
* @param value the bytes to send.
* @param oid the type OID of the parameter.
* @throws SQLException on error or if <code>index</code> is out of range
*/
void setBinaryParameter(int index, byte[] value, 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.
Params: - index – the 1-based parameter index to bind.
- oid – the type OID of the parameter, or
0
to infer the type.
Throws: - SQLException – on error or if
index
is out of range
/**
* 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.
*
* @param index the 1-based parameter index to bind.
* @param oid the type OID of the parameter, or <code>0</code> to infer the type.
* @throws SQLException on error or if <code>index</code> is out of range
*/
void setNull(int index, int oid) throws SQLException;
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: a new ParameterList instance
/**
* 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.
*
* @return a new ParameterList instance
*/
ParameterList copy();
Unbind all parameter values bound in this list.
/**
* Unbind all parameter values bound in this list.
*/
void clear();
Return a human-readable representation of a particular parameter in this ParameterList. If the
parameter is not bound, returns "?".
Params: - index – the 1-based parameter index to bind.
- standardConformingStrings – true if \ is not an escape character in strings literals
Returns: a string representation of the parameter.
/**
* Return a human-readable representation of a particular parameter in this ParameterList. If the
* parameter is not bound, returns "?".
*
* @param index the 1-based parameter index to bind.
* @param standardConformingStrings true if \ is not an escape character in strings literals
* @return a string representation of the parameter.
*/
String toString(int index, boolean standardConformingStrings);
Use this operation to append more parameters to the current list.
Params: - list – of parameters to append with.
Throws: - SQLException – fault raised if driver or back end throw an exception
/**
* Use this operation to append more parameters to the current list.
* @param list of parameters to append with.
* @throws SQLException fault raised if driver or back end throw an exception
*/
void appendAll(ParameterList list) throws SQLException ;
Returns the bound parameter values.
Returns: Object array containing the parameter values.
/**
* Returns the bound parameter values.
* @return Object array containing the parameter values.
*/
Object[] getValues();
}