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:
Serializable, ParameterizedQuery, Query, XMLSerializable
Direct Known Subclasses:
EOSQLQuery

public class SQLTemplate
extends AbstractQuery
implements 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
See Also:
Serialized Form

Field Summary
protected  String columnNamesCapitalization
           
protected  String defaultTemplate
           
static String LOWERCASE_COLUMN_NAMES
           
protected  Map<String,?>[] parameters
           
protected  Map<String,String> templates
           
static String UPPERCASE_COLUMN_NAMES
           
 
Fields inherited from class org.apache.cayenne.query.AbstractQuery
name, root
 
Constructor Summary
SQLTemplate()
          Creates an empty SQLTemplate.
SQLTemplate(Class<?> rootClass, String defaultTemplate)
           
SQLTemplate(DataMap rootMap, String defaultTemplate)
           
SQLTemplate(DbEntity rootEntity, String defaultTemplate)
           
SQLTemplate(ObjEntity rootEntity, String defaultTemplate)
           
SQLTemplate(String objEntityName, String defaultTemplate)
           
 
Method Summary
 PrefetchTreeNode addPrefetch(String prefetchPath)
          Adds a prefetch.
 void addPrefetches(Collection<String> prefetches)
          Adds all prefetches from a provided collection.
 void clearPrefetches()
          Clears all prefetches.
 Query createQuery(Map<String,?> 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.
 String[] getCacheGroups()
           
 String getCachePolicy()
          Deprecated. since 3.0 getCacheStrategy() replaces this method.
 QueryCacheStrategy getCacheStrategy()
           
 String getColumnNamesCapitalization()
          Returns a column name capitalization policy applied to selecting queries.
 String getCustomTemplate(String key)
          Returns template for key, or null if there is no template configured for this key.
 String getDefaultTemplate()
          Returns default SQL template for this query.
 int getFetchLimit()
           
 int getFetchOffset()
           
 QueryMetadata getMetaData(EntityResolver resolver)
          Returns default select parameters.
 int getPageSize()
           
 Map<String,?> getParameters()
          Utility method to get the first set of parameters, since most queries will only have one.
 PrefetchTreeNode getPrefetchTree()
           
 String getTemplate(String key)
          Returns a template for key, or a default template if a template for key is not found.
 Collection<String> getTemplateKeys()
          Returns a collection of configured template keys.
 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.
 Iterator<?> parametersIterator()
          Returns an iterator over parameter sets.
 int parametersSize()
          Returns the number of parameter sets.
 SQLTemplate queryWithParameters(Map<String,?>... parameters)
          Returns a new query built using this query as a prototype and a new set of parameters.
 void removePrefetch(String prefetch)
           
 void removeTemplate(String key)
           
 void setCacheGroups(String... cacheGroups)
           
 void setCachePolicy(String policy)
          Deprecated. since 3.0 setCacheStrategy(QueryCacheStrategy) replaces this method.
 void setCacheStrategy(QueryCacheStrategy strategy)
           
 void setColumnNamesCapitalization(String columnNameCapitalization)
          Sets a column name capitalization policy applied to selecting queries.
 void setDefaultTemplate(String string)
          Sets default SQL template for this query.
 void setFetchingDataRows(boolean flag)
           
 void setFetchLimit(int fetchLimit)
           
 void setFetchOffset(int fetchOffset)
           
 void setPageSize(int pageSize)
           
 void setParameters(Map<String,?>... parameters)
          Utility method to initialize query with one or more sets 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 setResultSetMapping(SQLResultSetMapping resultSetMapping)
          Sets an optional explicit mapping of the result set.
 void setTemplate(String key, 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, route
 

Field Detail

UPPERCASE_COLUMN_NAMES

public static final String UPPERCASE_COLUMN_NAMES
Since:
3.0
See Also:
Constant Field Values

LOWERCASE_COLUMN_NAMES

public static final String LOWERCASE_COLUMN_NAMES
Since:
3.0
See Also:
Constant Field Values

defaultTemplate

protected String defaultTemplate

templates

protected Map<String,String> templates

parameters

protected Map<String,?>[] parameters

columnNamesCapitalization

protected String columnNamesCapitalization
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,
                   String defaultTemplate)
Since:
1.2

SQLTemplate

public SQLTemplate(ObjEntity rootEntity,
                   String defaultTemplate)
Since:
1.2

SQLTemplate

public SQLTemplate(Class<?> rootClass,
                   String defaultTemplate)
Since:
1.2

SQLTemplate

public SQLTemplate(DbEntity rootEntity,
                   String defaultTemplate)
Since:
1.2

SQLTemplate

public SQLTemplate(String objEntityName,
                   String defaultTemplate)
Since:
1.2
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(Map<String,?> properties)
Initializes query parameters using a set of properties.

Since:
1.1

parametersIterator

public 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(Map<String,?>... parameters)
Returns a new query built using this query as a prototype and a new set of parameters.


createQuery

public Query createQuery(Map<String,?> 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 String getCachePolicy()
Deprecated. since 3.0 getCacheStrategy() replaces this method.


setCachePolicy

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

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

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

public boolean isResolvingInherited()
Deprecated. since 3.0. Inheritance resolving is not optional anymore.


setResolvingInherited

public void setResolvingInherited(boolean b)
Deprecated. since 3.0. Inheritance resolving is not optional anymore.


getDefaultTemplate

public String getDefaultTemplate()
Returns default SQL template for this query.


setDefaultTemplate

public void setDefaultTemplate(String string)
Sets default SQL template for this query.


getTemplate

public String getTemplate(String key)
Returns a template for key, or a default template if a template for key is not found.


getCustomTemplate

public String getCustomTemplate(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(String key,
                        String template)
Adds a SQL template string for a given key. Note the the keys understood by Cayenne must be fully qualified adapter class names. This way the framework can related current DataNode to the right template. E.g. "org.apache.cayenne.dba.oracle.OracleAdapter" is a key that should be used to setup an Oracle-specific template.

See Also:
setDefaultTemplate(String)

removeTemplate

public void removeTemplate(String key)

getTemplateKeys

public Collection<String> getTemplateKeys()
Returns a collection of configured template keys.


getParameters

public Map<String,?> getParameters()
Utility method to get the first set of parameters, since most queries will only have one.


setParameters

public void setParameters(Map<String,?>... parameters)
Utility method to initialize query with one or more sets of parameters.


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

getColumnNamesCapitalization

public String getColumnNamesCapitalization()
Returns a column name capitalization policy applied to selecting queries. This is used to simplify mapping of the queries like "SELECT * FROM ...", ensuring that a chosen Cayenne column mapping strategy (e.g. all column names in uppercase) is portable across database engines that can have varying default capitalization. Default (null) value indicates that column names provided in result set are used unchanged.

Since:
3.0

setColumnNamesCapitalization

public void setColumnNamesCapitalization(String columnNameCapitalization)
Sets a column name capitalization policy applied to selecting queries. This is used to simplify mapping of the queries like "SELECT * FROM ...", ensuring that a chosen Cayenne column mapping strategy (e.g. all column names in uppercase) is portable across database engines that can have varying default capitalization. Default (null) value indicates that column names provided in result set are used unchanged.

Note that while a non-default setting is useful for queries that do not rely on a #result directive to describe columns, it works for all SQLTemplates the same way.

Parameters:
columnNameCapitalization - Can be null of one of LOWERCASE_COLUMN_NAMES or UPPERCASE_COLUMN_NAMES.
Since:
3.0

setResultSetMapping

public void setResultSetMapping(SQLResultSetMapping resultSetMapping)
Sets an optional explicit mapping of the result set. If result set mapping is specified, the result of SQLTemplate may not be a normal list of Persistent objects or DataRows, instead it will follow the SQLResultSetMapping rules.

Since:
3.0


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