service.java

google gdata API 很好用的API

  /**
   * Executes a GData query against the target service and returns the
   * {@link Feed} containing entries that match the query result, if
   * it's been modified since the specified date.
   *
   * @param query Query instance defining target feed and query parameters.
   * @param feedClass the Class used to represent a service Feed.
   * @param ifModifiedSince used to set a precondition date that indicates the
   *          query result feed should be returned only if contains entries
   *          that have been modified after the specified date.  A value of
   *          {@code null} indicates no precondition.
   * @throws IOException error communicating with the GData service.
   * @throws NotModifiedException if the query resource does not contain
   *          entries modified since the specified precondition date.
   * @throws ServiceForbiddenException feed does not support the query.
   * @throws ParseException error parsing the returned feed data.
   * @throws ServiceException query request failed.
   */
  public <F extends BaseFeed> F query(Query query,
                                      Class<F> feedClass,
                                      DateTime ifModifiedSince)
      throws IOException, ServiceException {

    // A query is really same as getFeed against the combined feed + query URL
    return getFeed(query.getUrl(), feedClass, ifModifiedSince);
  }


  /**
   * Executes a GData query against the target service and returns the
   * {@link Feed} containing entries that match the query result.
   *
   * @param query Query instance defining target feed and query parameters.
   * @param feedClass the Class used to represent a service Feed.
   * @throws IOException error communicating with the GData service.
   * @throws ServiceForbiddenException feed does not support the query.
   * @throws ParseException error parsing the returned feed data.
   * @throws ServiceException query request failed.
   */
  public <F extends BaseFeed> F query(Query query, Class<F> feedClass)
      throws IOException, ServiceException {

    // A query is really same as getFeed against the combined feed + query URL
    return query(query, feedClass, null);
  }



  /**
   * Inserts a new {@link com.google.gdata.data.Entry} into a feed associated
   * with the target service.  It will return the inserted Entry, including
   * any additional attributes or extensions set by the GData server.
   *
   * @param feedUrl the POST URI associated with the target feed.
   * @param entry the new entry to insert into the feed.
   * @return the newly inserted Entry returned by the service.
   * @throws IOException error communicating with the GData service.
   * @throws ParseException error parsing the return entry data.
   * @throws ServiceException insert request failed due to system error.
   *
   * @see BaseFeed#getEntryPostLink()
   * @see BaseFeed#insert(BaseEntry)
   */
  public <E extends BaseEntry> E insert(URL feedUrl, E entry)
      throws IOException, ServiceException {

    InputStream resultStream = null;
    GDataRequest request = createInsertRequest(feedUrl);
    try {
      OutputStream entryStream = request.getRequestStream();
      Writer entryWriter = new OutputStreamWriter(entryStream, "utf-8");
      XmlWriter xw = new XmlWriter(entryWriter);
      entry.generateAtom(xw, extProfile);
      entryWriter.flush();

      request.execute();

      resultStream = request.getResponseStream();
      E insertedEntry;
      try {
        // Cast should be type safe, since inserted entry will match original
        insertedEntry = (E) entry.getClass().newInstance();
      } catch (InstantiationException e) {
        throw new ServiceException("Unable to create feed instance", e);
      } catch (IllegalAccessException e) {
        throw new ServiceException("Unable to create feed instance", e);
      }
      insertedEntry.parseAtom(extProfile, resultStream);
      insertedEntry.setService(this);
      return insertedEntry;

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

  /**
   * Executes several operations (insert, update or delete) on the entries
   * that are part of the input {@link Feed}. It will return another feed that
   * describes what was done while executing these operations.
   *
   * It is possible for one batch operation to fail even though other
   * operations have worked, so this method won't throw a ServiceException
   * unless something really wrong is going on. You need to check the
   * entries in the returned feed to know which operations succeeded
   * and which operations failed (see {@link BatchStatus}
   * and {@link com.google.gdata.data.batch.BatchInterrupted} extensions.)
   *
   * @param feedUrl the POST URI associated with the target feed.
   * @param inputFeed a description of the operations to execute, described
   *   using tags in the batch: namespace
   * @return a feed with the result of each operation in a separate
   *   entry
   * @throws IOException error communicating with the GData service.
   * @throws ParseException error parsing the return entry data.
   * @throws ServiceException insert request failed due to system error.
   * @throws BatchInterruptedException if something really wrong was detected
   *   by the server while parsing the request, like invalid XML data. Some
   *   operations might have succeeded when this exception is thrown. Check
   *   {@link BatchInterruptedException#getFeed()}.
   *
   * @see BaseFeed#getEntryPostLink()
   * @see BaseFeed#insert(BaseEntry)
   */
  public <F extends BaseFeed> F batch(URL feedUrl, F inputFeed)
      throws IOException, ServiceException, BatchInterruptedException {
    InputStream resultStream = null;
    GDataRequest request = createInsertRequest(feedUrl);
    try {
      OutputStream entryStream = request.getRequestStream();
      Writer entryWriter = new OutputStreamWriter(entryStream, "utf-8");
      XmlWriter xw = new XmlWriter(entryWriter);
      inputFeed.generateAtom(xw, extProfile);
      entryWriter.flush();

      request.execute();

      resultStream = request.getResponseStream();
      F resultFeed;
      try {
        // Cast should be type safe, since inserted entry will match original
        resultFeed = (F) inputFeed.getClass().newInstance();
      } catch (InstantiationException e) {
        throw new ServiceException("Unable to create feed instance", e);
      } catch (IllegalAccessException e) {
        throw new ServiceException("Unable to create feed instance", e);
      }
      resultFeed.parseAtom(extProfile, resultStream);
      resultFeed.setService(this);

      // Detect BatchInterrupted
      int count = resultFeed.getEntries().size();
      if (count > 0) {
        BaseEntry entry = (BaseEntry)resultFeed.getEntries().get(count - 1);
        BatchInterrupted interrupted = BatchUtils.getBatchInterrupted(entry);
        if (interrupted != null) {
          throw new BatchInterruptedException(resultFeed, interrupted);
        }
      }

      return resultFeed;

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

  /**
   * Creates a new GDataRequest that can be used to insert a new entry into
   * a feed using the request stream and to read the resulting entry
   * content from the response stream.
   *
   * @param feedUrl the POST URI associated with the target feed.
   * @return GDataRequest to interact with remote GData service.
   * @throws IOException error reading from or writing to the GData service.
   * @throws ServiceException insert request failed.
   */
  public GDataRequest createInsertRequest(URL feedUrl)
      throws IOException, ServiceException {
    return createRequest(GDataRequest.RequestType.INSERT, feedUrl, contentType);
  }

  /**
   * Creates a new GDataRequest that can be used to execute several
   * insert/update/delete operations in one request by writing a
   * feed into the request stream to read a feed containing the
   * result of the batch operations from the response stream.
   *
   * @param feedUrl the POST URI associated with the target feed.
   * @return GDataRequest to interact with remote GData service.
   * @throws IOException error reading from or writing to the GData service.
   * @throws ServiceException insert request failed.
   */
  public GDataRequest createBatchRequest(URL feedUrl)
      throws IOException, ServiceException {
    return createRequest(GDataRequest.RequestType.BATCH, feedUrl, contentType);
  }


  /**
   * Updates an existing {@link com.google.gdata.data.Entry} by writing
   * it to the specified entry edit URL.  The resulting Entry (after update)
   * will be returned.
   *
   * @param entryUrl the edit URL associated with the entry.
   * @param entry the modified Entry to be written to the server.
   * @return the updated Entry returned by the service.
   * @throws IOException error communicating with the GData service.
   * @throws ParseException error parsing the updated entry data.
   * @throws ServiceException update request failed due to system error.
   *
   * @see BaseEntry#getEditLink()
   * @see BaseEntry#update()
   */
  public <E extends BaseEntry> E update(URL entryUrl, E entry)
      throws IOException, ServiceException {

    InputStream resultStream = null;
    GDataRequest request = createUpdateRequest(entryUrl);
    try {
      // Send the entry
      OutputStream entryStream = request.getRequestStream();
      Writer entryWriter = new OutputStreamWriter(entryStream, "utf-8");
      XmlWriter xw = new XmlWriter(entryWriter);
      entry.generateAtom(xw, extProfile);
      entryWriter.flush();

      // Execute the request
      request.execute();

      // Handle the update
      resultStream = request.getResponseStream();
      E updatedEntry;
      try {
        // Cast should be type safe, since update entry will match original
        updatedEntry = (E) entry.getClass().newInstance();
      } catch (InstantiationException e) {
        throw new ServiceException("Unable to create feed instance", e);
      } catch (IllegalAccessException e) {
        throw new ServiceException("Unable to create feed instance", e);
      }
      updatedEntry.parseAtom(extProfile, resultStream);
      updatedEntry.setService(this);
      return updatedEntry;

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

  /**
   * Creates a new GDataRequest that can be used to update an existing
   * Atom entry.   The updated entry content can be written to the
   * GDataRequest request stream and the resulting updated entry can
   * be obtained from the GDataRequest response stream.
   *
   * @param entryUrl the edit URL associated with the entry.
   * @throws IOException error communicating with the GData service.
   * @throws ServiceException creation of update request failed.
   */
  public GDataRequest createUpdateRequest(URL entryUrl)
      throws IOException, ServiceException {

    return createRequest(GDataRequest.RequestType.UPDATE, entryUrl, contentType);
  }


  /**
   * Deletes an existing entry (and associated media content, if any) using the
   * specified edit URL.
   *
   * @param resourceUrl the edit or medit edit url associated with the
   *        resource.
   * @throws IOException error communicating with the GData service.
   * @throws ResourceNotFoundException invalid entry URL.
   * @throws ServiceException delete request failed due to system error.
   */
  public void delete(URL resourceUrl) throws IOException, ServiceException {

    GDataRequest request = createDeleteRequest(resourceUrl);
    request.execute();
  }


  /**
   * Creates a new GDataRequest that can be used to delete an Atom
   * entry.  For delete requests, no input is expected from the request
   * stream nor will any response data be returned.
   *
   * @param entryUrl the edit URL associated with the entry.
   * @throws IOException error communicating with the GData service.
   * @throws ServiceException creation of delete request failed.
   */
  public GDataRequest createDeleteRequest(URL entryUrl)
      throws IOException, ServiceException {

    return createRequest(GDataRequest.RequestType.DELETE, entryUrl, contentType);
  }
}