service.java

google的gdata api包

   *         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)
      throws IOException, ServiceException {
    return getEntry(entryUrl, entryClass, null);
  }


  /**
   * Returns a GDataRequest instance that can be used to access an
   * entry's contents as a stream, given the URL of the entry.
   *
   * @param entryUrl resource URL for the entry.
   * @return GData request instance that can be used to read the entry.
   * @throws IOException error communicating with the GData service.
   * @throws ServiceException entry request creation failed.
   */
  public GDataRequest createEntryRequest(URL entryUrl)
      throws IOException, ServiceException {
    return createRequest(GDataRequest.RequestType.QUERY, entryUrl, contentType);
  }


  /**
   * 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 com.google.gdata.util.NotModifiedException if the query resource
   *         does not contain entries modified since the specified precondition
   *         date.
   * @throws com.google.gdata.util.ServiceForbiddenException feed does not
   *         support the query.
   * @throws com.google.gdata.util.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 com.google.gdata.util.ServiceForbiddenException feed does not 
   *         support the query.
   * @throws com.google.gdata.util.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 com.google.gdata.util.ParseException error parsing the return entry
   *         data.
   * @throws com.google.gdata.util.ServiceForbiddenException the inserted Entry
   *         has associated media
   *         content and can only be inserted using a media service.
   * @throws ServiceException insert request failed due to system error.
   *
   * @see BaseFeed#getEntryPostLink()
   * @see BaseFeed#insert(BaseEntry)
   */
  @SuppressWarnings("unchecked")
  public <E extends BaseEntry<?>> E insert(URL feedUrl, E entry)
      throws IOException, ServiceException {

    if (entry == null) {
      throw new NullPointerException("Must supply entry");
    }

    InputStream resultStream = null;
    try {
      GDataRequest request;
      request = createInsertRequest(feedUrl);
      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();
      return (E) parseEntry(entry.getClass(), resultStream);

    } 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 com.google.gdata.data.batch.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 com.google.gdata.util.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)
   */
  @SuppressWarnings("unchecked")
  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 = (F)
          BaseFeed.readFeed(new ParseSource(resultStream), inputFeed.getClass(),
              extProfile);
      resultFeed.setService(this);

      // Detect BatchInterrupted
      int count = resultFeed.getEntries().size();
      if (count > 0) {
        BaseEntry<?> entry = 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 com.google.gdata.util.ParseException error parsing the updated 
   *         entry data.
   * @throws ServiceException update request failed due to system error.
   *
   * @see BaseEntry#getEditLink()
   * @see BaseEntry#update()
   */
  @SuppressWarnings("unchecked")
  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();
      return (E) parseEntry(entry.getClass(), resultStream);

    } 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 com.google.gdata.util.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);
  }
}