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

## org.apache.cayenne.query
Class ProcedureQuery

    java.lang.Object
      org.apache.cayenne.query.AbstractQuery
          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

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

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