Package org.apache.cayenne.query

## Class ProcedureQuery

- java.lang.Object
- - org.apache.cayenne.query.CacheableQuery
  - - org.apache.cayenne.query.AbstractQuery
    - - org.apache.cayenne.query.ProcedureQuery

- All Implemented Interfaces:
    `Serializable`, `ParameterizedQuery`, `Query`

      public class ProcedureQuery
      extends AbstractQuery
      implements ParameterizedQuery

  A query based on Procedure. Can be used as a select query, or as a query of an arbitrary complexity, performing data modification, selecting data (possibly with multiple result sets per call), returning values via OUT parameters.

  ### Execution with DataContext

  #### Reading OUT parameters

  If a ProcedureQuery has OUT parameters, they are wrapped in a separate List in the query result. Such list will contain a single Map with OUT parameter values.

  #### Using ProcedureQuery as a GenericSelectQuery

  Executing ProcedureQuery via `DataContext.performQuery(Query)` makes sense only if the stored procedure returns a single result set (or alternatively returns a result via OUT parameters and no other result sets). It is still OK if data modification occurs as a side effect. However if the query returns more then one result set, a more generic form should be used: `DataContext.performGenericQuery(Query)`.

  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static String` | `COLUMN_NAME_CAPITALIZATION_PROPERTY` |
    `protected CapsStrategy` | `columnNamesCapitalization` |
    `protected Map<String,​Object>` | `parameters` |
    `protected Class<?>` | `resultClass` |
    `protected List<ColumnDescriptor[]>` | `resultDescriptors` |
    `protected String` | `resultEntityName` |

    - ### Fields inherited from class org.apache.cayenne.query.AbstractQuery

      `root`

    - ### Fields inherited from class org.apache.cayenne.query.CacheableQuery

      `logger`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `ProcedureQuery()` | Creates an empty procedure query.
    `ProcedureQuery​(String procedureName)` | Creates a ProcedureQuery based on a stored procedure.
    `ProcedureQuery​(String procedureName, Class<?> resultType)` |
    `ProcedureQuery​(Procedure procedure)` | Creates a ProcedureQuery based on a Procedure object.
    `ProcedureQuery​(Procedure procedure, Class<?> resultType)` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addParameter​(String name, Object value)` | Adds a named parameter to the internal map of parameters.
    `PrefetchTreeNode` | `addPrefetch​(String prefetchPath)` | Adds a prefetch.
    `void` | `addPrefetches​(Collection<String> prefetches)` | Adds all prefetches from a provided collection.
    `void` | `addResultDescriptor​(ColumnDescriptor[] descriptor)` | Adds a descriptor for a single ResultSet.
    `void` | `clearParameters()` | Cleans up all configured parameters.
    `void` | `clearPrefetches()` | Clears all prefetches.
    `Query` | `createQuery​(Map<String,​?> parameters)` | Creates and returns a new ProcedureQuery built using this query as a prototype and substituting template parameters with the values from the map.
    `SQLAction` | `createSQLAction​(SQLActionVisitor visitor)` | Calls "makeProcedure" on the visitor.
    `protected org.apache.cayenne.query.BaseQueryMetadata` | `getBaseMetaData()` |
    `CapsStrategy` | `getColumnNamesCapitalization()` |
    `int` | `getFetchLimit()` |
    `int` | `getFetchOffset()` |
    `QueryMetadata` | `getMetaData​(EntityResolver resolver)` | Returns default select parameters.
    `int` | `getPageSize()` |
    `Map<String,​?>` | `getParameters()` | Returns a map of procedure parameters.
    `PrefetchTreeNode` | `getPrefetchTree()` |
    `int` | `getQueryTimeout()` |
    `List<ColumnDescriptor[]>` | `getResultDescriptors()` | Returns a List of descriptors for query ResultSets in the order they are returned by the stored procedure.
    `String` | `getResultEntityName()` |
    `int` | `getStatementFetchSize()` |
    `void` | `initWithProperties​(Map<String,​?> properties)` | Initializes query parameters using a set of properties.
    `boolean` | `isFetchingDataRows()` |
    `void` | `removeParameter​(String name)` |
    `void` | `removePrefetch​(String prefetch)` |
    `void` | `removeResultDescriptor​(ColumnDescriptor[] descriptor)` | Removes result descriptor from the list of descriptors.
    `void` | `setColumnNamesCapitalization​(CapsStrategy columnNameCapitalization)` |
    `void` | `setFetchingDataRows​(boolean flag)` |
    `void` | `setFetchLimit​(int fetchLimit)` |
    `void` | `setFetchOffset​(int fetchOffset)` |
    `void` | `setPageSize​(int pageSize)` |
    `void` | `setParameters​(Map<String,​?> parameters)` | Sets a map of parameters.
    `void` | `setQueryTimeout​(int timeout)` | Set's query timeout
    `void` | `setResultEntityName​(String resultEntityName)` |
    `void` | `setStatementFetchSize​(int size)` | Sets statement's fetch size (0 for no default size)

    - ### Methods inherited from class org.apache.cayenne.query.AbstractQuery

      `getRoot, route, setRoot, toString`

    - ### Methods inherited from class org.apache.cayenne.query.CacheableQuery

      `getCacheGroup, getCacheStrategy, setCacheGroup, setCacheStrategy, useLocalCache, useLocalCache, useSharedCache, useSharedCache`

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

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

    - ### Methods inherited from interface org.apache.cayenne.query.Query

      `route`

- - ### Field Detail

    - #### COLUMN_NAME_CAPITALIZATION_PROPERTY

          public static final String COLUMN_NAME_CAPITALIZATION_PROPERTY

      See Also:
        Constant Field Values

    - #### resultEntityName

          protected String resultEntityName

      Since:
        1.2

    - #### resultClass

          protected Class<?> resultClass

      Since:
        1.2

    - #### columnNamesCapitalization

          protected CapsStrategy columnNamesCapitalization

    - #### parameters

          protected Map<String,​Object> parameters

    - #### resultDescriptors

          protected List<ColumnDescriptor[]> resultDescriptors

      Since:
        1.2

  - ### Constructor Detail

    - #### ProcedureQuery

          public ProcedureQuery()

      Creates an empty procedure query. The query would fetch DataRows. Fetching Persistent objects can be achieved either by using `ProcedureQuery(String, Class)` constructor or by calling `setFetchingDataRows(boolean)` and `setResultEntityName(String)` methods.

    - #### ProcedureQuery

          public ProcedureQuery​(Procedure procedure)

      Creates a ProcedureQuery based on a Procedure object. The query would fetch DataRows. Fetching Persistent objects can be achieved either by using `ProcedureQuery(String, Class)` constructor or by calling `setFetchingDataRows(boolean)` and `setResultEntityName(String)` methods.

    - #### ProcedureQuery

          public ProcedureQuery​(String procedureName)

      Creates a ProcedureQuery based on a stored procedure. The query would fetch DataRows. Fetching Persistent objects can be achieved either by using `ProcedureQuery(String, Class)` constructor or by calling `setFetchingDataRows(boolean)` and `setResultEntityName(String)` methods.
      Parameters:
        `procedureName` - A name of the stored procedure. For this query to work, a procedure with this name must be mapped in Cayenne.

    - #### ProcedureQuery

          public ProcedureQuery​(Procedure procedure,
                                Class<?> resultType)

      Since:
        1.1

    - #### ProcedureQuery

          public ProcedureQuery​(String procedureName,
                                Class<?> resultType)

      Since:
        1.1

  - ### Method Detail

    - #### getMetaData

          public QueryMetadata getMetaData​(EntityResolver resolver)

      Description copied from class: `AbstractQuery`
      Returns default select parameters.
      Specified by:
        `getMetaData` in interface `Query`
      Overrides:
        `getMetaData` in class `AbstractQuery`
      Since:
        1.2

    - #### getResultDescriptors

          public List<ColumnDescriptor[]> getResultDescriptors()

      Returns a List of descriptors for query ResultSets in the order they are returned by the stored procedure.

      Note that if a procedure returns ResultSet in an OUT parameter, it is returned prior to any other result sets (though in practice database engines usually support only one mechanism for returning result sets.

      Since:
        1.2

    - #### addResultDescriptor

          public void addResultDescriptor​(ColumnDescriptor[] descriptor)

      Adds a descriptor for a single ResultSet. More than one descriptor can be added by calling this method multiple times in the order of described ResultSet appearance in the procedure results.
      Since:
        1.2

    - #### removeResultDescriptor

          public void removeResultDescriptor​(ColumnDescriptor[] descriptor)

      Removes result descriptor from the list of descriptors.
      Since:
        1.2

    - #### createSQLAction

          public SQLAction createSQLAction​(SQLActionVisitor visitor)

      Calls "makeProcedure" on the visitor.
      Specified by:
        `createSQLAction` in interface `Query`
      Specified by:
        `createSQLAction` in class `AbstractQuery`
      Since:
        1.2

    - #### initWithProperties

          public void initWithProperties​(Map<String,​?> properties)

      Initializes query parameters using a set of properties.
      Since:
        1.1

    - #### createQuery

          public Query createQuery​(Map<String,​?> parameters)

      Creates and returns a new ProcedureQuery built using this query as a prototype and substituting template parameters with the values from the map.
      Specified by:
        `createQuery` in interface `ParameterizedQuery`
      Since:
        1.1

    - #### getBaseMetaData

          protected org.apache.cayenne.query.BaseQueryMetadata getBaseMetaData()

      Specified by:
        `getBaseMetaData` in class `CacheableQuery`

    - #### getFetchLimit

          public int getFetchLimit()

    - #### setFetchLimit

          public void setFetchLimit​(int fetchLimit)

    - #### getFetchOffset

          public int getFetchOffset()

      Since:
        3.0

    - #### setFetchOffset

          public void setFetchOffset​(int fetchOffset)

      Since:
        3.0

    - #### getPageSize

          public int getPageSize()

    - #### setPageSize

          public void setPageSize​(int pageSize)

    - #### setFetchingDataRows

          public void setFetchingDataRows​(boolean flag)

    - #### isFetchingDataRows

          public boolean isFetchingDataRows()

    - #### addParameter

          public void addParameter​(String name,
                                   Object value)

      Adds a named parameter to the internal map of parameters.
      Since:
        1.1

    - #### removeParameter

          public void removeParameter​(String name)

      Since:
        1.1

    - #### getParameters

          public Map<String,​?> getParameters()

      Returns a map of procedure parameters.
      Since:
        1.1

    - #### setParameters

          public void setParameters​(Map<String,​?> parameters)

      Sets a map of parameters.
      Since:
        1.1

    - #### clearParameters

          public void clearParameters()

      Cleans up all configured parameters.
      Since:
        1.1

    - #### getPrefetchTree

          public PrefetchTreeNode getPrefetchTree()

      Since:
        1.2

    - #### addPrefetch

          public PrefetchTreeNode addPrefetch​(String prefetchPath)

      Adds a prefetch.
      Since:
        1.2

    - #### removePrefetch

          public void removePrefetch​(String prefetch)

      Since:
        1.2

    - #### addPrefetches

          public void addPrefetches​(Collection<String> prefetches)

      Adds all prefetches from a provided collection.
      Since:
        1.2

    - #### clearPrefetches

          public void clearPrefetches()

      Clears all prefetches.
      Since:
        1.2

    - #### getResultEntityName

          public String getResultEntityName()

      Since:
        1.2

    - #### setResultEntityName

          public void setResultEntityName​(String resultEntityName)

      Since:
        1.2

    - #### getColumnNamesCapitalization

          public CapsStrategy getColumnNamesCapitalization()

      Since:
        3.0

    - #### setColumnNamesCapitalization

          public void setColumnNamesCapitalization​(CapsStrategy columnNameCapitalization)

      Since:
        3.0

    - #### setStatementFetchSize

          public void setStatementFetchSize​(int size)

      Sets statement's fetch size (0 for no default size)
      Since:
        3.0

    - #### getStatementFetchSize

          public int getStatementFetchSize()

      Returns:
        statement's fetch size
      Since:
        3.0

    - #### getQueryTimeout

          public int getQueryTimeout()

      Returns:
        query timeout
      Since:
        4.2

    - #### setQueryTimeout

          public void setQueryTimeout​(int timeout)

      Set's query timeout
      Since:
        4.2