org.apache.cayenne.query
Class SQLTemplate

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


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