Overview | Package | Class | 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 SQLTemplate

    java.lang.Object
      org.apache.cayenne.query.AbstractQuery
          org.apache.cayenne.query.SQLTemplate

All Implemented Interfaces:
  java.io.Serializable, GenericSelectQuery, ParameterizedQuery, Query, XMLSerializable

Direct Known Subclasses:
  EOSQLQuery

    public class SQLTemplate

extends AbstractQuery
implements GenericSelectQuery, ParameterizedQuery, XMLSerializable

A query that executes unchanged (except for template preprocessing) "raw" SQL specified by the user.

### Template Script

SQLTemplate stores a dynamic template for the SQL query that supports parameters and customization using Velocity scripting language. The most straightforward use of scripting abilities is to build parameterized queries. For example:

                   SELECT ID, NAME FROM SOME_TABLE WHERE NAME LIKE $a

For advanced scripting options see "Scripting SQLTemplate" chapter in the User Guide.

### Per-Database Template Customization

SQLTemplate has a `default template script`, but also it allows to configure multiple templates and switch them dynamically. This way a single query can have multiple "dialects" specific to a given database.

### Parameter Sets

SQLTemplate supports multiple sets of parameters, so a single query can be executed multiple times with different parameters. "Scrolling" through parameter list is done by calling `parametersIterator()`. This iterator goes over parameter sets, returning a Map on each call to "next()"

Since:
  1.1
Author:
  Andrus Adamchik
See Also:
  Serialized Form

Field Summary
`protected java.lang.String` | `defaultTemplate`
`protected java.util.Map[]` | `parameters`
`protected boolean` | `selecting` Deprecated. Since 1.2 this property is redundant.
`protected java.util.Map` | `templates`

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
`SQLTemplate()` Creates an empty SQLTemplate.
`SQLTemplate(boolean selecting)` Deprecated. Since 1.2 'selecting' property is redundant.
`SQLTemplate(java.lang.Class rootClass, java.lang.String defaultTemplate)`
`SQLTemplate(java.lang.Class rootClass, java.lang.String defaultTemplate, boolean selecting)` Deprecated. Since 1.2 'selecting' property is redundant.
`SQLTemplate(DataMap rootMap, java.lang.String defaultTemplate)`
`SQLTemplate(DataMap rootMap, java.lang.String defaultTemplate, boolean selecting)` Deprecated. Since 1.2 'selecting' property is redundant.
`SQLTemplate(DbEntity rootEntity, java.lang.String defaultTemplate)`
`SQLTemplate(DbEntity rootEntity, java.lang.String defaultTemplate, boolean selecting)` Deprecated. Since 1.2 'selecting' property is redundant.
`SQLTemplate(ObjEntity rootEntity, java.lang.String defaultTemplate)`
`SQLTemplate(ObjEntity rootEntity, java.lang.String defaultTemplate, boolean selecting)` Deprecated. Since 1.2 'selecting' property is redundant.
`SQLTemplate(java.lang.String objEntityName, java.lang.String defaultTemplate)`
`SQLTemplate(java.lang.String objEntityName, java.lang.String defaultTemplate, boolean selecting)` Deprecated. Since 1.2 'selecting' property is redundant.

Method Summary
`PrefetchTreeNode` | `addPrefetch(java.lang.String prefetchPath)` Adds a prefetch.
`void` | `addPrefetches(java.util.Collection prefetches)` Adds all prefetches from a provided collection.
`void` | `clearPrefetches()` Clears all prefetches.
`Query` | `createQuery(java.util.Map parameters)` Creates and returns a new SQLTemplate built using this query as a prototype and substituting template parameters with the values from the map.
`SQLAction` | `createSQLAction(SQLActionVisitor visitor)` Calls sqlAction(this) 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`.
`java.lang.String` | `getCustomTemplate(java.lang.String key)` Returns template for key, or null if there is no template configured for this key.
`java.lang.String` | `getDefaultTemplate()` Returns default SQL template for this query.
`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()` Utility method to get the first set of parameters, since most queries will only have one.
`PrefetchTreeNode` | `getPrefetchTree()` Returns a root node of prefetch tree used by this query, or null of no prefetches are configured.
`java.lang.String` | `getTemplate(java.lang.String key)` Returns a template for key, or a default template if a template for key is not found.
`java.util.Collection` | `getTemplateKeys()` Returns a collection of configured template keys.
`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 'selecting' property is redundant.
`java.util.Iterator` | `parametersIterator()` Returns an iterator over parameter sets.
`int` | `parametersSize()` Returns the number of parameter sets.
`SQLTemplate` | `queryWithParameters(java.util.Map parameters)` Returns a new query built using this query as a prototype and a new set of parameters.
`SQLTemplate` | `queryWithParameters(java.util.Map[] parameters)` Returns a new query built using this query as a prototype and a new set of parameters.
`void` | `removePrefetch(java.lang.String prefetch)`
`void` | `removeTemplate(java.lang.String key)`
`void` | `setCachePolicy(java.lang.String policy)`
`void` | `setDefaultTemplate(java.lang.String string)` Sets default SQL template for this query.
`void` | `setFetchingDataRows(boolean flag)`
`void` | `setFetchLimit(int fetchLimit)`
`void` | `setPageSize(int pageSize)`
`void` | `setParameters(java.util.Map map)` Utility method to initialize query with only a single set of parameters.
`void` | `setParameters(java.util.Map[] parameters)`
`void` | `setRefreshingObjects(boolean flag)`
`void` | `setResolvingInherited(boolean b)`
`void` | `setSelecting(boolean b)` Deprecated. Since 1.2 'selecting' property is redundant.
`void` | `setTemplate(java.lang.String key, java.lang.String template)` Adds a SQL template string for a given key.

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

### defaultTemplate

    protected java.lang.String defaultTemplate

### templates

    protected java.util.Map templates

### parameters

    protected java.util.Map[] parameters

### selecting

    protected boolean selecting

  Deprecated. Since 1.2 this property is redundant.

Constructor Detail

### SQLTemplate

    public SQLTemplate()

  Creates an empty SQLTemplate. Note this constructor does not specify the "root" of the query, so a user must call "setRoot" later to make sure SQLTemplate can be executed.

  Since:
    1.2

### SQLTemplate

    public SQLTemplate(DataMap rootMap,
                       java.lang.String defaultTemplate)

Since:
  1.2

### SQLTemplate

    public SQLTemplate(ObjEntity rootEntity,
                       java.lang.String defaultTemplate)

Since:
  1.2

### SQLTemplate

    public SQLTemplate(java.lang.Class rootClass,
                       java.lang.String defaultTemplate)

Since:
  1.2

### SQLTemplate

    public SQLTemplate(DbEntity rootEntity,
                       java.lang.String defaultTemplate)

Since:
  1.2

### SQLTemplate

    public SQLTemplate(java.lang.String objEntityName,
                       java.lang.String defaultTemplate)

Since:
  1.2

### SQLTemplate

    public SQLTemplate(boolean selecting)

  Deprecated. Since 1.2 'selecting' property is redundant.

  Creates an empty SQLTemplate. Note this constructor does not specify the "root" of the query, so a user must call "setRoot" later to make sure SQLTemplate can be executed.

### SQLTemplate

    public SQLTemplate(DataMap rootMap,
                       java.lang.String defaultTemplate,
                       boolean selecting)

  Deprecated. Since 1.2 'selecting' property is redundant.

### SQLTemplate

    public SQLTemplate(ObjEntity rootEntity,
                       java.lang.String defaultTemplate,
                       boolean selecting)

  Deprecated. Since 1.2 'selecting' property is redundant.

### SQLTemplate

    public SQLTemplate(java.lang.Class rootClass,
                       java.lang.String defaultTemplate,
                       boolean selecting)

  Deprecated. Since 1.2 'selecting' property is redundant.

### SQLTemplate

    public SQLTemplate(DbEntity rootEntity,
                       java.lang.String defaultTemplate,
                       boolean selecting)

  Deprecated. Since 1.2 'selecting' property is redundant.

### SQLTemplate

    public SQLTemplate(java.lang.String objEntityName,
                       java.lang.String defaultTemplate,
                       boolean selecting)

  Deprecated. Since 1.2 'selecting' property is redundant.

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

### createSQLAction

    public SQLAction createSQLAction(SQLActionVisitor visitor)

  Calls sqlAction(this) on the visitor.

  Specified by:
    `createSQLAction` in interface `Query`
  Specified by:
    `createSQLAction` in class `AbstractQuery`
  Since:
    1.2

### encodeAsXML

    public void encodeAsXML(XMLEncoder encoder)

  Prints itself as XML to the provided PrintWriter.

  Specified by:
    `encodeAsXML` in interface `XMLSerializable`
  Since:
    1.1

### initWithProperties

    public void initWithProperties(java.util.Map properties)

  Initializes query parameters using a set of properties.

  Since:
    1.1

### parametersIterator

    public java.util.Iterator parametersIterator()

  Returns an iterator over parameter sets. Each element returned from the iterator is a java.util.Map.

### parametersSize

    public int parametersSize()

  Returns the number of parameter sets.

### queryWithParameters

    public SQLTemplate queryWithParameters(java.util.Map parameters)

  Returns a new query built using this query as a prototype and a new set of parameters.

### queryWithParameters

    public SQLTemplate queryWithParameters(java.util.Map[] parameters)

  Returns a new query built using this query as a prototype and a new set of parameters.

### createQuery

    public Query createQuery(java.util.Map parameters)

  Creates and returns a new SQLTemplate 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)

### getDefaultTemplate

    public java.lang.String getDefaultTemplate()

  Returns default SQL template for this query.

### setDefaultTemplate

    public void setDefaultTemplate(java.lang.String string)

  Sets default SQL template for this query.

### getTemplate

    public java.lang.String getTemplate(java.lang.String key)

  Returns a template for key, or a default template if a template for key is not found.

### getCustomTemplate

    public java.lang.String getCustomTemplate(java.lang.String key)

  Returns template for key, or null if there is no template configured for this key. Unlike `getTemplate(String)`this method does not return a default template as a failover strategy, rather it returns null.

### setTemplate

    public void setTemplate(java.lang.String key,
                            java.lang.String template)

  Adds a SQL template string for a given key.

  See Also:
    `setDefaultTemplate(String)`

### removeTemplate

    public void removeTemplate(java.lang.String key)

### getTemplateKeys

    public java.util.Collection getTemplateKeys()

  Returns a collection of configured template keys.

### getParameters

    public java.util.Map getParameters()

  Utility method to get the first set of parameters, since most queries will only have one.

### setParameters

    public void setParameters(java.util.Map map)

  Utility method to initialize query with only a single set of parameters. Useful, since most queries will only have one set. Internally calls `setParameters(Map[])`.

### setParameters

    public void setParameters(java.util.Map[] parameters)

### isSelecting

    public boolean isSelecting()

  Deprecated. Since 1.2 'selecting' property is redundant.

  Returns true if SQLTemplate is expected to return a ResultSet.

### setSelecting

    public void setSelecting(boolean b)

  Deprecated. Since 1.2 'selecting' property is redundant.

  Sets whether SQLTemplate is expected to return a ResultSet.

### 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

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 Apache.org All Rights Reserved.