# Google Data APIs Client Library (1.43.0)

## com.google.gdata.client
Class Query

    java.lang.Object
      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, ProjectsQuery, 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