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

java.lang.Object
- com.tridion.smarttarget.entitymodel.query.location.Location

All Implemented Interfaces:

Serializable
```
public class Location
extends Object
implements Serializable
```
Class that models FAS locations, i.e. those strings that may serve as valid arguments to the fh_location parameter.

Locations always specify a universe and locale. Additionally they may contain zero or more criteria (modelled through Criterion instances), filters and targets.

All remove*() and set*() methods provided by this class return the Location instance on which they are applied. This is useful for chained manipulations such as the following:
```
 location.removeSearchCriteria().addCriterion(...);
 
```
Author:

pavel

See Also:

Serialized Form

Constructor Summary

Constructors
Constructor and Description
`Location(Location location)` Copy constructor.
`Location(String location)` Creates a `Location` instance by parsing the given string.
`Location(String universe, String locale)` Constructs a minimal `Location` instance.

Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`Location`	`addCriterion(Criterion criterion)` Adds the given `Criterion` to the back of this location.
`boolean`	`equals(Object o)`
`List`	`getAllCriteria()` Returns all `Criterion` instances contained in this location.
`List`	`getCriteria(String attribute)` Returns all `Criterion` instances that operate on the attribute with the given name.
`Criterion`	`getCriterion(int position)` Returns the `Criterion` at the given position, if any.
`Criterion`	`getCriterion(String attribute)` Returns the first `Criterion` instance that operates on the attribute with the given name, if any.
`Criterion`	`getLastCriterion()` Returns last `Criterion` from this location, if any.
`String`	`getLocale()` Returns the locale of this location.
`SearchCriterion`	`getSearchCriterion()` Returns the first (and presumably only) `SearchCriterion` in this location, if any.
`String`	`getUniverse()` Returns the universe of this `Location`.
`int`	`hashCode()`
`protected boolean`	`isValidAttributeName(String str)` Deprecated. This method is not used internally by this class; subclasses can use `CriterionFactory.isValidAttributeName(CharSequence)` instead.
`protected Criterion`	`parseCriterion(String criterion)` Converts the string representation of a criterion into a corresponding `Criterion` instance.
`Location`	`removeAllCriteria()` Removes all criteria, filters and targets from this location, but preserves the configured universe and locale.
`Location`	`removeCriteria(String attribute)` Removes all `Criterion` instances that operate on the attribute with the given name.
`Location`	`removeCriterion(int position)` Removes the `Criterion` at the given position, if any.
`Location`	`removeLastCriterion()` Removes last `Criterion` from this location, if any.
`Location`	`removeSearchCriteria()` Removes all `SearchCriterion` instances from the list of `Criterion` objects that make up this location.
`Location`	`setLocale(String localeParam)` Sets a new locale for this location.
`Location`	`setUniverse(String universeParam)` Sets a new universe for this location.
`int`	`size()` Returns the number of `Criterion` instances contained in this location.
`String`	`toString()` Returns a syntactically correct string representation of this location, such that it can be interpreted by FAS.

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

Constructor Detail

Location
```
public Location(Location location)
```
Copy constructor.

Parameters:

location - The Location instance that is to be cloned.

Location
```
public Location(String universe,
                String locale)
```
Constructs a minimal Location instance.

Parameters:

universe - A valid (non-null, non-empty) universe.

locale - A valid (non-null, non-empty) locale.

Throws:

IllegalArgumentException - If either the universe or locale is malformed.

Location

public Location(String location)

Creates a Location instance by parsing the given string.

The syntax of location strings can roughly be described as follows:

`SingleValuedCriterion`	attribute=value	equals to value
	attribute<value	small or equal to value
	attribute>value	greater or equal to value
	value1<attribute<value2	between values
	value1>attribute>value2	between values
`MultiValuedCriterion`	attribute={value1,value2,...}	equals to set
	attribute<{value1,value2,...}	contained in (subset of)
	attribute>{value1,value2,...}	contains
	attribute>{value1;value2;...}	contains at least one out of
	!attribute>{value}	does not contain
`FunctionCriterion`	function_name(argument,...)=value	function with arginets must be equal to value
`SearchCriterion`	$s=search_phrase;t=profile;p=passId	search for search_phrase with profile and passId

Parameters:: location - The string representation from which to create a new Location instance.
Throws:: IllegalArgumentException - If the location cannot be parsed successfully.

Method Detail
- isValidAttributeName
```
@Deprecated
protected boolean isValidAttributeName(String str)
```
  Deprecated. This method is not used internally by this class; subclasses can use CriterionFactory.isValidAttributeName(CharSequence) instead.
  
  Tells whether the given string is a valid attribute name.
  
  Equivalently, this method tells whether the given string is permissible as a universe or locale identifier.
  
  Parameters:
  
  str - The string to test.
  
  Returns:
  
  true if str can be an attribute name, universe or locale; false otherwise.
- parseCriterion
```
protected Criterion parseCriterion(String criterion)
```
  Converts the string representation of a criterion into a corresponding Criterion instance.
  
  Parameters:
  
  criterion - The string to convert into a Criterion.
  
  Returns:
  
  A Criterion instance that represents criterion.
  
  Throws:
  
  CriterionFactory.InvalidCriterionException - If criterion cannot be parsed.
- toString
```
public String toString()
```
  Returns a syntactically correct string representation of this location, such that it can be interpreted by FAS.
  
  Important: this method will not encode this string in any way. One will have to post-process this string if one is to pass this location around as part of an HTTP query string.
  
  Overrides:
  
  toString in class Object
  
  Returns:
  
  A string that serves as a valid parameter to the FAS fh_location parameter, provided that it is URL encoded.
- getUniverse
```
public String getUniverse()
```
  Returns the universe of this Location.
  
  Returns:
  
  The universe of the location.
  
  See Also:
  
  setUniverse(String)
- setUniverse
```
public Location setUniverse(String universeParam)
```
  Sets a new universe for this location.
  
  Parameters:
  
  universeParam - The new universe.
  
  Returns:
  
  This Location instance; useful for chained manipulations.
  
  Throws:
  
  IllegalArgumentException - If universe is null or empty.
  
  See Also:
  
  getUniverse()
- getLocale
```
public String getLocale()
```
  Returns the locale of this location.
  
  Returns:
  
  The locale of the location.
  
  See Also:
  
  setLocale(String)
- setLocale
```
public Location setLocale(String localeParam)
```
  Sets a new locale for this location.
  
  Parameters:
  
  localeParam - The new locale.
  
  Returns:
  
  This Location instance; useful for chained manipulations.
  
  Throws:
  
  IllegalArgumentException - If locale is null or empty.
  
  See Also:
  
  getLocale()
- addCriterion
```
public Location addCriterion(Criterion criterion)
```
  Adds the given Criterion to the back of this location.
  
  Parameters:
  
  criterion - The new criterion.
  
  Returns:
  
  This Location instance; useful for chained manipulations.
  
  Throws:
  
  IllegalArgumentException - If criterion is null.
- getAllCriteria
```
public List getAllCriteria()
```
  Returns all Criterion instances contained in this location.
  
  Returns:
  
  A (possibly empty) lists that contains all criteria in this location, in order.
  
  See Also:
  
  removeAllCriteria()
- removeAllCriteria
```
public Location removeAllCriteria()
```
  Removes all criteria, filters and targets from this location, but preserves the configured universe and locale.
  
  Returns:
  
  This Location instance; useful for chained manipulations.
  
  See Also:
  
  getAllCriteria()
- getSearchCriterion
```
public SearchCriterion getSearchCriterion()
```
  Returns the first (and presumably only) SearchCriterion in this location, if any.
  
  Returns:
  
  A SearchCriterion if present; null otherwise.
  
  See Also:
  
  removeSearchCriteria()
- removeSearchCriteria
```
public Location removeSearchCriteria()
```
  Removes all SearchCriterion instances from the list of Criterion objects that make up this location.
  
  Returns:
  
  This Location instance; useful for chained manipulations.
  
  See Also:
  
  getSearchCriterion()
- getCriterion
```
public Criterion getCriterion(String attribute)
```
  Returns the first Criterion instance that operates on the attribute with the given name, if any.
  
  Parameters:
  
  attribute - The non-ML name of the attribute on which this criterion operates.
  
  Returns:
  
  The first Criterion that references the specified attribute.
  
  See Also:
  
  getCriteria(String), removeCriteria(String)
- getCriteria
```
public List getCriteria(String attribute)
```
  Returns all Criterion instances that operate on the attribute with the given name.
  
  Parameters:
  
  attribute - The non-ML name of the attribute on which this criterion operates.
  
  Returns:
  
  A (possibly empty) lists that contains all criteria that reference the specified attribute, in order.
  
  See Also:
  
  getCriterion(String), removeCriteria(String)
- removeCriteria
```
public Location removeCriteria(String attribute)
```
  Removes all Criterion instances that operate on the attribute with the given name.
  
  Parameters:
  
  attribute - The non-ML name of the attribute on which this criterion operates.
  
  Returns:
  
  This Location instance; useful for chained manipulations.
  
  See Also:
  
  getCriterion(String), getCriteria(String)
- getCriterion
```
public Criterion getCriterion(int position)
```
  Returns the Criterion at the given position, if any.
  
  Parameters:
  
  position - The position of the criterion that is the be returned.
  
  Returns:
  
  The Criterion at position position, if any; null otherwise.
  
  See Also:
  
  removeCriterion(int)
- removeCriterion
```
public Location removeCriterion(int position)
```
  Removes the Criterion at the given position, if any.
  
  If there is no criterion at the specified location, then the internal state of this Location object remains unaltered.
  
  Parameters:
  
  position - The position from which the criterion should be removed.
  
  Returns:
  
  This Location instance; useful for chained manipulations.
  
  See Also:
  
  getCriterion(int)
- getLastCriterion
```
public Criterion getLastCriterion()
```
  Returns last Criterion from this location, if any.
  
  Returns:
  
  The last Criterion, if any; null otherwise.
  
  See Also:
  
  removeLastCriterion()
- removeLastCriterion
```
public Location removeLastCriterion()
```
  Removes last Criterion from this location, if any.
  
  Returns:
  
  This Location instance; useful for chained manipulations.
  
  See Also:
  
  getLastCriterion()
- size
```
public int size()
```
  Returns the number of Criterion instances contained in this location.
  
  Returns:
  
  The number of criteria that refine this loation.
- equals
```
public boolean equals(Object o)
```
  Important: this method implements a very rudimentary equivalence test. It is not concerned with the ordering of criteria, filters and targets. On the other hand, it only compares individual criteria. I.e., it does not tests whether a set of criteria A is semantically equivalent to some other set of criteria B.
  
  Overrides:
  
  equals in class Object
- hashCode
```
public int hashCode()
```
  Overrides:
  
  hashCode in class Object

Class Location

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Location

Location

Location

Method Detail

isValidAttributeName

parseCriterion

toString

getUniverse

setUniverse

getLocale

setLocale

addCriterion

getAllCriteria

removeAllCriteria

getSearchCriterion

removeSearchCriteria

getCriterion

getCriteria

removeCriteria

getCriterion

removeCriterion

getLastCriterion

removeLastCriterion

size

equals

hashCode