Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.objectstyle.cayenne.query
Class ProcedureQuery

    java.lang.Object
      org.objectstyle.cayenne.query.AbstractQuery
          org.objectstyle.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.objectstyle.cayenne.query.AbstractQuery
`name, root`

Fields inherited from interface org.objectstyle.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.objectstyle.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.objectstyle.cayenne.query.Query
`getName, getRoot, route, setName, setRoot`

Methods inherited from interface org.objectstyle.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

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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