org.apache.cayenne.query
Class ProcedureQuery

java.lang.Object
  extended by org.apache.cayenne.query.AbstractQuery
      extended by org.apache.cayenne.query.ProcedureQuery
All Implemented Interfaces:
Serializable, ParameterizedQuery, Query, XMLSerializable

public class ProcedureQuery
extends AbstractQuery
implements ParameterizedQuery, XMLSerializable

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
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
name, root
 
Constructor Summary
ProcedureQuery()
          Creates an empty procedure query.
ProcedureQuery(Procedure procedure)
          Creates a ProcedureQuery based on a Procedure object.
ProcedureQuery(Procedure procedure, Class<?> resultType)
           
ProcedureQuery(String procedureName)
          Creates a ProcedureQuery based on a stored procedure.
ProcedureQuery(String procedureName, Class<?> resultType)
           
 
Method Summary
 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.
 void encodeAsXML(XMLEncoder encoder)
          Prints itself as XML to the provided PrintWriter.
 String[] getCacheGroups()
           
 String getCachePolicy()
          Deprecated. since 3.0 getCacheStrategy() replaces this method.
 QueryCacheStrategy getCacheStrategy()
           
 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()
           
 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()
           
 boolean isRefreshingObjects()
          Deprecated. since 3.0. With introduction of the cache strategies this setting is redundant, although it is still being taken into account. It will be removed in the later versions of Cayenne.
 boolean isResolvingInherited()
          Deprecated. since 3.0. Inheritance resolving is not optional anymore.
 void removeParameter(String name)
           
 void removePrefetch(String prefetch)
           
 void removeResultDescriptor(ColumnDescriptor[] descriptor)
          Removes result descriptor from the list of descriptors.
 void setCacheGroups(String... cacheGroups)
           
 void setCachePolicy(String policy)
          Deprecated. since 3.0 setCacheStrategy(QueryCacheStrategy) replaces this method.
 void setCacheStrategy(QueryCacheStrategy strategy)
           
 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 setRefreshingObjects(boolean flag)
          Deprecated. since 3.0. With introduction of the cache strategies this setting is redundant, although it is still being taken into account. It will be removed in the later versions of Cayenne.
 void setResolvingInherited(boolean b)
          Deprecated. since 3.0. Inheritance resolving is not optional anymore.
 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
getName, getRoot, route, setName, setRoot, toString
 
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
getName, route
 

Field Detail

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

encodeAsXML

public void encodeAsXML(XMLEncoder encoder)
Prints itself as XML to the provided PrintWriter.

Specified by:
encodeAsXML in interface XMLSerializable
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

getCachePolicy

@Deprecated
public String getCachePolicy()
Deprecated. since 3.0 getCacheStrategy() replaces this method.


setCachePolicy

@Deprecated
public void setCachePolicy(String policy)
Deprecated. since 3.0 setCacheStrategy(QueryCacheStrategy) replaces this method.


getCacheStrategy

public QueryCacheStrategy getCacheStrategy()
Since:
3.0

setCacheStrategy

public void setCacheStrategy(QueryCacheStrategy strategy)
Since:
3.0

getCacheGroups

public String[] getCacheGroups()
Since:
3.0

setCacheGroups

public void setCacheGroups(String... cacheGroups)
Since:
3.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()

isRefreshingObjects

@Deprecated
public boolean isRefreshingObjects()
Deprecated. since 3.0. With introduction of the cache strategies this setting is redundant, although it is still being taken into account. It will be removed in the later versions of Cayenne.


setRefreshingObjects

@Deprecated
public void setRefreshingObjects(boolean flag)
Deprecated. since 3.0. With introduction of the cache strategies this setting is redundant, although it is still being taken into account. It will be removed in the later versions of Cayenne.


isResolvingInherited

@Deprecated
public boolean isResolvingInherited()
Deprecated. since 3.0. Inheritance resolving is not optional anymore.


setResolvingInherited

@Deprecated
public void setResolvingInherited(boolean b)
Deprecated. since 3.0. Inheritance resolving is not optional anymore.


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


Copyright © 2001-2011 Apache Cayenne. All Rights Reserved.