QueryBuilder (XO Query Client - Documentation 11.6.0-1110 API)

java.lang.Object
- com.tridion.smarttarget.query.builder.QueryBuilder

public class QueryBuilder
extends Object

Used to build a query for Experience Optimization Promotions and items.

Example getting Promotions from Publication 'tcm:0-3-1' in the Header or Footer region:

 
 TcmUri publicationId = new TcmUri("tcm:0-3-1");
 String regionHeader = "Header";
 String regionFooter = "Footer";

 QueryBuilder builder = new QueryBuilder(publicationId, Arrays.asList(regionHeader, regionFooter));
 ResultSet resultSet = builder.execute();

Example getting Experiments adding criteria for a specific Page and an Audience Management based trigger value:

 
 TcmUri publicationId = new TcmUri("tcm:0-3-1");
 TcmUri pageId = new TcmUri("tcm:3-6409-64");
 String regionHeader = "Header";
 String triggerTypeAgeUrlParam = "am_ex_age";

 QueryBuilder builder = new QueryBuilder(publicationId, Arrays.asList(regionHeader));
 builder.addCriteria(new PageCriteria(pageId));
 builder.addCriteria(new CustomParameterCriteria(triggerTypeAgeUrlParam, Integer.toString(30)));

 ResultSet resultSet = builder.execute();

 List<Experiment> experiments = new ArrayList<Experiment>();
 for(Promotion promotion : resultSet.getPromotions()) {
     if(promotion instanceof Experiment) experiments.add((Experiment)promotion);
 }
 log.info(String.format("Found %s experiments.", experiments.size()));

Constructor Summary

Constructors
Constructor and Description
`QueryBuilder()` Initializes a QueryBuilder.
`QueryBuilder(String universe, String locale)` Initializes a QueryBuilder for the specified universe and locale.
`QueryBuilder(String universe, String locale, com.tridion.smarttarget.utils.TcmUri publication, List<String> regions)` Initializes a QueryBuilder for the given universe, locale, Publication and regions.
`QueryBuilder(com.tridion.smarttarget.utils.TcmUri publication, List<String> regions)` Initializes a QueryBuilder for the given Publication and regions.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`QueryBuilder`	`addCriteria(com.tridion.smarttarget.query.builder.Criteria criteria)` Adds a Criteria object to the QueryBuilder.
`void`	`addListener(QueryListener listener)` Adds a listener.
`void`	`clearAllCriteria()` Clears All criteria.
`com.tridion.smarttarget.query.ResultSet`	`execute()` Executes the query and returns a `ResultSet` exposing the Promotions, search results and navigation links.
`String`	`getContextPublicationUri()` Gets the URI of the context Publication, where the resulting items will be rendered.
`Date`	`getCurrentDate()` Gets the 'currentDate' that will be used to trigger on.
`String`	`getLocale()` Gets the locale.
`List<com.tridion.smarttarget.query.builder.Criteria>`	`getLocationCriteria()` Gets all location based criteria.
`int`	`getMaxItems()` Gets the number of Items that will be returned from a SmartTarget query.
`List<com.tridion.smarttarget.query.builder.Criteria>`	`getParameterCriteria()` Gets all parameter based criteria.
`ParameterCriteria`	`getParameterCriteriaByName(String parameterName)` Gets the ParameterCriteria from the list for the specified name.
`List<com.tridion.smarttarget.query.builder.Criteria>`	`getSearchCriteria()` Gets all search based criteria.
`int`	`getStartIndex()` Gets the start index of Items that will be returned from a SmartTarget query.
`int`	`getTimeout()` Gets the timeout in milliseconds for the SmartTarget query.
`String`	`getUniverse()` Gets the Universe.
`boolean`	`isParsedFromNavigationLink()` Indicates if this QueryBuilder object has been constructed from a Fredhopper Link.
`void`	`parseQueryString(String query)` Parses a query.
`void`	`parseQueryString(String queryString, boolean clearCriteria)` Parses a query and adds `Criteria` objects to the QueryBuilder.
`QueryBuilder`	`removeCriteria(com.tridion.smarttarget.query.builder.Criteria criteria)` Removes a Criteria object.
`void`	`removeListener(QueryListener listener)` Removes a listener.
`void`	`setCurrentDate(Date value)` Overrides the 'currentDate' that will be used to trigger on.
`void`	`setMaxItems(int value)` Sets the number of Items that will be returned from a SmartTarget query.
`void`	`setStartIndex(int value)` Sets the start index of Items that will be returned from a SmartTarget query.
`void`	`setTimeout(int timeoutInMilliseconds)` Sets the timeout in milliseconds for the SmartTarget query.
`String`	`toString()` Returns the current query, represented as a URL query string.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - QueryBuilder
```
public QueryBuilder()
```
    Initializes a QueryBuilder.
    
    Gets the universe and locale from the configuration.
  - QueryBuilder
```
public QueryBuilder(String universe,
                    String locale)
```
    Initializes a QueryBuilder for the specified universe and locale.
    
    Parameters:
    
    universe - the universe where this query executes.
    
    locale - the locale for which this query executes.
  - QueryBuilder
```
public QueryBuilder(com.tridion.smarttarget.utils.TcmUri publication,
                    List<String> regions)
             throws com.tridion.smarttarget.SmartTargetException
```
    Initializes a QueryBuilder for the given Publication and regions.
    Gets the universe and locale from the configuration.
    The publication and regions are added as PublicationCriteria and RegionCriteria.
    Results will be 'scoped' for this publication.
    
    Parameters:
    
    publication - The TcmUri of the Publication.
    
    regions - a list of regions.
    
    Throws:
    
    com.tridion.smarttarget.SmartTargetException
  - QueryBuilder
```
public QueryBuilder(String universe,
                    String locale,
                    com.tridion.smarttarget.utils.TcmUri publication,
                    List<String> regions)
             throws com.tridion.smarttarget.SmartTargetException
```
    Initializes a QueryBuilder for the given universe, locale, Publication and regions.
    
    The Publication and regions are added as PublicationCriteria and RegionCriteria.
    Results will be 'scoped' for this publication.
    Example:
```
 
 String universe = "catalog01";
 String locale = "en_US";
 TcmUri publicationId = new TcmUri("tcm:0-3-1");
 TcmUri pageId = new TcmUri("tcm:3-6409-64");
 String regionHeader = "Header";
 String regionFooter = "Footer";

 QueryBuilder builder = new QueryBuilder(universe, locale, publicationId, Arrays.asList(regionHeader,
 regionFooter));
 ResultSet resultSet = builder.execute();
 
 
```
    Parameters:
    
    universe - the universe where this query executes.
    
    locale - the locale for which this query executes.
    
    publication - The TcmUri of the Publication.
    
    regions - a list of regions.
    
    Throws:
    
    com.tridion.smarttarget.SmartTargetException
- Method Detail
  - clearAllCriteria
```
public void clearAllCriteria()
```
    Clears All criteria.
  - addCriteria
```
public QueryBuilder addCriteria(com.tridion.smarttarget.query.builder.Criteria criteria)
                         throws com.tridion.smarttarget.SmartTargetException
```
    Adds a Criteria object to the QueryBuilder.
    
    Parameters:
    
    criteria - A concrete subclass of Criteria to add to the QueryBuilder.
    
    Returns:
    
    The QueryBuilder.
    
    Throws:
    
    com.tridion.smarttarget.SmartTargetException
  - removeCriteria
```
public QueryBuilder removeCriteria(com.tridion.smarttarget.query.builder.Criteria criteria)
```
    Removes a Criteria object.
    
    Parameters:
    
    criteria - The Criteria to remove.
    
    Returns:
    
    The QueryBuilder.
  - getLocationCriteria
```
public List<com.tridion.smarttarget.query.builder.Criteria> getLocationCriteria()
```
    Gets all location based criteria.
    
    Returns:
    
    All location based criteria in the form of an ArrayList of Criteria objects.
  - getParameterCriteria
```
public List<com.tridion.smarttarget.query.builder.Criteria> getParameterCriteria()
```
    Gets all parameter based criteria.
    
    Returns:
    
    All parameter based criteria in the form of an ArrayList of Criteria objects.
  - getSearchCriteria
```
public List<com.tridion.smarttarget.query.builder.Criteria> getSearchCriteria()
```
    Gets all search based criteria.
    
    Returns:
    
    All search based criteria in the form of an ArrayList of Criteria objects.
  - getCurrentDate
```
public Date getCurrentDate()
```
    Gets the 'currentDate' that will be used to trigger on.
    
    Returns:
    
    A date representing the 'currentDate'.
  - setCurrentDate
```
public void setCurrentDate(Date value)
```
    Overrides the 'currentDate' that will be used to trigger on.
    
    Parameters:
    
    value - The Date to override the default 'currentDate' with.
  - getParameterCriteriaByName
```
public ParameterCriteria getParameterCriteriaByName(String parameterName)
```
    Gets the ParameterCriteria from the list for the specified name. Null if no ParameterCriteria with that name was found.
    
    Parameters:
    
    parameterName - The name of the ParameterCriteria to get.
    
    Returns:
    
    A ParameterCriteria if it was found, null otherwise.
  - parseQueryString
```
public void parseQueryString(String query)
                      throws com.tridion.smarttarget.SmartTargetException
```
    Parses a query.
    
    Parameters:
    
    query - The query string to parse.
    
    Throws:
    
    com.tridion.smarttarget.SmartTargetException - when query string is not parsable.
  - parseQueryString
```
public void parseQueryString(String queryString,
                             boolean clearCriteria)
                      throws com.tridion.smarttarget.SmartTargetException
```
    Parses a query and adds Criteria objects to the QueryBuilder.
    
    This method can be used to add triggers found on the Ambient Data Framework to the query as CustomParameterCriteria objects.
    Example:
```
 
 TcmUri publicationId = new TcmUri("tcm:0-3-1");
 TcmUri pageId = new TcmUri("tcm:3-6409-64");
 String regionHeader = "Header";

 QueryBuilder builder = new QueryBuilder(publicationId, Arrays.asList(regionHeader));
 builder.addCriteria(new PageCriteria(pageId));

 ClaimStore claimStore = AmbientDataContext.getCurrentClaimStore();
 if(claimStore != null) {
     String triggers = AmbientDataHelper.getTriggers(claimStore);
     builder.parseQueryString(triggers);
 }
 ResultSet resultSet = builder.execute();
 
 
```
    Parameters:
    
    queryString - The query string to parse.
    
    clearCriteria - When set to true clears any Criteria before parsing.
    
    Throws:
    
    com.tridion.smarttarget.SmartTargetException - when string is not parsable.
  - execute
```
public com.tridion.smarttarget.query.ResultSet execute()
                                                throws com.tridion.smarttarget.SmartTargetException
```
    Executes the query and returns a ResultSet exposing the Promotions, search results and navigation links.
    
    Returns:
    
    The result of executing the Query in the form of a ResultSet.
    
    Throws:
    
    com.tridion.smarttarget.SmartTargetException
  - toString
```
public String toString()
```
    Returns the current query, represented as a URL query string.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    The query string.
  - getUniverse
```
public String getUniverse()
```
    Gets the Universe.
    
    Returns:
    
    The universe.
  - getLocale
```
public String getLocale()
```
    Gets the locale.
    
    Returns:
    
    The locale.
  - getContextPublicationUri
```
public String getContextPublicationUri()
```
    Gets the URI of the context Publication, where the resulting items will be rendered.
    This is used to ensure that the correct content is displayed for Promotions that return content from a parent Publication. Setting the context Publication is done by adding PublicationCriteria to the QueryBuilder.
    
    Returns:
    
    A String representing the context Publication Uri.
  - getStartIndex
```
public int getStartIndex()
```
    Gets the start index of Items that will be returned from a SmartTarget query.
    
    Returns:
    
    The start index to use when retrieving items through a SmartTarget query.
  - setStartIndex
```
public void setStartIndex(int value)
```
    Sets the start index of Items that will be returned from a SmartTarget query.
    
    Use this method in combination with setMaxItems before executing a query to implement paging through SmartTarget items. Example: A SmartTarget query requests data based on a Keyword. There are 100 Component Presentations related to that keyword. Calling setStartIndex(0) and setMaxItems(5) will result in the first up to fifth item to be returned. Calling setStartIndex(5) and setMaxItems(5) will result in the next five items to be returned. etc.
    
    Parameters:
    
    value - The start index to use when retrieving items through a SmartTarget query.
  - getMaxItems
```
public int getMaxItems()
```
    Gets the number of Items that will be returned from a SmartTarget query.
    
    Returns:
    
    Number of Items returned from a SmartTarget query.
  - setMaxItems
```
public void setMaxItems(int value)
```
    Sets the number of Items that will be returned from a SmartTarget query.
    
    Use this method in combination with setStartIndex before executing a query to implement paging through SmartTarget items. Example: A SmartTarget query requests data based on a Keyword. There are 100 Component Presentations related to that keyword. Calling setStartIndex(0) and setMaxItems(5) will result in the first up to fifth item to be returned. Calling setStartIndex(5) and setMaxItems(5) will result in the next five items to be returned. etc.
    
    Parameters:
    
    value - The number of Items returned from a SmartTarget query.
  - getTimeout
```
public int getTimeout()
```
    Gets the timeout in milliseconds for the SmartTarget query.
    
    Returns:
    
    The timeout in milliseconds.
  - setTimeout
```
public void setTimeout(int timeoutInMilliseconds)
```
    Sets the timeout in milliseconds for the SmartTarget query.
    
    Parameters:
    
    timeoutInMilliseconds - The timeout in milliseconds.
  - isParsedFromNavigationLink
```
public boolean isParsedFromNavigationLink()
```
    Indicates if this QueryBuilder object has been constructed from a Fredhopper Link.
    
    Returns:
    
    true if the QueryBuilder was created from a Fredhopper Navigation Link, false otherwise.
  - addListener
```
public void addListener(QueryListener listener)
```
    Adds a listener.
    
    Parameters:
    
    listener - The QueryListener to add.
  - removeListener
```
public void removeListener(QueryListener listener)
```
    Removes a listener.
    
    Parameters:
    
    listener - The QueryListener to remove.

Class QueryBuilder

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

QueryBuilder

QueryBuilder

QueryBuilder

QueryBuilder

Method Detail

clearAllCriteria

addCriteria

removeCriteria

getLocationCriteria

getParameterCriteria

getSearchCriteria

getCurrentDate

setCurrentDate

getParameterCriteriaByName

parseQueryString

parseQueryString

execute

toString

getUniverse

getLocale

getContextPublicationUri

getStartIndex

setStartIndex

getMaxItems

setMaxItems

getTimeout

setTimeout

isParsedFromNavigationLink

addListener

removeListener