query.java

google gdata API 很好用的API

/* Copyright (c) 2006 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.data.Category;
import com.google.gdata.data.DateTime;

import java.net.*;
import java.util.*;

/**
 * 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.
 * <p>
 * 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 int UNDEFINED = -1;


  /**
   * Defines the possible query return formats.
   */
  public static enum ResultFormat {

    ATOM("atom"),
    RSS("rss"),
    JSON("json"),
    ATOM_IN_SCRIPT("atom-in-script"),
    RSS_IN_SCRIPT("rss-in-script"),
    JSON_IN_SCRIPT("json-in-script");

    /**
     * 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>();


  /** 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 ATOM.
   */
  private ResultFormat resultFormat = ResultFormat.ATOM;


  /**
   * 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;
  }


  /**
   * 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.
   * <p>
   * 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.
   * <p>
   * 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 List<Category> categories;


    /** List of categories that returned entries must match. */
    private List<Category> excludeCategories;


    /**
     * Creates an empty category filter.
     */
    public CategoryFilter() {
      categories = new LinkedList<Category>();
      excludeCategories = new LinkedList<Category>();
    }

    /**
     * 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<Category> included,
                          List<Category> excluded) {

      if (included != null) {
        categories = included;
      } else {
        categories = new LinkedList<Category>();
      }
      if (excluded != null) {
        excludeCategories = excluded;
      } else {
        excludeCategories = new LinkedList<Category>();
      }
    }

    /**
     * Creates a simple category filter containing only a single
     * {@link Category}.
     *
     * @param category an initial category to add to the filter.
     */
    public CategoryFilter(Category category) {
      categories.add(category);
    }


    /**
     * Adds a new {@link Category} 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(Category category) {
      categories.add(category);
    }


    /**
     * Adds a new {@link Category} 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(Category category) {
      excludeCategories.add(category);
    }


    private String getQueryString(Category category) {
      StringBuilder sb = new StringBuilder();

      String scheme = category.getScheme();
      if (scheme != null) {
        sb.append(Category.SCHEME_PREFIX);
        sb.append(scheme);
        sb.append(Category.SCHEME_SUFFIX);
      }
      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.
     */
    public String toString() {
      StringBuilder sb = new StringBuilder();
      boolean isFirst = true;
      for (Category category : categories) {

          if (isFirst) {
            isFirst = false;
          } else {
            sb.append("|");
          }
          sb.append(getQueryString(category));
      }
      for (Category 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.
   *