com.google.gdata.client
Class Query

java.lang.Object
  extended by com.google.gdata.client.Query
Direct Known Subclasses:
CalendarQuery

public class Query
extends java.lang.Object

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:
Service.query(Query, Class)

Nested Class Summary
static 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.
static class Query.CustomParameter
           
static class Query.ResultFormat
          Defines the possible query return formats.
 
Constructor Summary
Query(java.net.URL feedUrl)
          Constructs a new Query object that targets a feed.
 
Method Summary
 void addCategoryFilter(Query.CategoryFilter categoryFilter)
          Adds a new CategoryFilter to the query.
 void addCustomParameter(Query.CustomParameter customParameter)
          Adds a new CustomParameter.
 java.lang.String getAuthor()
          Returns the author name or email address used for the query.
 java.util.List<Query.CategoryFilter> getCategoryFilters()
          Returns the current list of CategoryFilters associated with the query.
 java.util.List<Query.CustomParameter> getCustomParameters()
          Returns the list of custom parameters.
 java.util.List<Query.CustomParameter> getCustomParameters(java.lang.String name)
          Returns the list of custom parameters that match a specified name.
 java.lang.String getFullTextQuery()
          Returns the full text query string that will be used for the query.
 int getMaxResults()
          Returns the maximum number of results to return for the query.
 java.net.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.
 DateTime getUpdatedMax()
          Returns the maximum date used for this query.
 DateTime getUpdatedMin()
          Returns the minimum date used for this query.
 java.net.URL getUrl()
          Returns the Query URL that encapsulates the current state of this query object.
 void setAuthor(java.lang.String author)
          Sets the author name or email address used for the query.
 void setFullTextQuery(java.lang.String query)
          Sets the full text query string that will be used for the query.
 void setMaxResults(int maxResults)
          Sets the maximum number of results to return 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 setUpdatedMax(DateTime updatedMax)
          Sets the maximum date used for the query.
 void setUpdatedMin(DateTime updatedMin)
          Sets the minimum date used for the query.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Query

public Query(java.net.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.
Method Detail

setFullTextQuery

public void setFullTextQuery(java.lang.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.

getFullTextQuery

public java.lang.String getFullTextQuery()
Returns the full text query string that will be used for the query.


addCategoryFilter

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.


getCategoryFilters

public java.util.List<Query.CategoryFilter> getCategoryFilters()
Returns the current list of CategoryFilters associated with the query.

Returns:
list of category filters.

setAuthor

public void setAuthor(java.lang.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.

getAuthor

public java.lang.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.

setUpdatedMin

public void setUpdatedMin(DateTime updatedMin)
Sets the minimum date used for the query. Only entries with an update time equal to or later than the specified date will be returned.

Parameters:
updatedMin - minimum date for matched entries. A value of null disables minimum date filtering.

getUpdatedMin

public DateTime getUpdatedMin()
Returns the minimum date used for this query. Only entries with an update time equal to or later than the specified date will be returned.

Returns:
minimum date for matched entries. A value of null indicates no minimum date.

setUpdatedMax

public void setUpdatedMax(DateTime updatedMax)
Sets the maximum date used for the query. Only entries with an update time earlier than the specified date will be returned.

Parameters:
updatedMax - maximum date for matched entries. A value of null disables maximum date filtering.

getUpdatedMax

public DateTime getUpdatedMax()
Returns the maximum date used for this query. Only entries with an update time earlier than the specified date will be returned.

Returns:
maximum date for matched entries. A value of null indicates no maximum date.

setStartIndex

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:
java.lang.IllegalArgumentException - if index is less than or equal to zero.

getStartIndex

public int getStartIndex()
Returns the current start index value for the query.


setMaxResults

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:
java.lang.IllegalArgumentException - if the provided value is less than zero.

getMaxResults

public int getMaxResults()
Returns 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.


setResultFormat

public void setResultFormat(Query.ResultFormat resultFormat)
Sets the expected query result format.

Parameters:
resultFormat - ResultFormat value indicating the desired format.

getResultFormat

public Query.ResultFormat getResultFormat()
Returns the query result format.

Returns:
ResultFormat associated with the query instance.

addCustomParameter

public void addCustomParameter(Query.CustomParameter customParameter)
Adds a new CustomParameter.

Parameters:
customParameter - the new custom parameter to add.

getCustomParameters

public java.util.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.

getCustomParameters

public java.util.List<Query.CustomParameter> getCustomParameters(java.lang.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.

getQueryUri

public java.net.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.

getUrl

public java.net.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.