SQLExec (cayenne-doc: Cayenne Documentation 5.0-M2 API)
Description: declaration: package: org.apache.cayenne.query, class: SQLExec

# Class SQLExec

java.lang.Object
org.apache.cayenne.query.IndirectQuery
org.apache.cayenne.query.SQLExec

All Implemented Interfaces:
  `Serializable, Query`

public class SQLExec extends IndirectQuery
A generic query based on raw SQL and featuring fluent API. While `SQLExec` can be used to select data (see `execute(ObjectContext)` ), it is normally used for updates, DDL operations, etc.

Since:
  4.0
See Also:
  - Serialized Form

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected String`
  `dataMapName`
  `protected Map<String,Object>`
  `params`
  `protected List<Object>`
  `positionalParams`
  `protected int`
  `queryTimeout`
  `protected boolean`
  `returnGeneratedKeys`
  `protected StringBuilder`
  `sqlBuffer`

  ### Fields inherited from class IndirectQuery

  `dataMap, lastResolver, name, replacementQuery`
  Modifier and Type
  Field
  Description
  `protected DataMap`
  `dataMap`
  `protected EntityResolver`
  `lastResolver`
  `protected String`
  `name`
  `protected Query`
  `replacementQuery`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `SQLExec(String sql)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `SQLExec`
  `append(String sqlChunk)`
  Appends a piece of SQL to the previously stored SQL template.
  `protected Query`
  `createReplacementQuery(EntityResolver resolver)`
  Creates a substitute query.
  `QueryResult`
  `execute(ObjectContext context)`
  `Map<String,Object>`
  `getParams()`
  Returns a potentially immutable map of named parameters that will be bound to SQL.
  `List<Object>`
  `getPositionalParams()`
  Returns a potentially immutable list of positional parameters that will be bound to SQL.
  `String`
  `getSql()`
  `boolean`
  `isReturnGeneratedKeys()`
  `SQLExec`
  `params(String name, Object value)`
  `SQLExec`
  `params(Map<String,?> parameters)`
  `SQLExec`
  `paramsArray(Object... params)`
  Initializes positional parameters of the query.
  `SQLExec`
  `paramsList(List<Object> params)`
  Initializes positional parameters of the query.
  `static SQLExec`
  `query(String sql)`
  Creates a query executing provided SQL run against default database.
  `static SQLExec`
  `query(String dataMapName, String sql)`
  Creates a query executing provided SQL that performs routing based on the provided DataMap name.
  `SQLExec`
  `queryTimeout(int queryTimeout)`
  `SQLExec`
  `returnGeneratedKeys(boolean returnGeneratedKeys)`
  Flag indicating that generated keys should be returned by this query execution.
  `int`
  `update(ObjectContext context)`
  `int[]`
  `updateBatch(ObjectContext context)`

  ### Methods inherited from class IndirectQuery

  `createSQLAction, getMetaData, getReplacementQuery, route`
  Modifier and Type
  Method
  Description
  `SQLAction`
  `createSQLAction(SQLActionVisitor visitor)`
  Throws an exception as indirect query should not be executed directly.
  `QueryMetadata`
  `getMetaData(EntityResolver resolver)`
  Returns the metadata obtained from the replacement query.
  `protected Query`
  `getReplacementQuery(EntityResolver resolver)`
  Returns a replacement query, creating it on demand and caching it for reuse.
  `void`
  `route(QueryRouter router, EntityResolver resolver, Query substitutedQuery)`
  Delegates routing to a replacement query.

  ### Methods inherited from class Object

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

- ## Field Details

  - ### dataMapName

    protected String dataMapName

  - ### sqlBuffer

    protected StringBuilder sqlBuffer

  - ### params

    protected Map<String,Object> params

  - ### positionalParams

    protected List<Object> positionalParams

  - ### returnGeneratedKeys

    protected boolean returnGeneratedKeys

  - ### queryTimeout

    protected int queryTimeout

- ## Constructor Details

  - ### SQLExec

    public SQLExec(String sql)

- ## Method Details

  - ### query

    public static SQLExec query(String sql)
    Creates a query executing provided SQL run against default database.

  - ### query

    public static SQLExec query(String dataMapName, String sql)
    Creates a query executing provided SQL that performs routing based on the provided DataMap name.

  - ### getSql

    public String getSql()

  - ### append

    public SQLExec append(String sqlChunk)
    Appends a piece of SQL to the previously stored SQL template.

  - ### params

    public SQLExec params(String name, Object value)

  - ### params

    public SQLExec params(Map<String,?> parameters)

  - ### paramsArray

    public SQLExec paramsArray(Object... params)
    Initializes positional parameters of the query. Parameters are bound in the order they are found in the SQL template. If a given parameter name is used more than once, only the first occurrence is treated as "position", subsequent occurrences are bound with the same value as the first one. If template parameters count is different from the array parameter count, an exception will be thrown.

    Note that calling this method will reset any previously set *named* parameters.

  - ### paramsList

    public SQLExec paramsList(List<Object> params)
    Initializes positional parameters of the query. Parameters are bound in the order they are found in the SQL template. If a given parameter name is used more than once, only the first occurrence is treated as "position", subsequent occurrences are bound with the same value as the first one. If template parameters count is different from the list parameter count, an exception will be thrown.

    Note that calling this method will reset any previously set *named* parameters.

  - ### getParams

    public Map<String,Object> getParams()
    Returns a potentially immutable map of named parameters that will be bound to SQL.

  - ### getPositionalParams

    public List<Object> getPositionalParams()
    Returns a potentially immutable list of positional parameters that will be bound to SQL.

  - ### execute

    public QueryResult execute(ObjectContext context)

  - ### update

    public int update(ObjectContext context)

  - ### updateBatch

    public int[] updateBatch(ObjectContext context)

  - ### isReturnGeneratedKeys

    public boolean isReturnGeneratedKeys()
    Returns:
      returnGeneratedKeys flag value
    Since:
      4.1

  - ### returnGeneratedKeys

    public SQLExec returnGeneratedKeys(boolean returnGeneratedKeys)
    Flag indicating that generated keys should be returned by this query execution. Generated keys could be read via `QueryResponse.currentList()` method
    Parameters:
      `returnGeneratedKeys` - flag value
    Since:
      4.1
    See Also:
      - `Statement.RETURN_GENERATED_KEYS`

  - ### queryTimeout

    public SQLExec queryTimeout(int queryTimeout)
    Since:
      4.2

  - ### createReplacementQuery

    protected Query createReplacementQuery(EntityResolver resolver)
    Description copied from class: `IndirectQuery`
    Creates a substitute query. An implementor is free to provide an arbitrary replacement query.
    Specified by:
      `createReplacementQuery` in class `IndirectQuery`