org.apache.cayenne.query

Class ProcedureQuery

java.lang.Object

org.apache.cayenne.query.AbstractQuery

org.apache.cayenne.query.ProcedureQuery

All Implemented Interfaces:

Serializable, ConfigurationNode, 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

Fields

Modifier and Type	Field and Description
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

dataMap, name, root

Constructor Summary

Constructors

Constructor and Description
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

Methods

Modifier and Type	Method and 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.
void	encodeAsXML(XMLEncoder encoder) Prints itself as XML to the provided PrintWriter.
String[]	getCacheGroups()
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()
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	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	setResultEntityName(String resultEntityName)
void	setStatementFetchSize(int size) Sets statement's fetch size (0 for no default size)
void	useLocalCache(String... cacheGroups) Instructs Cayenne to look for query results in the "local" cache when running the query.
void	useSharedCache(String... cacheGroups) Instructs Cayenne to look for query results in the "shared" cache when running the query.

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

acceptVisitor, getDataMap, getName, getRoot, route, setDataMap, 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

getDataMap, getName, route

Methods inherited from interface org.apache.cayenne.configuration.ConfigurationNode

acceptVisitor

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

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

useLocalCache

public void useLocalCache(String... cacheGroups)

Instructs Cayenne to look for query results in the "local" cache when running the query. This is a short-hand notation for:

 query.setCacheStrategy(QueryCacheStrategy.LOCAL_CACHE);
 query.setCacheGroups("group1", "group2");
 

Since:

4.0

useSharedCache

public void useSharedCache(String... cacheGroups)

Instructs Cayenne to look for query results in the "shared" cache when running the query. This is a short-hand notation for:

 query.setCacheStrategy(QueryCacheStrategy.SHARED_CACHE);
 query.setCacheGroups("group1", "group2");
 

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