query.java

google gdata API 很好用的API

   * @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.
   */
  public int getStartIndex() {
    return (startIndex == UNDEFINED) ? 1 : 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.  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;
  }

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


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

    StringBuilder pathBuf = new StringBuilder();

    if (categoryFilters.size() != 0) {
      if (pathBuf.length() != 0) { pathBuf.append("/"); }
      pathBuf.append("-");   // signals beginning of query path elements
    }

    for (CategoryFilter categoryFilter : categoryFilters) {
      pathBuf.append("/");
      pathBuf.append(URLEncoder.encode(categoryFilter.toString()));
    }

    StringBuilder queryBuf = new StringBuilder();
    if (queryString != null) {
      queryBuf.append(queryBuf.length() != 0 ? '&' : '?');
      queryBuf.append("q=");
      queryBuf.append(URLEncoder.encode(queryString));
    }

    if (author != null) {
      queryBuf.append(queryBuf.length() != 0 ? '&' : '?');
      queryBuf.append("author=");
      queryBuf.append(URLEncoder.encode(author));
    }

    if (resultFormat != ResultFormat.ATOM) {
      queryBuf.append(queryBuf.length() != 0 ? '&' : '?');
      queryBuf.append("alt=");
      queryBuf.append(resultFormat.paramValue());
    }

    if (updatedMin != null) {
      queryBuf.append(queryBuf.length() != 0 ? '&' : '?');
      queryBuf.append("updated-min=");
      queryBuf.append(updatedMin.toString());
    }

    if (updatedMax != null) {
      queryBuf.append(queryBuf.length() != 0 ? '&' : '?');
      queryBuf.append("updated-max=");
      queryBuf.append(updatedMax.toString());
    }

    if (publishedMin != null) {
      queryBuf.append(queryBuf.length() != 0 ? '&' : '?');
      queryBuf.append("published-min=");
      queryBuf.append(publishedMin.toString());
    }

    if (publishedMax != null) {
      queryBuf.append(queryBuf.length() != 0 ? '&' : '?');
      queryBuf.append("published-max=");
      queryBuf.append(publishedMax.toString());
    }

    if (startIndex != UNDEFINED) {
      queryBuf.append(queryBuf.length() != 0 ? '&' : '?');
      queryBuf.append("start-index=" + startIndex);
    }

    if (maxResults != UNDEFINED) {
      queryBuf.append(queryBuf.length() != 0 ? '&' : '?');
      queryBuf.append("max-results=" + maxResults);
    }

    for (CustomParameter customParameter : customParameters) {
      queryBuf.append(queryBuf.length() != 0 ? '&' : '?');
      queryBuf.append(URLEncoder.encode(customParameter.name));
      queryBuf.append('=');
      queryBuf.append(URLEncoder.encode(customParameter.value));
    }

    try {

      return new URI(pathBuf.toString() + queryBuf.toString());

    } 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() {

    try {
      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;
  }
}