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:
java.io.Serializable, GenericSelectQuery, ParameterizedQuery, Query, XMLSerializable

public class ProcedureQuery
extends AbstractQuery
implements GenericSelectQuery, 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).

Author:
Andrus Adamchik
See Also:
Serialized Form

Field Summary
protected  java.util.Map parameters
           
protected  java.lang.Class resultClass
           
protected  java.lang.String resultClassName
          Deprecated. since 1.2 'resultEntityName' must be used.
protected  java.util.List resultDescriptors
           
protected  java.lang.String resultEntityName
           
protected  boolean selecting
          Deprecated. since 1.2 as this information is no longer relavant to Cayenne
 
Fields inherited from class org.apache.cayenne.query.AbstractQuery
name, root
 
Fields inherited from interface org.apache.cayenne.query.GenericSelectQuery
CACHE_POLICY_DEFAULT, CACHE_POLICY_PROPERTY, FETCH_LIMIT_DEFAULT, FETCH_LIMIT_PROPERTY, FETCHING_DATA_ROWS_DEFAULT, FETCHING_DATA_ROWS_PROPERTY, LOCAL_CACHE, NO_CACHE, PAGE_SIZE_DEFAULT, PAGE_SIZE_PROPERTY, REFRESHING_OBJECTS_DEFAULT, REFRESHING_OBJECTS_PROPERTY, RESOLVING_INHERITED_DEFAULT, RESOLVING_INHERITED_PROPERTY, SHARED_CACHE
 
Constructor Summary
ProcedureQuery()
          Creates an empty procedure query.
ProcedureQuery(Procedure procedure)
          Creates a ProcedureQuery based on a Procedure object.
ProcedureQuery(Procedure procedure, java.lang.Class resultType)
           
ProcedureQuery(java.lang.String procedureName)
          Creates a ProcedureQuery based on a stored procedure.
ProcedureQuery(java.lang.String procedureName, java.lang.Class resultType)
           Performance Note: with current EntityResolver implementation it is preferrable to use Procedure object instead of String as a query root.
 
Method Summary
 void addParameter(java.lang.String name, java.lang.Object value)
          Adds a named parameter to the internal map of parameters.
 PrefetchTreeNode addPrefetch(java.lang.String prefetchPath)
          Adds a prefetch.
 void addPrefetches(java.util.Collection 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(java.util.Map 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.
 java.lang.String getCachePolicy()
          Returns query cache policy, which can be one of GenericSelectQuery.NO_CACHE, GenericSelectQuery.LOCAL_CACHE, or GenericSelectQuery.SHARED_CACHE.
 int getFetchLimit()
          Returns the limit on the maximium number of records that can be returned by this query.
 QueryMetadata getMetaData(EntityResolver resolver)
          Returns default select parameters.
 int getPageSize()
          Returns query page size.
 java.util.Map getParameters()
          Returns a map of procedure parameters.
 PrefetchTreeNode getPrefetchTree()
          Returns a root node of prefetch tree used by this query, or null of no prefetches are configured.
 java.lang.Class getResultClass(java.lang.ClassLoader classLoader)
          Deprecated. since 1.2
 java.lang.String getResultClassName()
          Deprecated. since 1.2 use getResultEntityName()
 java.util.List getResultDescriptors()
          Returns a List of #RowDescriptor objects describing query ResultSets in the order they are returned by the stored procedure.
 java.lang.String getResultEntityName()
           
 void initWithProperties(java.util.Map properties)
          Initializes query parameters using a set of properties.
 boolean isFetchingDataRows()
          Returns true if this query should produce a list of data rows as opposed to DataObjects, false for DataObjects.
 boolean isRefreshingObjects()
          Returns true if the query results should replace any currently cached values, returns false otherwise.
 boolean isResolvingInherited()
          Returns true if objects fetched via this query should be fully resolved according to the inheritance hierarchy.
 boolean isSelecting()
          Deprecated. since 1.2 as this information is no longer relavant to Cayenne
 void removeParameter(java.lang.String name)
           
 void removePrefetch(java.lang.String prefetch)
           
 void removeResultDescriptor(ColumnDescriptor[] descriptor)
          Removes result descriptor from the list of descriptors.
 void setCachePolicy(java.lang.String policy)
           
 void setFetchingDataRows(boolean flag)
           
 void setFetchLimit(int fetchLimit)
           
 void setPageSize(int pageSize)
           
 void setParameters(java.util.Map parameters)
          Sets a map of parameters.
 void setRefreshingObjects(boolean flag)
           
 void setResolvingInherited(boolean b)
           
 void setResultClassName(java.lang.String resultClassName)
          Deprecated. since 1.2 use setResultEntityName(String)
 void setResultEntityName(java.lang.String resultEntityName)
           
 void setSelecting(boolean b)
          Deprecated. since 1.2 as this information is no longer relavant to Cayenne
 
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, getRoot, route, setName, setRoot
 
Methods inherited from interface org.apache.cayenne.query.Query
getName, getRoot, route, setName, setRoot
 

Field Detail

resultClassName

protected java.lang.String resultClassName
Deprecated. since 1.2 'resultEntityName' must be used.
If set, allows to fetch results as DataObjects.

Since:
1.1

resultEntityName

protected java.lang.String resultEntityName
Since:
1.2

resultClass

protected java.lang.Class resultClass
Since:
1.2

parameters

protected java.util.Map parameters

selecting

protected boolean selecting
Deprecated. since 1.2 as this information is no longer relavant to Cayenne

resultDescriptors

protected java.util.List resultDescriptors
Since:
1.2
Constructor Detail

ProcedureQuery

public ProcedureQuery()
Creates an empty procedure query.


ProcedureQuery

public ProcedureQuery(Procedure procedure)
Creates a ProcedureQuery based on a Procedure object.


ProcedureQuery

public ProcedureQuery(java.lang.String procedureName)
Creates a ProcedureQuery based on a stored procedure.

Performance Note: with current EntityResolver implementation it is preferrable to use Procedure object instead of String as a query root. String root can cause unneeded EntityResolver reindexing on every call. See this mailing list thread: http://objectstyle.org/cayenne/lists/cayenne-user/2005/01/0109.html

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,
                      java.lang.Class resultType)
Since:
1.1

ProcedureQuery

public ProcedureQuery(java.lang.String procedureName,
                      java.lang.Class resultType)

Performance Note: with current EntityResolver implementation it is preferrable to use Procedure object instead of String as a query root. String root can cause unneeded EntityResolver reindexing on every call. See this mailing list thread: http://objectstyle.org/cayenne/lists/cayenne-user/2005/01/0109.html

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 java.util.List getResultDescriptors()
Returns a List of #RowDescriptor objects describing 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(java.util.Map 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(java.util.Map 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

public java.lang.String getCachePolicy()
Description copied from interface: GenericSelectQuery
Returns query cache policy, which can be one of GenericSelectQuery.NO_CACHE, GenericSelectQuery.LOCAL_CACHE, or GenericSelectQuery.SHARED_CACHE. NO_CACHE is generally a default policy.

Specified by:
getCachePolicy in interface GenericSelectQuery

setCachePolicy

public void setCachePolicy(java.lang.String policy)

getFetchLimit

public int getFetchLimit()
Description copied from interface: GenericSelectQuery
Returns the limit on the maximium number of records that can be returned by this query. If the actual number of rows in the result exceeds the fetch limit, they will be discarded. One possible use of fetch limit is using it as a safeguard against large result sets that may lead to the application running out of memory, etc. If a fetch limit is greater or equal to zero, all rows will be returned.

Specified by:
getFetchLimit in interface GenericSelectQuery
Returns:
the limit on the maximium number of records that can be returned by this query

setFetchLimit

public void setFetchLimit(int fetchLimit)

getPageSize

public int getPageSize()
Description copied from interface: GenericSelectQuery
Returns query page size. Page size is a hint to Cayenne that query should be performed page by page, instead of retrieveing all results at once. If the value returned is less than or equal to zero, no paging should occur.

Specified by:
getPageSize in interface GenericSelectQuery

setPageSize

public void setPageSize(int pageSize)

setFetchingDataRows

public void setFetchingDataRows(boolean flag)

isFetchingDataRows

public boolean isFetchingDataRows()
Description copied from interface: GenericSelectQuery
Returns true if this query should produce a list of data rows as opposed to DataObjects, false for DataObjects. This is a hint to QueryEngine executing this query.

Specified by:
isFetchingDataRows in interface GenericSelectQuery

isRefreshingObjects

public boolean isRefreshingObjects()
Description copied from interface: GenericSelectQuery
Returns true if the query results should replace any currently cached values, returns false otherwise. If GenericSelectQuery.isFetchingDataRows()returns true, this setting is not applicable and has no effect.

Specified by:
isRefreshingObjects in interface GenericSelectQuery

setRefreshingObjects

public void setRefreshingObjects(boolean flag)

isResolvingInherited

public boolean isResolvingInherited()
Description copied from interface: GenericSelectQuery
Returns true if objects fetched via this query should be fully resolved according to the inheritance hierarchy.

Specified by:
isResolvingInherited in interface GenericSelectQuery

setResolvingInherited

public void setResolvingInherited(boolean b)

addParameter

public void addParameter(java.lang.String name,
                         java.lang.Object value)
Adds a named parameter to the internal map of parameters.

Since:
1.1

removeParameter

public void removeParameter(java.lang.String name)
Since:
1.1

getParameters

public java.util.Map getParameters()
Returns a map of procedure parameters.

Since:
1.1

setParameters

public void setParameters(java.util.Map parameters)
Sets a map of parameters.

Since:
1.1

clearParameters

public void clearParameters()
Cleans up all configured parameters.

Since:
1.1

getResultClassName

public java.lang.String getResultClassName()
Deprecated. since 1.2 use getResultEntityName()

Returns an optional result type of the query.

Since:
1.1

getResultClass

public java.lang.Class getResultClass(java.lang.ClassLoader classLoader)
Deprecated. since 1.2

Returns Java class of the DataObjects returned by this query.

Since:
1.1

setResultClassName

public void setResultClassName(java.lang.String resultClassName)
Deprecated. since 1.2 use setResultEntityName(String)

Sets optional result type of the query. A Class of the result type must be a DataObject implementation mapped in Cayenne.

Since:
1.1

isSelecting

public boolean isSelecting()
Deprecated. since 1.2 as this information is no longer relavant to Cayenne

Returns true if ProcedureQuery is expected to return a ResultSet.

Since:
1.1

setSelecting

public void setSelecting(boolean b)
Deprecated. since 1.2 as this information is no longer relavant to Cayenne

Sets whether ProcedureQuery is expected to return a ResultSet.

Since:
1.1

getPrefetchTree

public PrefetchTreeNode getPrefetchTree()
Description copied from interface: GenericSelectQuery
Returns a root node of prefetch tree used by this query, or null of no prefetches are configured.

Specified by:
getPrefetchTree in interface GenericSelectQuery
Since:
1.2

addPrefetch

public PrefetchTreeNode addPrefetch(java.lang.String prefetchPath)
Adds a prefetch.

Since:
1.2

removePrefetch

public void removePrefetch(java.lang.String prefetch)
Since:
1.2

addPrefetches

public void addPrefetches(java.util.Collection prefetches)
Adds all prefetches from a provided collection.

Since:
1.2

clearPrefetches

public void clearPrefetches()
Clears all prefetches.

Since:
1.2

getResultEntityName

public java.lang.String getResultEntityName()
Since:
1.2

setResultEntityName

public void setResultEntityName(java.lang.String resultEntityName)
Since:
1.2


Copyright © 2001-2006 Apache.org All Rights Reserved.