Google Data APIs Client Library (1.41.1)



com.google.gdata.client
Class Query

java.lang.Object
  extended by com.google.gdata.client.Query
Direct Known Subclasses:
ActivityQuery, AppsForYourDomainQuery, BlogPostQuery, CalendarQuery, CellQuery, ContactQuery, ContentQuery, DataQuery, DocumentQuery, DocumentQuery, FeatureQuery, GoogleBaseQuery, IssuesQuery, ListQuery, MapQuery, PortfolioQuery, PositionQuery, RecordQuery, SidewikiEntryQuery, SiteQuery, TableQuery, TranslationMemoryQuery, VolumeQuery, YouTubeQuery

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
          The CustomParameter class defines a base representation for custom query parameters.
static class Query.ResultFormat
          Defines all query return formats.
 
Field Summary
static int UNDEFINED
          Magic value indicating that a numeric field is not set.
 
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.
protected  void appendQueryParameter(java.lang.StringBuilder queryBuf, java.lang.String paramName, java.lang.String paramValue)
          Appends specified query (parameter, value) to provided query URL buffer.
 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.net.URL getFeedUrl()
          Returns the feed URL of this query.
 java.lang.String getFields()
          Returns the fields query string that will be used for the query.
 java.lang.String getFullTextQuery()
          Returns the full text query string that will be used for the query.
 java.lang.Integer getIntegerCustomParameter(java.lang.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.
 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, or UNDEFINED if start index has not been set.
 java.lang.String getStringCustomParameter(java.lang.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.
 java.net.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(java.lang.String author)
          Sets the author name or email address used for the query.
 void setFields(java.lang.String fields)
          Sets the "fields" partial selection query parameter.
 void setFullTextQuery(java.lang.String query)
          Sets the full text query string that will be used for the query.
 void setIntegerCustomParameter(java.lang.String name, java.lang.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.
 void setStringCustomParameter(java.lang.String name, java.lang.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.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

UNDEFINED

public static final int UNDEFINED
Magic value indicating that a numeric field is not set.

See Also:
Constant Field Values
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

getFeedUrl

public java.net.URL getFeedUrl()
Returns the feed URL of this query.

Returns:
Feed URL.

setFields

public void setFields(java.lang.String fields)
Sets the "fields" partial selection query parameter.

Parameters:
fields - query value

getFields

public java.lang.String getFields()
Returns the fields query string that will be used for the query.


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 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.

getUpdatedMin

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.

setUpdatedMax

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.

getUpdatedMax

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.

setPublishedMin

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.

getPublishedMin

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.

setPublishedMax

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.

getPublishedMax

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.

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, or UNDEFINED if start index has not been set.


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, 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.


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.

setStrict

public void setStrict(boolean strict)
Sets the strictness of parameter parsing.

Parameters:
strict - true if strict parsing should be enabled for this query.

isStrict

public boolean isStrict()
Returns the strictness setting for query parameter parsing on the server.

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

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.

appendQueryParameter

protected void appendQueryParameter(java.lang.StringBuilder queryBuf,
                                    java.lang.String paramName,
                                    java.lang.String paramValue)
                             throws java.io.UnsupportedEncodingException
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:
java.io.UnsupportedEncodingException

isValidState

public boolean isValidState()
Check if current query state is supported.

Returns:
true if supported.

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.

setStringCustomParameter

public final void setStringCustomParameter(java.lang.String name,
                                           java.lang.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

getStringCustomParameter

public final java.lang.String getStringCustomParameter(java.lang.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

setIntegerCustomParameter

public final void setIntegerCustomParameter(java.lang.String name,
                                            java.lang.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

getIntegerCustomParameter

public final java.lang.Integer getIntegerCustomParameter(java.lang.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