Class SQLTemplate
- All Implemented Interfaces:
- Serializable,- ParameterizedQuery,- Query
public class SQLTemplate extends AbstractQuery implements ParameterizedQuery
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.
 
- Since:
- 1.1
- See Also:
- Serialized Form
- 
Field SummaryFields Modifier and Type Field Description static StringCOLUMN_NAME_CAPITALIZATION_PROPERTYprotected CapsStrategycolumnNamesCapitalizationprotected StringdefaultTemplateprotected Map<String,?>[]parametersprotected List<Object>positionalParamsprotected SQLResultresultprotected booleanreturnGeneratedKeysprotected Map<String,String>templatesFields inherited from class org.apache.cayenne.query.AbstractQueryrootFields inherited from class org.apache.cayenne.query.CacheableQuerylogger
- 
Constructor SummaryConstructors Constructor Description SQLTemplate()Creates an empty SQLTemplate.SQLTemplate(Class<?> rootClass, String defaultTemplate)SQLTemplate(String defaultTemplate, boolean isFetchingDataRows)Creates a SQLTemplate without an explicit root.SQLTemplate(String objEntityName, String defaultTemplate)SQLTemplate(DataMap rootMap, String defaultTemplate, boolean isFetchingDataRows)SQLTemplate(DbEntity rootEntity, String defaultTemplate)SQLTemplate(ObjEntity rootEntity, String defaultTemplate)
- 
Method SummaryModifier and Type Method Description PrefetchTreeNodeaddPrefetch(String prefetchPath)Adds a prefetch.voidaddPrefetch(PrefetchTreeNode prefetchElement)Adds a prefetch with specified relationship path to the query.voidaddPrefetches(Collection<String> prefetches)Adds all prefetches from a provided collection.voidclearPrefetches()Clears all prefetches.QuerycreateQuery(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.SQLActioncreateSQLAction(SQLActionVisitor visitor)Calls sqlAction(this) on the visitor.protected org.apache.cayenne.query.BaseQueryMetadatagetBaseMetaData()CapsStrategygetColumnNamesCapitalization()Returns a column name capitalization policy applied to selecting queries.StringgetCustomTemplate(String key)Returns template for key, or null if there is no template configured for this key.StringgetDataNodeName()Returns a name of the DataNode to use with this SQLTemplate.StringgetDefaultTemplate()Returns default SQL template for this query.intgetFetchLimit()intgetFetchOffset()QueryMetadatagetMetaData(EntityResolver resolver)Returns default select parameters.intgetPageSize()Map<String,?>getParameters()Utility method to get the first set of parameters, since most queries will only have one.Map<String,?>getParams()Returns a map of named parameters that will be bound to SQL.List<Object>getPositionalParams()Returns a list of positional parameters that will be bound to SQL.PrefetchTreeNodegetPrefetchTree()SQLResultgetResult()List<Class<?>>getResultColumnsTypes()intgetStatementFetchSize()StringgetTemplate(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.voidinitWithProperties(Map<String,?> properties)Initializes query parameters using a set of properties.booleanisFetchingDataRows()booleanisReturnGeneratedKeys()booleanisUseScalar()Iterator<Map<String,?>>parametersIterator()Returns an iterator over parameter sets.intparametersSize()Returns the number of parameter sets.SQLTemplatequeryWithParameters(Map<String,?>... parameters)Returns a new query built using this query as a prototype and a new set of parameters.voidremovePrefetch(String prefetch)voidremoveTemplate(String key)voidroute(QueryRouter router, EntityResolver resolver, Query substitutedQuery)Implements default routing mechanism relying on the EntityResolver to find DataMap based on the query root.voidsetColumnNamesCapitalization(CapsStrategy columnNameCapitalization)Sets a column name capitalization policy applied to selecting queries.voidsetDataNodeName(String dataNodeName)Sets a name of the DataNode to use with this SQLTemplate.voidsetDefaultTemplate(String string)Sets default SQL template for this query.voidsetFetchingDataRows(boolean flag)voidsetFetchLimit(int fetchLimit)voidsetFetchOffset(int fetchOffset)voidsetPageSize(int pageSize)voidsetParameters(Map<String,?>... parameters)Utility method to initialize query with one or more sets of parameters.voidsetParams(Map<String,?> params)Initializes named parameter of this query.voidsetParamsArray(Object... params)Initializes positional parameters of the query.voidsetParamsList(List<Object> params)Initializes positional parameters of the query.voidsetResult(SQLResult resultSet)Sets an optional explicit mapping of the result set.voidsetResultColumnsTypes(Class<?>... types)voidsetResultColumnsTypes(List<Class<?>> resultColumnsTypes)voidsetReturnGeneratedKeys(boolean returnGeneratedKeys)Sets flag to return generated keys.voidsetRoot(Object value)Sets the root of the queryvoidsetStatementFetchSize(int size)Sets statement's fetch size (0 for no default size)voidsetTemplate(String key, String template)Adds a SQL template string for a given key.voidsetUseScalar(boolean useScalar)Sets flag to use scalars.Methods inherited from class org.apache.cayenne.query.AbstractQuerygetRoot, toStringMethods inherited from class org.apache.cayenne.query.CacheableQuerygetCacheGroup, getCacheStrategy, setCacheGroup, setCacheStrategy, useLocalCache, useLocalCache, useSharedCache, useSharedCache
- 
Field Details- 
COLUMN_NAME_CAPITALIZATION_PROPERTY- See Also:
- Constant Field Values
 
- 
defaultTemplate
- 
templates
- 
parameters
- 
positionalParams
- 
columnNamesCapitalization
- 
result
- 
returnGeneratedKeysprotected boolean returnGeneratedKeys
 
- 
- 
Constructor Details- 
SQLTemplatepublic 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
 
- 
SQLTemplateCreates a SQLTemplate without an explicit root.- Since:
- 4.0
 
- 
SQLTemplate- Since:
- 3.1
 
- 
SQLTemplate- Since:
- 1.2
 
- 
SQLTemplate- Since:
- 1.2
 
- 
SQLTemplate- Since:
- 1.2
 
- 
SQLTemplate- Since:
- 1.2
 
 
- 
- 
Method Details- 
setResultColumnsTypes
- 
setRootDescription copied from class:AbstractQuerySets the root of the query- Overrides:
- setRootin class- AbstractQuery
- Parameters:
- value- The new root
 
- 
routeDescription copied from class:AbstractQueryImplements default routing mechanism relying on the EntityResolver to find DataMap based on the query root. This mechanism should be sufficient for most queries that "know" their root.- Specified by:
- routein interface- Query
- Overrides:
- routein class- AbstractQuery
 
- 
getMetaDataDescription copied from class:AbstractQueryReturns default select parameters.- Specified by:
- getMetaDatain interface- Query
- Overrides:
- getMetaDatain class- AbstractQuery
- Since:
- 1.2
 
- 
createSQLActionCalls sqlAction(this) on the visitor.- Specified by:
- createSQLActionin interface- Query
- Specified by:
- createSQLActionin class- AbstractQuery
- Since:
- 1.2
 
- 
initWithPropertiesInitializes query parameters using a set of properties.- Since:
- 1.1
 
- 
parametersIteratorReturns an iterator over parameter sets. Each element returned from the iterator is a java.util.Map.
- 
parametersSizepublic int parametersSize()Returns the number of parameter sets.
- 
setParamsInitializes named parameter of this query. Note that calling this method will reset any positional parameters.- Since:
- 4.0
 
- 
setParamsArrayInitializes positional parameters of the query. Parameters are bound in the order they are found in the SQL template. If a given parameter name is used more than once, only the first occurrence is treated as "position", subsequent occurrences are bound with the same value as the first one. If template parameters count is different from the array parameter count, an exception will be thrown.Note that calling this method will reset any previously set *named* parameters. - Since:
- 4.0
 
- 
setParamsListInitializes positional parameters of the query. Parameters are bound in the order they are found in the SQL template. If a given parameter name is used more than once, only the first occurrence is treated as "position", subsequent occurrences are bound with the same value as the first one. If template parameters count is different from the list parameter count, an exception will be thrown.Note that calling this method will reset any previously set *named* parameters. - Since:
- 4.0
 
- 
queryWithParametersReturns a new query built using this query as a prototype and a new set of parameters.
- 
createQueryCreates and returns a new SQLTemplate built using this query as a prototype and substituting template parameters with the values from the map.- Specified by:
- createQueryin interface- ParameterizedQuery
- Since:
- 1.1
 
- 
getBaseMetaDataprotected org.apache.cayenne.query.BaseQueryMetadata getBaseMetaData()- Specified by:
- getBaseMetaDatain class- CacheableQuery
 
- 
getFetchLimitpublic int getFetchLimit()
- 
setFetchLimitpublic void setFetchLimit(int fetchLimit)
- 
getFetchOffsetpublic int getFetchOffset()- Since:
- 3.0
 
- 
setFetchOffsetpublic void setFetchOffset(int fetchOffset)- Since:
- 3.0
 
- 
getPageSizepublic int getPageSize()
- 
setPageSizepublic void setPageSize(int pageSize)
- 
setFetchingDataRowspublic void setFetchingDataRows(boolean flag)
- 
isFetchingDataRowspublic boolean isFetchingDataRows()
- 
getDefaultTemplateReturns default SQL template for this query.
- 
setDefaultTemplateSets default SQL template for this query.
- 
getTemplateReturns a template for key, or a default template if a template for key is not found.
- 
getCustomTemplateReturns template for key, or null if there is no template configured for this key. UnlikegetTemplate(String)this method does not return a default template as a failover strategy, rather it returns null.
- 
setTemplateAdds 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
- 
getTemplateKeysReturns a collection of configured template keys.
- 
getParamsReturns a map of named parameters that will be bound to SQL.- Since:
- 4.0
 
- 
getPositionalParamsReturns a list of positional parameters that will be bound to SQL.- Since:
- 4.0
 
- 
getParametersUtility method to get the first set of parameters, since most queries will only have one.
- 
setParametersUtility method to initialize query with one or more sets of parameters.
- 
getPrefetchTree- Since:
- 1.2
 
- 
addPrefetchAdds a prefetch.- Since:
- 1.2
 
- 
addPrefetchAdds a prefetch with specified relationship path to the query.- Since:
- 4.0
 
- 
removePrefetch- Since:
- 1.2
 
- 
addPrefetchesAdds all prefetches from a provided collection.- Since:
- 1.2
 
- 
clearPrefetchespublic void clearPrefetches()Clears all prefetches.- Since:
- 1.2
 
- 
getColumnNamesCapitalizationReturns 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
 
- 
setColumnNamesCapitalizationSets 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. - Since:
- 3.0
 
- 
setResultSets 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 theSQLResultrules.- Since:
- 3.0
 
- 
getResult- Since:
- 3.0
 
- 
setStatementFetchSizepublic void setStatementFetchSize(int size)Sets statement's fetch size (0 for no default size)- Since:
- 3.0
 
- 
getStatementFetchSizepublic int getStatementFetchSize()- Returns:
- statement's fetch size
- Since:
- 3.0
 
- 
getDataNodeNameReturns a name of the DataNode to use with this SQLTemplate. This information will be used during query execution if no other routing information is provided such as entity name or class, etc.- Since:
- 4.0
 
- 
setDataNodeNameSets a name of the DataNode to use with this SQLTemplate. This information will be used during query execution if no other routing information is provided such as entity name or class, etc.- Since:
- 4.0
 
- 
isReturnGeneratedKeyspublic boolean isReturnGeneratedKeys()- Returns:
- returnGeneratedKeys flag
- Since:
- 4.1
 
- 
setReturnGeneratedKeyspublic void setReturnGeneratedKeys(boolean returnGeneratedKeys)Sets flag to return generated keys.- Since:
- 4.1
 
- 
getResultColumnsTypes
- 
setResultColumnsTypes
- 
setUseScalarpublic void setUseScalar(boolean useScalar)Sets flag to use scalars.- Since:
- 4.1
 
- 
isUseScalarpublic boolean isUseScalar()
 
-