gdata-java-client/java/src/com/google/gdata/client/Query.java at master · google/gdata-java-client

This repository was archived by the owner on Jan 5, 2026. It is now read-only.
918 lines (756 loc) · 25.8 KB
/* Copyright (c) 2008 Google Inc.
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *     http://www.apache.org/licenses/LICENSE-2.0
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
package com.google.gdata.client;
import com.google.gdata.util.common.base.CharEscapers;
import com.google.gdata.data.ICategory;
import com.google.gdata.data.DateTime;
import java.io.UnsupportedEncodingException;
import java.net.MalformedURLException;
import java.net.URI;
import java.net.URISyntaxException;
import java.net.URL;
import java.util.ArrayList;
import java.util.Collections;
import java.util.LinkedList;
import java.util.List;
 * 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 Service#query(Query, Class)
public class Query {
   * Magic value indicating that a numeric field is not set.
  public static final int UNDEFINED = -1;
   * Defines all query return formats.  Return format "json-xd" is
   * not supported.
  public static enum ResultFormat {
    DEFAULT("default"), // default for target resource (Atom or media)
    ATOM("atom"),
    RSS("rss"),
    JSON("json"),
    JSONC("jsonc"),
    ATOM_IN_SCRIPT("atom-in-script"),
    RSS_IN_SCRIPT("rss-in-script"),
    JSON_IN_SCRIPT("json-in-script"),
    JSONC_IN_SCRIPT("jsonc-in-script"),
    JSON_XD("json-xd"),
    ATOM_SERVICE("atom-service");
     * Value to use for the "alt" param.
    private String paramValue;
     * Constructs a new ResultFormat object using a given value to use for the
     * "alt" parameter.
     * @param value value to use for the "alt" parameter.
    private ResultFormat(String value) {
      this.paramValue = value;
     * Returns the value to use for the "alt" parameter.
     * @return value to use for the "alt" parameter.
    public String paramValue() {
      return paramValue;
  /** Base feed URL against which the query will be applied. */
  private URL feedUrl;
  /** The list of category filters associate with the query. */
  private List<CategoryFilter> categoryFilters =
                                new LinkedList<CategoryFilter>();
  /** Fields partial selection query parameter */
  private String fields;
  /** Full-text search query string. */
  private String queryString;
  /** Author name or e-mail address for matched entries. */
  private String author;
  /** Minimum updated timestamp for matched entries. */
  private DateTime updatedMin;
  /** Maximum updated timestamp for matched entries. */
  private DateTime updatedMax;
  /** Minimum published timestamp for matched entries. */
  private DateTime publishedMin;
  /** Maximum published timestamp for matched entries. */
  private DateTime publishedMax;
   * The start index for query results.  A value of {@link #UNDEFINED}
   * indicates that no start index has been set.
  private int startIndex = UNDEFINED;
   * The maximum number of results to return for the query.  A value of
   * {@link #UNDEFINED} indicates the server can determine the maximum size.
  private int maxResults = UNDEFINED;
   * The expected result format for the query.  The default is
   * {@link ResultFormat#DEFAULT}.
  private ResultFormat resultFormat = ResultFormat.DEFAULT;
   * 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 boolean strict = false;
   * The list of custom parameters associated with the query.
  private List<CustomParameter> customParameters =
    new ArrayList<CustomParameter>();
   * 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.
   * @param feedUrl the URL of the feed against which queries will be
   *                executed.
  public Query(URL feedUrl) {
    this.feedUrl = feedUrl;
   * Returns the feed URL of this query.
   * @return Feed URL.
  public URL getFeedUrl() {
    return feedUrl;
   * Sets the "fields" partial selection query parameter.
   * @param fields query value
  public void setFields(String fields) {
    this.fields = fields;
   * Returns the fields query string that will be used for the query.
  public String getFields() {
    return fields;
   * Sets the full text query string that will be used for the query.
   * @param query the full text search query string.  A value of
   *                    {@code null} disables full text search for this Query.
  public void setFullTextQuery(String query) {
    this.queryString = query;
   * Returns the full text query string that will be used for the query.
  public String getFullTextQuery() {
    return queryString;
   * The CategoryFilter class is used  to define sets of category conditions 
   * that must be met in order for an entry to match.
   * The CategoryFilter can contain multiple category criteria (inclusive
   * or exclusive).  If it does contain multiple categories, then the
   * query matches if any one of the category filter criteria is met,
   * i.e. it is a logical 'OR' of the contained category criteria.   
   * To match, an entry must contain at least one included category or 
   * must not contain at least one excluded category.
   * It is also possible to add multiple CategoryFilters to a Query.  In
   * this case, each individual CategoryFilter must be true for an entry 
   * to match, i.e. it is a logical 'AND' of all CategoryFilters.
   * @see Query#addCategoryFilter(CategoryFilter)
  public static class CategoryFilter {
    /** List of categories that returned entries must match. */
    private final List<ICategory> categories;
    public List<ICategory> getCategories() { return categories; }
    /** List of categories that returned entries must match. */
    private final List<ICategory> excludeCategories;
    public List<ICategory> getExcludeCategories() { return excludeCategories; }
     * Creates an empty category filter.
    public CategoryFilter() {
      categories = new LinkedList<ICategory>();
      excludeCategories = new LinkedList<ICategory>();
     * Creates a new category filter using the supplied inclusion and
     * exclusion lists.  A null value for either is equivalent to an
     * empty list.
    public CategoryFilter(List<ICategory> included,
                          List<ICategory> excluded) {
      if (included != null) {
        categories = included;
      } else {
        categories = new LinkedList<ICategory>();
      if (excluded != null) {
        excludeCategories = excluded;
      } else {
        excludeCategories = new LinkedList<ICategory>();
     * Creates a simple category filter containing only a single
     * {@link ICategory}.
     * @param category an initial category to add to the filter.
    public CategoryFilter(ICategory category) {
      this();
      categories.add(category);
     * Adds a new {@link ICategory} to the query, indicating that entries
     * containing the category should be considered to match.
     * @param category the category to add to query parameters.
    public void addCategory(ICategory category) {
      categories.add(category);
     * Adds a new {@link ICategory} to the query, indicating that entries
     * that do not contain the category should be considered to
     * match.
     * @param category the category to add to query parameters.
    public void addExcludeCategory(ICategory category) {
      excludeCategories.add(category);
    private String getQueryString(ICategory category) {
      StringBuilder sb = new StringBuilder();
      String scheme = category.getScheme();
      if (scheme != null) {
        sb.append("{");
        sb.append(scheme);
        sb.append("}");
      sb.append(category.getTerm());
      return sb.toString();
     * Returns a string representation for the category conditions in
     * the CategoryFilter, in the format used by a Query URI.
    @Override public String toString() {
      StringBuilder sb = new StringBuilder();
      boolean isFirst = true;
      for (ICategory category : categories) {
          if (isFirst) {
            isFirst = false;
          } else {
            sb.append("|");
          sb.append(getQueryString(category));
      for (ICategory category : excludeCategories) {
          if (isFirst) {
            isFirst = false;
          } else {
            sb.append("|");
          sb.append("-");
          sb.append(getQueryString(category));
      return sb.toString();
   * Adds a new CategoryFilter to the query.   For an entry to match the
   * query criteria, it must match against <b>all</b> CategoryFilters
   * that have been associated with the query.
  public void addCategoryFilter(CategoryFilter categoryFilter) {
    categoryFilters.add(categoryFilter);
   * Returns the current list of CategoryFilters associated with the query.
   * @return list of category filters.
  public List<CategoryFilter> getCategoryFilters() {
    return Collections.unmodifiableList(categoryFilters);
   * 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.
   * @param author the name or email address for matched entries.  A value of
   *               {@code null} disables author-based matching.
  public void setAuthor(String author) {
    this.author = author;
   * 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.
   * @return the name or email address for matched entries.  A value of
   *          {@code null} means no author-based matching.
  public String getAuthor() {
    return this.author;
   * 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.
   * @param updatedMin minimum updated timestamp for matched entries.  A value
   *        of {@code null} disables minimum timestamp filtering.
  public void setUpdatedMin(DateTime updatedMin) {
    this.updatedMin = updatedMin;
   * 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.
   * @return minimum updated timestamp for matched entries.  A value of
   *         {@code null} indicates no minimum timestamp.
  public DateTime getUpdatedMin() {
    return this.updatedMin;
   * Sets the maximum updated timestamp used for the query.  Only entries with
   * an updated timestamp earlier than the specified timestamp will be returned.
   * @param updatedMax maximum updated timestamp for matched entries.  A value
   *        of {@code null} disables maximum timestamp filtering.
  public void setUpdatedMax(DateTime updatedMax) {
    this.updatedMax = updatedMax;
   * Returns the maximum updated timestamp used for this query.   Only entries
   * with an updated timestamp earlier than the specified timestamp will be
   * returned.
   * @return maximum updated timestamp for matched entries.  A value of
   *         {@code null} indicates no maximum timestamp.
  public DateTime getUpdatedMax() {
    return this.updatedMax;
   * 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.
   * @param publishedMin minimum published timestamp for matched entries.  A
   *        value of {@code null} disables minimum timestamp filtering.
  public void setPublishedMin(DateTime publishedMin) {
    this.publishedMin = publishedMin;
   * 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.
   * @return minimum published timestamp for matched entries.  A value of
   *         {@code null} indicates no minimum timestamp.
  public DateTime getPublishedMin() {
    return this.publishedMin;
   * Sets the maximum published timestamp used for the query.  Only entries with
   * a published time earlier than the specified timestamp will be returned.
   * @param publishedMax maximum published timestamp for matched entries.  A
   *        value of {@code null} disables maximum timestamp filtering.
  public void setPublishedMax(DateTime publishedMax) {
    this.publishedMax = publishedMax;
   * Returns the maximum published timestamp used for this query.   Only entries
   * with a published timestamp earlier than the specified timestamp will be
   * returned.
   * @return maximum published timestamp for matched entries.  A value of
   *         {@code null} indicates no maximum timestamp.
  public DateTime getPublishedMax() {
    return this.publishedMax;
   * Sets the start index for query results.  This is a 1-based index.
   * @param startIndex the start index for query results.
   * @throws IllegalArgumentException if index is less than or equal to zero.
  public void setStartIndex(int startIndex) {
    if (startIndex != UNDEFINED && startIndex < 1) {
      throw new IllegalArgumentException("Start index must be positive");
    this.startIndex = startIndex;
   * Returns the current start index value for the query,
   * or {@link #UNDEFINED} if start index has not been set.
  public int getStartIndex() {
    return startIndex;
   * 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.
   * @param 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 setMaxResults(int maxResults) {
    if (maxResults != UNDEFINED && maxResults < 0) {
      throw new IllegalArgumentException("Max results must be zero or larger");
    this.maxResults = maxResults;
   * Returns the maximum number of results to return for the query,
   * or {@link #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 int getMaxResults() {
    return this.maxResults;
   * Sets the expected query result format.
   * @param resultFormat ResultFormat value indicating the desired format.
  public void setResultFormat(ResultFormat resultFormat) {
    this.resultFormat = resultFormat;
   * Returns the query result format.
   * @return ResultFormat associated with the query instance.
  public ResultFormat getResultFormat() {
    return resultFormat;
   * Sets the strictness of parameter parsing.
   * @param strict true if strict parsing should be enabled for this query.
  public void setStrict(boolean strict) {
    this.strict = strict;
   * Returns the strictness setting for query parameter parsing on the server.
   * @return true if strict parsing is enabled for this query.
  public boolean isStrict() {
    return strict;
   * The CustomParameter class defines a base representation for custom query
   * parameters.
  public static class CustomParameter {
    private String name;
    private String value;
     * Constructs a new custom parameter with the specified name/value
     * pair.
    public CustomParameter(String name, String value) {
      this.name = name;
      this.value = value;
     * Returns the name of the custom parameter.
    public String getName() { return name; }
     * Returns the value of the custom parameter.
    public String getValue() { return value; }
   * Adds a new CustomParameter.
   * @param customParameter the new custom parameter to add.
  public void addCustomParameter(CustomParameter customParameter) {
    if (customParameter == null) {
      throw new NullPointerException("Null custom parameter");
    customParameters.add(customParameter);
   * Returns the list of custom parameters.
   * @return all custom parameters for the query.  An empty list will be
   *         returned if there are no custom parameters.
  public List<CustomParameter> getCustomParameters() {
    return customParameters;
   * Returns the list of custom parameters that match a specified name.
   * @param name the name value to match for returned parameters.
   * @return all parameters that have the specified name.  An empty list will
   *         be returned if there are no matching parameters.
  public List<CustomParameter> getCustomParameters(String name) {
    List<CustomParameter> matchList = new ArrayList<CustomParameter>();
    for (CustomParameter param : customParameters) {
      if (param.name.equals(name)) {
        matchList.add(param);
    return matchList;
   * Appends specified query (parameter, value) to provided query URL buffer.
   * @param queryBuf    base URI buffer to append to.
   * @param paramName   query parameter name.
   * @param paramValue  query parameter value.
  protected void appendQueryParameter(StringBuilder queryBuf, String paramName,
      String paramValue) throws UnsupportedEncodingException {
    queryBuf.append(queryBuf.length() != 0 ? '&' : '?');
    queryBuf.append(paramName);
    queryBuf.append("=");
    queryBuf.append(paramValue);
   * Check if current query state is supported.
   * @return <code>true</code> if supported.
  public boolean isValidState() {
    // Check if requested ResultFormat is supported
    return (resultFormat != ResultFormat.JSON_XD);
   * 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.
   * @return URI representing current query.
  public URI getQueryUri() {
    if (!isValidState()) {
      throw new IllegalStateException("Unsupported Query");
    StringBuilder pathBuf = new StringBuilder();
      if (categoryFilters.size() != 0) {
        pathBuf.append("-");   // signals beginning of query path elements
        for (CategoryFilter categoryFilter : categoryFilters) {
          pathBuf.append("/");
          pathBuf.append(
              CharEscapers.uriEscaper().escape(categoryFilter.toString()));
      StringBuilder queryBuf = new StringBuilder();
      if (queryString != null) {
        appendQueryParameter(queryBuf, GDataProtocol.Query.FULL_TEXT,
            CharEscapers.uriEscaper().escape(queryString));
      if (author != null) {
        appendQueryParameter(queryBuf, GDataProtocol.Query.AUTHOR,
            CharEscapers.uriEscaper().escape(author));
      if (resultFormat != ResultFormat.DEFAULT) {
        appendQueryParameter(queryBuf, GDataProtocol.Parameter.ALT, 
            resultFormat.paramValue());
      if (updatedMin != null) {
        appendQueryParameter(queryBuf, GDataProtocol.Query.UPDATED_MIN,
            CharEscapers.uriEscaper().escape(updatedMin.toString()));
      if (updatedMax != null) {
        appendQueryParameter(queryBuf, GDataProtocol.Query.UPDATED_MAX,
            CharEscapers.uriEscaper().escape(updatedMax.toString()));
      if (publishedMin != null) {
        appendQueryParameter(queryBuf, GDataProtocol.Query.PUBLISHED_MIN,
            CharEscapers.uriEscaper().escape(publishedMin.toString()));
      if (publishedMax != null) {
        appendQueryParameter(queryBuf, GDataProtocol.Query.PUBLISHED_MAX,
            CharEscapers.uriEscaper().escape(publishedMax.toString()));
      if (startIndex != UNDEFINED) {
        appendQueryParameter(queryBuf, GDataProtocol.Query.START_INDEX,
            Integer.toString(startIndex));
      if (maxResults != UNDEFINED) {
        appendQueryParameter(queryBuf, GDataProtocol.Query.MAX_RESULTS,
            Integer.toString(maxResults));
      if (fields != null) {
        appendQueryParameter(queryBuf, GDataProtocol.Query.FIELDS,
            CharEscapers.uriEscaper().escape(fields));
      if (strict) {
        appendQueryParameter(queryBuf, GDataProtocol.Parameter.STRICT, "true");
      for (CustomParameter customParameter : customParameters) {
        appendQueryParameter(queryBuf,
            CharEscapers.uriEscaper().escape(customParameter.name),
            CharEscapers.uriEscaper().escape(customParameter.value));
      return new URI(pathBuf.toString() + queryBuf.toString());
    } catch (UnsupportedEncodingException uee) {
      throw new IllegalStateException("Unable to encode query URI", uee);
    } catch (URISyntaxException use) {
      // This would indicate a programming error above, not user error
      throw new IllegalStateException("Unable to construct query URI", use);
   * Returns the Query URL that encapsulates the current state of this
   * query object.
   * @return URL that represents the query against the target feed.
  public URL getUrl() {
      String queryUri = getQueryUri().toString();
      if (queryUri.length() == 0) {
        return feedUrl;
      // Build the full query URL.  An earlier implementation of this
      // was done using URI.resolve(), but there are issues if both the
      // base and relative URIs contain path components (the last path
      // element on the base will be removed).
      String feedRoot = feedUrl.toString();
      StringBuilder urlBuf = new StringBuilder(feedRoot);
      if (!feedRoot.endsWith("/") && !queryUri.startsWith("?")) {
        urlBuf.append('/');
      urlBuf.append(queryUri);
      return new URL(urlBuf.toString());
    // Since we are combining a valid URL and a valid URI,
    // any exception thrown below is not a user error.
    } catch (MalformedURLException mue) {
      throw new IllegalStateException("Unable to create query URL", mue);
   * Sets a string custom parameter, with null signifying to clear the
   * parameter.
   * @param name the name of the parameter
   * @param value the value to set it to
  public final void setStringCustomParameter(String name, String value) {
    List<CustomParameter> customParams = getCustomParameters();
    for (CustomParameter existingValue : getCustomParameters(name)) {
      customParams.remove(existingValue);
    if (value != null) {
      customParams.add(new CustomParameter(name, value));
   * Gets an existing String custom parameter, with null signifying that the
   * parameter is not specified.
   * @param name the name of the parameter
   * @return the value, or null if there is no parameter
  public final String getStringCustomParameter(String name) {
    List<CustomParameter> params = getCustomParameters(name);
    if (params.size() == 0) {
      return null;
    } else {
      return params.get(0).getValue();
   * Sets an integer custom paramter, with null signifying to clear the
   * parameter.
   * @param name the parameter name
   * @param value the value to set it to
  public final void setIntegerCustomParameter(String name, Integer value) {
    if (value == null) {
      setStringCustomParameter(name, null);
    } else {
      setStringCustomParameter(name, value.toString());
   * Gets an existing Integer custom paramter, with null signifying that
   * the parameter is not specified or not an integer.
   * @param name the name of the parameter
   * @return the value of the parameter, or null if it is unspecified
   *         or non-integer
  public final Integer getIntegerCustomParameter(String name) {
    String strValue = getStringCustomParameter(name);
    Integer intValue;
    if (strValue != null) {
      try {
        intValue = Integer.valueOf(Integer.parseInt(strValue));
      } catch (NumberFormatException nfe) {
        intValue = null;
    } else {
      intValue = null;
    return intValue;
Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FilesExpand file tree

Query.java

Latest commit

History

Query.java

File metadata and controls
