Class ProcedureQuery<T>

java.lang.Object
org.apache.cayenne.query.ProcedureQuery<T>
Type Parameters:
T - the type of the result elements: a DataRow by default, or a persistent object when a result type is specified.
All Implemented Interfaces:
Query, Select<T>
public class ProcedureQuery<T> extends Object implements Select<T>
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, their values are reported as a separate item of the query response, a Map keyed by parameter name (see OutParametersResult).

Using ProcedureQuery as a Select

Executing ProcedureQuery via ObjectContext.select(Select) 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: ObjectContext.execute(Query).

  • Field Details

    • resultEntityName

      protected String resultEntityName

    • resultClass

      protected Class<?> resultClass

    • columnNamesCapitalization

      protected CapsStrategy columnNamesCapitalization

    • parameters

      protected Map<String,Object> parameters

    • resultDescriptors

      protected List<ProcedureColumn[]> resultDescriptors

    • root

      protected Object root
      The root object of this query. May be an entity name, Java class, ObjEntity or DbEntity, depending on the specific query and how it was constructed.

  • Constructor Details

  • Method Details

    • getRoot

      public Object getRoot()
      Returns the root of this query.

    • setRoot

      public void setRoot(Object value)
      Sets the root of the query.
      Parameters:
      value - The new root
      Throws:
      IllegalArgumentException - if value is not a String, ObjEntity, DbEntity, Procedure, DataMap, Class or null.

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • getMetaData

      public QueryMetadata getMetaData(EntityResolver resolver)
      Description copied from interface: Query
      Returns query runtime parameters. The method is called at various stages of the execution by Cayenne access stack to retrieve query parameters. EntityResolver instance is passed to this method, meaning that the query doesn't need to store direct references to Cayenne mapping objects and can resolve them at runtime.
      Specified by:
      getMetaData in interface Query
      Since:
      1.2

    • getResultDescriptors

      public List<ProcedureColumn[]> 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:
      5.0

    • addResultDescriptor

      public void addResultDescriptor(ProcedureColumn[] 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:
      5.0

    • removeResultDescriptor

      public void removeResultDescriptor(ProcedureColumn[] descriptor)
      Removes result descriptor from the list of descriptors.
      Since:
      5.0

    • createSQLAction

      public SQLAction createSQLAction(SQLActionVisitor visitor)
      Calls "makeProcedure" on the visitor.
      Specified by:
      createSQLAction in interface Query
      Since:
      1.2

    • selectFirst

      public T selectFirst(ObjectContext context)
      Description copied from interface: Select
      Selects a single object using provided context. The query itself can match any number of objects, but will return only the first one. It returns null if no objects were matched.

      If it matched more than one object, the first object from the list is returned. This makes 'selectFirst' different from Select.selectOne(ObjectContext), which would throw in this situation. 'selectFirst' is useful e.g. when the query is ordered and we only want to see the first object (e.g. "most recent news article"), etc.

      Selecting the first object via "Select.selectFirst(ObjectContext)" is more comprehensible than selecting via "ObjectContext.selectFirst(Select)", because implementations of "Select" set fetch size limit to one.

      Specified by:
      selectFirst in interface Select<T>
      Since:
      5.0

    • getCacheStrategy

      public QueryCacheStrategy getCacheStrategy()
      Since:
      3.0

    • setCacheStrategy

      public void setCacheStrategy(QueryCacheStrategy strategy)
      Since:
      3.0

    • getCacheGroup

      public String getCacheGroup()
      Since:
      4.0

    • setCacheGroup

      public void setCacheGroup(String cacheGroup)
      Since:
      4.0

    • useLocalCache

      @Deprecated(since="5.0", forRemoval=true) public void useLocalCache()
      Deprecated, for removal: This API element is subject to removal in a future version.
      use setCacheStrategy(QueryCacheStrategy) with QueryCacheStrategy.LOCAL_CACHE
      Since:
      4.0

    • useLocalCache

      @Deprecated(since="5.0", forRemoval=true) public void useLocalCache(String cacheGroup)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use setCacheStrategy(QueryCacheStrategy) with QueryCacheStrategy.LOCAL_CACHE and setCacheGroup(String)
      Since:
      4.0

    • useSharedCache

      @Deprecated(since="5.0", forRemoval=true) public void useSharedCache()
      Deprecated, for removal: This API element is subject to removal in a future version.
      use setCacheStrategy(QueryCacheStrategy) with QueryCacheStrategy.SHARED_CACHE
      Since:
      4.0

    • useSharedCache

      @Deprecated(since="5.0", forRemoval=true) public void useSharedCache(String cacheGroup)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use setCacheStrategy(QueryCacheStrategy) with QueryCacheStrategy.SHARED_CACHE and setCacheGroup(String)
      Since:
      4.0

    • 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