Package oracle.nosql.driver.ops

# Class PreparedStatement

java.lang.Object
oracle.nosql.driver.ops.PreparedStatement

public class PreparedStatement extends Object
A class encapsulating a prepared query statement. It includes state that can be sent to a server and executed without re-parsing the query. It includes bind variables which may be set for each successive use of the query. The prepared query itself is read-only but this object contains a mutable map of bind variables and is not thread-safe if variables are used.

A single instance of PreparedStatement is thread-safe if bind variables are not used. If bind variables are to be used and the statement shared among threads additional instances of PreparedStatement can be constructed using `copyStatement()`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `clearVariables()`
  Clears all bind variables from the statement.
  `PreparedStatement`
  `copyStatement()`
  Returns a new instance that shares this object's prepared query, which is immutable, but does not share its variables.
  `String`
  `getQueryPlan()`
  Returns a string representation of the query execution plan, if it was requested in the `PrepareRequest`; null otherwise.
  `String`
  `getQuerySchema()`
  Returns a string (JSON) representation of the schema of the query result for this query, if it was requested in the `PrepareRequest`; null otherwise.
  `String`
  `getSQLText()`
  Returns the SQL text of this PreparedStatement.
  `Map<String,FieldValue>`
  `getVariables()`
  Returns the map of variables to use for a prepared query with variables.
  `PreparedStatement`
  `setVariable(int pos, FieldValue value)`
  Binds an external variable to a given value.
  `PreparedStatement`
  `setVariable(String name, FieldValue value)`
  Binds an external variable to a given value.

  ### Methods inherited from class java.lang.Object

  `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Method Details

  - ### copyStatement

    public PreparedStatement copyStatement()
    Returns a new instance that shares this object's prepared query, which is immutable, but does not share its variables.
    Returns:
      a new PreparedStatement using this instance's prepared query. Bind variables are uninitialized.

  - ### getSQLText

    public String getSQLText()
    Returns the SQL text of this PreparedStatement.
    Returns:
      the SQL text of this PreparedStatement.

  - ### getQueryPlan

    public String getQueryPlan()
    Returns a string representation of the query execution plan, if it was requested in the `PrepareRequest`; null otherwise.
    Returns:
      the string representation of the query execution plan

  - ### getQuerySchema

    public String getQuerySchema()
    Returns a string (JSON) representation of the schema of the query result for this query, if it was requested in the `PrepareRequest`; null otherwise.
    Returns:
      the string representation of the query schema
    Since:
      5.4

  - ### getVariables

    public Map<String,FieldValue> getVariables()
    Returns the map of variables to use for a prepared query with variables.
    Returns:
      the map, or null if there are no variables set.

  - ### clearVariables

    public void clearVariables()
    Clears all bind variables from the statement.

  - ### setVariable

    public PreparedStatement setVariable(String name, FieldValue value)
    Binds an external variable to a given value. The variable is identified by its name.
    Parameters:
      `name` - the name of the variable
      `value` - the value
    Returns:
      this

  - ### setVariable

    public PreparedStatement setVariable(int pos, FieldValue value)
    Binds an external variable to a given value. The variable is identified by its position within the query string. The variable that appears first in the query text has position 1, the variable that appears second has position 2 and so on.
    Parameters:
      `pos` - the position of the variable
      `value` - the value
    Returns:
      this