Package org.postgresql.core

# Interface ParameterList

public interface ParameterList

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.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `appendAll(ParameterList list)`
  Use this operation to append more parameters to the current list.
  `void`
  `clear()`
  Unbind all parameter values bound in this list.
  `ParameterList`
  `copy()`
  Perform a shallow copy of this ParameterList, returning a new instance (still suitable for passing to the owning Query).
  `@org.checkerframework.checker.index.qual.NonNegative int`
  `getInParameterCount()`
  Get the number of IN parameters in this list.
  `@org.checkerframework.checker.index.qual.NonNegative int`
  `getOutParameterCount()`
  Get the number of OUT parameters in this list.
  `@org.checkerframework.checker.index.qual.NonNegative int`
  `getParameterCount()`
  Get the number of parameters in this list.
  `int[]`
  `getTypeOIDs()`
  Return the oids of the parameters in this list.
  `@Nullable Object @Nullable []`
  `getValues()`
  Returns the bound parameter values.
  `void`
  `registerOutParameter(@org.checkerframework.checker.index.qual.Positive int index, int sqlType)`
  `void`
  `setBinaryParameter(@org.checkerframework.checker.index.qual.Positive int index, byte[] value, int oid)`
  Binds given byte[] value to a parameter.
  `void`
  `setBytea(@org.checkerframework.checker.index.qual.Positive int index, byte[] data, @org.checkerframework.checker.index.qual.NonNegative int offset, @org.checkerframework.checker.index.qual.NonNegative int length)`
  Binds a binary bytea value stored as a bytearray to a parameter.
  `void`
  `setBytea(@org.checkerframework.checker.index.qual.Positive int index, InputStream stream)`
  Binds a binary bytea value stored as an InputStream.
  `void`
  `setBytea(@org.checkerframework.checker.index.qual.Positive int index, InputStream stream, @org.checkerframework.checker.index.qual.NonNegative int length)`
  Binds a binary bytea value stored as an InputStream.
  `void`
  `setBytea(@org.checkerframework.checker.index.qual.Positive int index, ByteStreamWriter writer)`
  Binds a binary bytea value stored as a ByteStreamWriter.
  `void`
  `setIntParameter(@org.checkerframework.checker.index.qual.Positive int index, int value)`
  Binds an integer value to a parameter.
  `void`
  `setLiteralParameter(@org.checkerframework.checker.index.qual.Positive int index, String value, int oid)`
  Binds a String value that is an unquoted literal to the server's query parser (for example, a bare integer) to a parameter.
  `void`
  `setNull(@org.checkerframework.checker.index.qual.Positive int index, int oid)`
  Binds a SQL NULL value to a parameter.
  `void`
  `setStringParameter(@org.checkerframework.checker.index.qual.Positive int index, String value, int oid)`
  Binds a String value that needs to be quoted for the server's parser to understand (for example, a timestamp) to a parameter.
  `void`
  `setText(@org.checkerframework.checker.index.qual.Positive int index, InputStream stream)`
  Binds a text value stored as an InputStream that is a valid UTF-8 byte stream.
  `String`
  `toString(@org.checkerframework.checker.index.qual.Positive int index, boolean standardConformingStrings)`
  Return a human-readable representation of a particular parameter in this ParameterList.

- ## Method Details

  - ### registerOutParameter

    void registerOutParameter(@org.checkerframework.checker.index.qual.Positive int index, int sqlType) throws SQLException
    Throws:
      `SQLException`

  - ### getParameterCount

    @org.checkerframework.checker.index.qual.NonNegative int getParameterCount()
    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.

  - ### getInParameterCount

    @org.checkerframework.checker.index.qual.NonNegative int getInParameterCount()
    Get the number of IN parameters in this list.
    Returns:
      the number of IN parameters in this list

  - ### getOutParameterCount

    @org.checkerframework.checker.index.qual.NonNegative int getOutParameterCount()
    Get the number of OUT parameters in this list.
    Returns:
      the number of OUT parameters in this list

  - ### getTypeOIDs

    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:
      oids of the parameters

  - ### setIntParameter

    void setIntParameter(@org.checkerframework.checker.index.qual.Positive int index, int value) throws SQLException
    Binds an integer value to a parameter. The type of the parameter is implicitly 'int4'.
    Parameters:
      `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

  - ### setLiteralParameter

    void setLiteralParameter(@org.checkerframework.checker.index.qual.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` - 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

  - ### setStringParameter

    void setStringParameter(@org.checkerframework.checker.index.qual.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` - 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

  - ### setBytea

    void setBytea(@org.checkerframework.checker.index.qual.Positive int index, byte[] data, @org.checkerframework.checker.index.qual.NonNegative int offset, @org.checkerframework.checker.index.qual.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` - 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

  - ### setBytea

    void setBytea(@org.checkerframework.checker.index.qual.Positive int index, InputStream stream, @org.checkerframework.checker.index.qual.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` - 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

  - ### setBytea

    void setBytea(@org.checkerframework.checker.index.qual.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` - 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

  - ### setBytea

    void setBytea(@org.checkerframework.checker.index.qual.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` - the 1-based parameter index to bind.
      `writer` - a writer that can write the bytes for the parameter
    Throws:
      `SQLException` - on error or if `index` is out of range

  - ### setText

    void setText(@org.checkerframework.checker.index.qual.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` - 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

  - ### setBinaryParameter

    void setBinaryParameter(@org.checkerframework.checker.index.qual.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` - 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

  - ### setNull

    void setNull(@org.checkerframework.checker.index.qual.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` - 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

  - ### copy

    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:
      a new ParameterList instance

  - ### clear

    void clear()
    Unbind all parameter values bound in this list.

  - ### toString

    String toString(@org.checkerframework.checker.index.qual.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` - 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.

  - ### appendAll

    void appendAll(ParameterList list) throws SQLException
    Use this operation to append more parameters to the current list.
    Parameters:
      `list` - of parameters to append with.
    Throws:
      `SQLException` - fault raised if driver or back end throw an exception

  - ### getValues

    @Nullable Object @Nullable [] getValues()
    Returns the bound parameter values.
    Returns:
      Object array containing the parameter values.