public class

Query

extends Object
java.lang.Object
   ↳ com.google.gdata.client.Query
Known Direct Subclasses
Known Indirect Subclasses

Class Overview

The Query class is a helper class that aids in the construction of a GData query. It provides a simple API and object model that exposes query parameters. Once constructed, the query can be executed against a GData service.

The Query class also acts as a simple base class for GData services that support custom query parameters. These services can subclass the base Query class, add APIs to represent service query parameters, and participate in the Query URI generation process.

See Also

Summary

Nested Classes
class Query.CategoryFilter The CategoryFilter class is used to define sets of category conditions that must be met in order for an entry to match. 
class Query.CustomParameter The CustomParameter class defines a base representation for custom query parameters. 
enum Query.ResultFormat Defines all query return formats. 
Constants
int UNDEFINED Magic value indicating that a numeric field is not set.
Fields
private String author Author name or e-mail address for matched entries.
private List<Query.CategoryFilter> categoryFilters The list of category filters associate with the query.
private List<Query.CustomParameter> customParameters The list of custom parameters associated with the query.
private URL feedUrl Base feed URL against which the query will be applied.
private String fields Fields partial selection query parameter
private int maxResults The maximum number of results to return for the query.
private DateTime publishedMax Maximum published timestamp for matched entries.
private DateTime publishedMin Minimum published timestamp for matched entries.
private String queryString Full-text search query string.
private Query.ResultFormat resultFormat The expected result format for the query.
private int startIndex The start index for query results.
private boolean strict The strictness of the query parameter parsing on the server.
private DateTime updatedMax Maximum updated timestamp for matched entries.
private DateTime updatedMin Minimum updated timestamp for matched entries.
Public Constructors
Query(URL feedUrl)
Constructs a new Query object that targets a feed.
Public Methods
void addCategoryFilter(Query.CategoryFilter categoryFilter)
Adds a new CategoryFilter to the query.
void addCustomParameter(Query.CustomParameter customParameter)
Adds a new CustomParameter.
String getAuthor()
Returns the author name or email address used for the query.
List<Query.CategoryFilter> getCategoryFilters()
Returns the current list of CategoryFilters associated with the query.
List<Query.CustomParameter> getCustomParameters()
Returns the list of custom parameters.
List<Query.CustomParameter> getCustomParameters(String name)
Returns the list of custom parameters that match a specified name.
URL getFeedUrl()
Returns the feed URL of this query.
String getFields()
Returns the fields query string that will be used for the query.
String getFullTextQuery()
Returns the full text query string that will be used for the query.
final Integer getIntegerCustomParameter(String name)
Gets an existing Integer custom paramter, with null signifying that the parameter is not specified or not an integer.
int getMaxResults()
Returns the maximum number of results to return for the query, or UNDEFINED if max results has not been set.
DateTime getPublishedMax()
Returns the maximum published timestamp used for this query.
DateTime getPublishedMin()
Returns the minimum published timestamp used for this query.
URI getQueryUri()
Returns the relative query URI that represents only the query parameters without any components related to the target feed.
Query.ResultFormat getResultFormat()
Returns the query result format.
int getStartIndex()
Returns the current start index value for the query, or UNDEFINED if start index has not been set.
final String getStringCustomParameter(String name)
Gets an existing String custom parameter, with null signifying that the parameter is not specified.
DateTime getUpdatedMax()
Returns the maximum updated timestamp used for this query.
DateTime getUpdatedMin()
Returns the minimum updated timestamp used for this query.
URL getUrl()
Returns the Query URL that encapsulates the current state of this query object.
boolean isStrict()
Returns the strictness setting for query parameter parsing on the server.
boolean isValidState()
Check if current query state is supported.
void setAuthor(String author)
Sets the author name or email address used for the query.
void setFields(String fields)
Sets the "fields" partial selection query parameter.
void setFullTextQuery(String query)
Sets the full text query string that will be used for the query.
final void setIntegerCustomParameter(String name, Integer value)
Sets an integer custom paramter, with null signifying to clear the parameter.
void setMaxResults(int maxResults)
Sets the maximum number of results to return for the query.
void setPublishedMax(DateTime publishedMax)
Sets the maximum published timestamp used for the query.
void setPublishedMin(DateTime publishedMin)
Sets the minimum published timestamp used for the query.
void setResultFormat(Query.ResultFormat resultFormat)
Sets the expected query result format.
void setStartIndex(int startIndex)
Sets the start index for query results.
void setStrict(boolean strict)
Sets the strictness of parameter parsing.
final void setStringCustomParameter(String name, String value)
Sets a string custom parameter, with null signifying to clear the parameter.
void setUpdatedMax(DateTime updatedMax)
Sets the maximum updated timestamp used for the query.
void setUpdatedMin(DateTime updatedMin)
Sets the minimum updated timestamp used for the query.
Protected Methods
void appendQueryParameter(StringBuilder queryBuf, String paramName, String paramValue)
Appends specified query (parameter, value) to provided query URL buffer.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final int UNDEFINED

Magic value indicating that a numeric field is not set.

Constant Value: -1 (0xffffffff)

Fields

private String author

Author name or e-mail address for matched entries.

private List<Query.CategoryFilter> categoryFilters

The list of category filters associate with the query.

private List<Query.CustomParameter> customParameters

The list of custom parameters associated with the query.

private URL feedUrl

Base feed URL against which the query will be applied.

private String fields

Fields partial selection query parameter

private int maxResults

The maximum number of results to return for the query. A value of UNDEFINED indicates the server can determine the maximum size.

private DateTime publishedMax

Maximum published timestamp for matched entries.

private DateTime publishedMin

Minimum published timestamp for matched entries.

private String queryString

Full-text search query string.

private Query.ResultFormat resultFormat

The expected result format for the query. The default is DEFAULT.

private int startIndex

The start index for query results. A value of UNDEFINED indicates that no start index has been set.

private boolean strict

The strictness of the query parameter parsing on the server. If strict mode is enabled any unknown query parameters will be rejected. The default value is false.

private DateTime updatedMax

Maximum updated timestamp for matched entries.

private DateTime updatedMin

Minimum updated timestamp for matched entries.

Public Constructors

public Query (URL feedUrl)

Constructs a new Query object that targets a feed. The initial state of the query contains no parameters, meaning all entries in the feed would be returned if the query was executed immediately after construction.

Parameters
feedUrl The URL of the feed against which queries will be executed.

Public Methods

public void addCategoryFilter (Query.CategoryFilter categoryFilter)

Adds a new CategoryFilter to the query. For an entry to match the query criteria, it must match against all CategoryFilters that have been associated with the query.

Parameters
categoryFilter

public void addCustomParameter (Query.CustomParameter customParameter)

Adds a new CustomParameter.

Parameters
customParameter The new custom parameter to add.

public String getAuthor ()

Returns the author name or email address used for the query. Only entries with an author whose name or email address match the specified value will be returned.

Returns
  • the name or email address for matched entries. A value of null means no author-based matching.

public List<Query.CategoryFilter> getCategoryFilters ()

Returns the current list of CategoryFilters associated with the query.

Returns
  • list of category filters.

public List<Query.CustomParameter> getCustomParameters ()

Returns the list of custom parameters.

Returns
  • all custom parameters for the query. An empty list will be returned if there are no custom parameters.

public List<Query.CustomParameter> getCustomParameters (String name)

Returns the list of custom parameters that match a specified name.

Parameters
name The name value to match for returned parameters.
Returns
  • all parameters that have the specified name. An empty list will be returned if there are no matching parameters.

public URL getFeedUrl ()

Returns the feed URL of this query.

Returns
  • Feed URL.

public String getFields ()

Returns the fields query string that will be used for the query.

public String getFullTextQuery ()

Returns the full text query string that will be used for the query.

public final Integer getIntegerCustomParameter (String name)

Gets an existing Integer custom paramter, with null signifying that the parameter is not specified or not an integer.

Parameters
name The name of the parameter
Returns
  • the value of the parameter, or null if it is unspecified or non-integer

public int getMaxResults ()

Returns the maximum number of results to return for the query, or UNDEFINED if max results has not been set.

Note: a GData server may choose to provide fewer results, but will never provide more than the requested maximum.

public DateTime getPublishedMax ()

Returns the maximum published timestamp used for this query. Only entries with a published timestamp earlier than the specified timestamp will be returned.

Returns
  • maximum published timestamp for matched entries. A value of null indicates no maximum timestamp.

public DateTime getPublishedMin ()

Returns the minimum published timestamp used for this query. Only entries with a published time equal to or later than the specified timestamp will be returned.

Returns
  • minimum published timestamp for matched entries. A value of null indicates no minimum timestamp.

public URI getQueryUri ()

Returns the relative query URI that represents only the query parameters without any components related to the target feed. Subclasses of the Query class may override this method to add additional URI path elements or HTTP query parameters to represent service-specific parameters.

Returns
  • URI representing current query.

public Query.ResultFormat getResultFormat ()

Returns the query result format.

Returns
  • ResultFormat associated with the query instance.

public int getStartIndex ()

Returns the current start index value for the query, or UNDEFINED if start index has not been set.

public final String getStringCustomParameter (String name)

Gets an existing String custom parameter, with null signifying that the parameter is not specified.

Parameters
name The name of the parameter
Returns
  • the value, or null if there is no parameter

public DateTime getUpdatedMax ()

Returns the maximum updated timestamp used for this query. Only entries with an updated timestamp earlier than the specified timestamp will be returned.

Returns
  • maximum updated timestamp for matched entries. A value of null indicates no maximum timestamp.

public DateTime getUpdatedMin ()

Returns the minimum updated timestamp used for this query. Only entries with an updated timestamp equal to or later than the specified timestamp will be returned.

Returns
  • minimum updated timestamp for matched entries. A value of null indicates no minimum timestamp.

public URL getUrl ()

Returns the Query URL that encapsulates the current state of this query object.

Returns
  • URL that represents the query against the target feed.

public boolean isStrict ()

Returns the strictness setting for query parameter parsing on the server.

Returns
  • true if strict parsing is enabled for this query.

public boolean isValidState ()

Check if current query state is supported.

Returns
  • true if supported.

public void setAuthor (String author)

Sets the author name or email address used for the query. Only entries with an author whose name or email address match the specified value will be returned.

Parameters
author The name or email address for matched entries. A value of null disables author-based matching.

public void setFields (String fields)

Sets the "fields" partial selection query parameter.

Parameters
fields Query value

public void setFullTextQuery (String query)

Sets the full text query string that will be used for the query.

Parameters
query The full text search query string. A value of null disables full text search for this Query.

public final void setIntegerCustomParameter (String name, Integer value)

Sets an integer custom paramter, with null signifying to clear the parameter.

Parameters
name The parameter name
value The value to set it to

public void setMaxResults (int maxResults)

Sets the maximum number of results to return for the query. Note: a GData server may choose to provide fewer results, but will never provide more than the requested maximum.

Parameters
maxResults The maximum number of results to return for the query. A value of zero indicates that the server is free to determine the maximum value.
Throws
IllegalArgumentException if the provided value is less than zero.

public void setPublishedMax (DateTime publishedMax)

Sets the maximum published timestamp used for the query. Only entries with a published time earlier than the specified timestamp will be returned.

Parameters
publishedMax Maximum published timestamp for matched entries. A value of null disables maximum timestamp filtering.

public void setPublishedMin (DateTime publishedMin)

Sets the minimum published timestamp used for the query. Only entries with a published time equal to or later than the specified timestamp will be returned.

Parameters
publishedMin Minimum published timestamp for matched entries. A value of null disables minimum timestamp filtering.

public void setResultFormat (Query.ResultFormat resultFormat)

Sets the expected query result format.

Parameters
resultFormat ResultFormat value indicating the desired format.

public void setStartIndex (int startIndex)

Sets the start index for query results. This is a 1-based index.

Parameters
startIndex The start index for query results.
Throws
IllegalArgumentException if index is less than or equal to zero.

public void setStrict (boolean strict)

Sets the strictness of parameter parsing.

Parameters
strict True if strict parsing should be enabled for this query.

public final void setStringCustomParameter (String name, String value)

Sets a string custom parameter, with null signifying to clear the parameter.

Parameters
name The name of the parameter
value The value to set it to

public void setUpdatedMax (DateTime updatedMax)

Sets the maximum updated timestamp used for the query. Only entries with an updated timestamp earlier than the specified timestamp will be returned.

Parameters
updatedMax Maximum updated timestamp for matched entries. A value of null disables maximum timestamp filtering.

public void setUpdatedMin (DateTime updatedMin)

Sets the minimum updated timestamp used for the query. Only entries with an updated timestamp equal to or later than the specified timestamp will be returned.

Parameters
updatedMin Minimum updated timestamp for matched entries. A value of null disables minimum timestamp filtering.

Protected Methods

protected void appendQueryParameter (StringBuilder queryBuf, String paramName, String paramValue)

Appends specified query (parameter, value) to provided query URL buffer.

Parameters
queryBuf Base URI buffer to append to.
paramName Query parameter name.
paramValue Query parameter value.
Throws
UnsupportedEncodingException