service.java

google的gdata api包

  /**
   * Returns the {@link ExtensionProfile} that defines any expected extensions
   * to the base RSS/Atom content model.
   */
  public ExtensionProfile getExtensionProfile() {
    return extProfile;
  }

  /**
   * Sets the {@link ExtensionProfile} that defines any expected extensions
   * to the base RSS/Atom content model.
   */
  public void setExtensionProfile(ExtensionProfile v) {
    this.extProfile = v;
  }

  /**
   * The GDataRequestFactory associated with this service.  The default is
   * the base HttpGDataRequest Factory class.
   */
  protected GDataRequestFactory requestFactory = new HttpGDataRequest.Factory();


  /**
   * Returns the GDataRequestFactory currently associated with the service.
   */
  public GDataRequestFactory getRequestFactory() {
    return requestFactory;
  }


  /**
   * Sets the GDataRequestFactory currently associated with the service.
   */
  public void setRequestFactory(GDataRequestFactory requestFactory) {
    this.requestFactory = requestFactory;
  }


  /**
   * Creates a new GDataRequest for use by the service.
   */
  public GDataRequest createRequest(GDataRequest.RequestType type,
                                    URL requestUrl,
                                    ContentType inputType)
      throws IOException, ServiceException {

    GDataRequest request =
      requestFactory.getRequest(type, requestUrl, inputType);
    if (connectTimeout >= 0) {
      request.setConnectTimeout(connectTimeout);
    }
    if (readTimeout >= 0) {
      request.setReadTimeout(readTimeout);
    }
    return request;
  }


  /**
   * Content type of data posted to the GData service.
   * Defaults to Atom using UTF-8 character set.
   */
  private ContentType contentType = ContentType.ATOM;

  /**
   * Returns the default ContentType for data associated with this GData
   * service.
   */
  public ContentType getContentType() { return contentType; }


  /**
   * Sets the default ContentType for writing data to the GData service.
   */
  public void setContentType(ContentType contentType) {
    this.contentType = contentType;
  }


  /**
   * Client-configured connection timeout value.  A value of -1 indicates
   * the client has not set any timeout.
   */
  protected int connectTimeout = -1;


  /**
   * Sets the default wait timeout (in milliseconds) for a connection to the
   * remote GData service.
   *
   * @param timeout the read timeout.  A value of zero indicates an
   *        infinite timeout.
   * @throws IllegalArgumentException if the timeout value is negative.
   *
   * @see java.net.URLConnection#setConnectTimeout(int)
   */
  public void setConnectTimeout(int timeout) {
    if (timeout < 0) {
      throw new IllegalArgumentException("Timeout value cannot be negative");
    }
    connectTimeout = timeout;
  }


  /**
   * Client configured read timeout value.  A value of -1 indicates
   * the client has not set any timeout.
   */
  int readTimeout = -1;


  /**
   * Sets the default wait timeout (in milliseconds) for a response from the
   * remote GData service.
   *
   * @param timeout the read timeout.  A value of zero indicates an
   *        infinite timeout.
    @throws IllegalArgumentException if the timeout value is negative.
   *
   * @see java.net.URLConnection#setReadTimeout(int)
   */
  public void setReadTimeout(int timeout) {
    if (timeout < 0) {
      throw new IllegalArgumentException("Timeout value cannot be negative");
    }
    readTimeout = timeout;
  }

  /**
   * Parse an entry of the specified class from an input stream.
   */
  protected <E extends BaseEntry<?>> E parseEntry(Class<E> entryClass,
                                               InputStream entryStream)
      throws IOException, ServiceException {

    E entry = BaseEntry.readEntry(new ParseSource(entryStream), entryClass,
        extProfile);
    entry.setService(this);
    return entry;
  }

  /**
   * Returns the Atom introspection Service Document associated with a
   * particular feed URL.  This document provides service metadata about
   * the set of Atom services associated with the target feed URL.
   *
   * @param feedUrl the URL associated with a feed.   This URL can not include
   *        any query parameters.
   * @param serviceClass the class used to represent a service document.
   *
   * @return ServiceDocument resource referenced by the input URL.
   * @throws IOException error sending request or reading the feed.
   * @throws com.google.gdata.util.ParseException error parsing the returned 
   *         service data.
   * @throws com.google.gdata.util.ResourceNotFoundException invalid feed URL.
   * @throws ServiceException system error retrieving service document.
   */
  public <S extends ServiceDocument> S introspect(URL feedUrl,
                                                  Class<S> serviceClass)
      throws IOException, ServiceException {

    String feedQuery = feedUrl.getQuery();
    if (feedQuery == null || feedQuery.indexOf("alt=atom-service") == -1) {
      char appendChar = (feedQuery == null) ? '?' : '&';
      feedUrl = new URL(feedUrl.toString() + appendChar + "alt=atom-service");
    }

    InputStream responseStream = null;
    GDataRequest request = createFeedRequest(feedUrl);
    try {
      request.execute();
      responseStream = request.getResponseStream();

      S serviceDoc = serviceClass.newInstance();
      serviceDoc.parse(extProfile, responseStream);

      return serviceDoc;

    } catch (InstantiationException e) {
      throw new ServiceException("Unable to create service document instance",
                                 e);
    } catch (IllegalAccessException e) {
      throw new ServiceException("Unable to create service document instance",
                                 e);
    } finally {
      if (responseStream != null) {
        responseStream.close();
      }
    }
  }


  /**
   * Returns the Feed associated with a particular feed URL, if it's
   * been modified since the specified date.
   *
   * @param feedUrl the URL associated with a feed.   This URL can include
   *                GData query parameters.
   * @param feedClass the class used to represent a service Feed.
   * @param ifModifiedSince used to set a precondition date that indicates the
   *          feed should be returned only if it has been modified after the
   *          specified date. A value of {@code null} indicates no precondition.
   * @return Feed resource referenced by the input URL.
   * @throws IOException error sending request or reading the feed.
   * @throws com.google.gdata.util.NotModifiedException if the feed resource has
   *         not been modified since the specified precondition date.
   * @throws com.google.gdata.util.ParseException error parsing the returned
   *         feed data.
   * @throws com.google.gdata.util.ResourceNotFoundException invalid feed URL.
   * @throws ServiceException system error retrieving feed.
   */
  @SuppressWarnings("unchecked")
  public <F extends BaseFeed<?, ?>> F getFeed(URL feedUrl,
                                        Class<F> feedClass,
                                        DateTime ifModifiedSince)
      throws IOException, ServiceException {

    InputStream feedStream = null;
    GDataRequest request = createFeedRequest(feedUrl);
    try {
      request.setIfModifiedSince(ifModifiedSince);
      request.execute();
      feedStream = request.getResponseStream();

      BaseFeed<?, ?> feed =
          BaseFeed.readFeed(new ParseSource(feedStream), feedClass, extProfile);
      feed.setService(this);
      return (F) feed;
    } finally {
      if (feedStream != null) {
        feedStream.close();
      }
    }
  }


  /**
   * Returns the Feed associated with a particular feed URL.
   *
   * @param feedUrl the URL associated with a feed.   This URL can include
   *                GData query parameters.
   * @param feedClass the class used to represent a service Feed.
   * @return Feed resource referenced by the input URL.
   * @throws IOException error sending request or reading the feed.
   * @throws com.google.gdata.util.ParseException error parsing the returned 
   *         feed data.
   * @throws com.google.gdata.util.ResourceNotFoundException invalid feed URL.
   * @throws ServiceException system error retrieving feed.
   */
  public <F extends BaseFeed<?, ?>> F getFeed(URL feedUrl, Class<F> feedClass)
      throws IOException, ServiceException {
    return getFeed(feedUrl, feedClass, null);
  }


  /**
   * Executes a GData query against the target service and returns the
   * resulting feed results via an input stream.
   *
   * @param queryUrl URL that defines target feed and any query parameters.
   * @return GData request instance that can be used to read the feed data.
   * @throws IOException error communicating with the GData service.
   * @throws ServiceException creation of query feed request failed.
   *
   * @see Query#getUrl()
   */
  public GDataRequest createFeedRequest(URL queryUrl)
      throws IOException, ServiceException {
    return createRequest(GDataRequest.RequestType.QUERY, queryUrl, contentType);
  }


  /**
   * Returns an Atom entry instance, given the URL of the entry and an
   * if-modified-since date.
   *
   * @param entryUrl resource URL for the entry.
   * @param entryClass class used to represent service entries.
   * @param ifModifiedSince used to set a precondition date that indicates the
   *          entry should be returned only if it has been modified after the
   *          specified date. A value of {@code null} indicates no precondition.
   * @return the entry referenced by the URL parameter.
   * @throws IOException error communicating with the GData service.
   * @throws com.google.gdata.util.NotModifiedException if the entry resource 
   *         has not been modified
   *          after the specified precondition date.
   * @throws com.google.gdata.util.ParseException error parsing the returned 
   *         entry.
   * @throws com.google.gdata.util.ResourceNotFoundException if the entry URL 
   *         is not valid.
   * @throws com.google.gdata.util.ServiceForbiddenException if the GData 
   *          service cannot
   *          get the entry resource due to access constraints.
   * @throws ServiceException if a system error occurred when retrieving
   *          the entry.
   */
  public <E extends BaseEntry<?>> E getEntry(URL entryUrl,
                                             Class<E> entryClass,
                                             DateTime ifModifiedSince)
      throws IOException, ServiceException {

    InputStream entryStream = null;
    GDataRequest request = createEntryRequest(entryUrl);
    try {

      request.setIfModifiedSince(ifModifiedSince);
      request.execute();
      entryStream = request.getResponseStream();
      return parseEntry(entryClass, entryStream);

    } finally {
      if (entryStream != null) {
        entryStream.close();
      }
    }
  }


  /**
   * Returns an Atom entry instance, given the URL of the entry.
   *
   * @param entryUrl resource URL for the entry.
   * @param entryClass class used to represent service entries.
   * @return the entry referenced by the URL parameter.
   * @throws IOException error communicating with the GData service.
   * @throws com.google.gdata.util.ParseException error parsing the returned 
   *         entry.
   * @throws com.google.gdata.util.ResourceNotFoundException if the entry URL