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.
  `String`
  `toString(@org.checkerframework.checker.index.qual.Positive int index, SqlSerializationContext context)`
  Return the string literal 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 or is of type bytea sourced from an InputStream, returns "?". This method will NOT consume InputStreams, instead "?" will be returned.
    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.

  - ### toString

    String toString(@org.checkerframework.checker.index.qual.Positive int index, SqlSerializationContext context)
    Return the string literal representation of a particular parameter in this ParameterList. If the parameter is not bound, returns "?". This method will consume all InputStreams to produce the result.
    Parameters:
      `index` - the 1-based parameter index to bind.
      `context` - specifies configuration for converting the parameters to string
    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.