service.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.util.common.xml.XmlWriter;
import com.google.gdata.client.batch.BatchInterruptedException;
import com.google.gdata.client.http.HttpGDataRequest;
import com.google.gdata.data.BaseEntry;
import com.google.gdata.data.BaseFeed;
import com.google.gdata.data.DateTime;
import com.google.gdata.data.ExtensionProfile;
import com.google.gdata.data.Feed;
import com.google.gdata.data.batch.BatchInterrupted;
import com.google.gdata.data.batch.BatchStatus;
import com.google.gdata.data.batch.BatchUtils;
import com.google.gdata.data.introspection.ServiceDocument;
import com.google.gdata.util.ContentType;
import com.google.gdata.util.ParseException;
import com.google.gdata.util.ResourceNotFoundException;
import com.google.gdata.util.ServiceException;
import com.google.gdata.util.ServiceForbiddenException;
import com.google.gdata.util.NotModifiedException;

import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.io.OutputStreamWriter;
import java.io.Writer;
import java.net.URL;

/**
 * The Service class represents a client connection to a GData service.
 * It encapsulates all protocol-level interactions with the GData server
 * and acts as a helper class for higher level entities (feeds, entries,
 * etc) that invoke operations on the server and process their results.
 * <p>
 * This class provides the base level common functionality required to
 * access any GData service.  It is also designed to act as a base class
 * that can be customized for specific types of GData services.  Examples
 * of supported customizations include:
 * <ul>
 * <li><b>Authentication</b> - implementating a custom authentication
 * mechanism for services that require authentication and use something
 * other than HTTP basic or digest authentication.
 * <li><b>Extensions</b> - define expected ExtensionPoints and Extensions
 * with the {@link ExtensionProfile} associated with the service to allow
 * Atom/RSS extension elements to be automatically converted to/from the
 * {@link Feed}/{@link com.google.gdata.data.Entry} object model.
 * </ul>
 *
 * 
 */
public class Service {


  private static final String SERVICE_VERSION =
    "GData-Java/" + Service.class.getPackage().getImplementationVersion();

  /**
   * The GDataRequest interface represents a streaming connection to a
   * GData service that can be used either to send request data to the
   * service using an OutputStream or to receive response data from the
   * service as an InputStream.   The calling client then has full control
   * of the request data generation and response data parsing.  This can
   * be used to integrate GData services with an external Atom or RSS
   * parsing library, such as Rome.
   * <p>
   * A GDataRequest instance will be returned by the streaming client
   * APIs of the Service class.  The basic usage pattern is:
   * <p>
   * <pre>
   * GDataRequest request = ...     // createXXXRequest API call
   * try {
   *    OutputStream requestStream = request.getRequestStream();
   *    // stream request data, if any
   *
   *    request.execute()                // execute the request
   *
   *    InputStream responseStream = request.getResponseStream();
   *    // process the response data, if any
   * }
   * catch (IOException ioe) {
   *    // handle errors writing to / reading from server
   * } catch (ServiceException se) {
   *    // handle service invocation errors
   * }
   * </pre>
   *
   * @see Service#createEntryRequest(URL)
   * @see Service#createFeedRequest(URL)
   * @see Service#createInsertRequest(URL)
   * @see Service#createUpdateRequest(URL)
   * @see Service#createDeleteRequest(URL)
   */
  public interface GDataRequest {


    /**
     * The RequestType enumeration defines the set of expected GData
     * request types.  These correspond to the four operations of the
     * GData protocol:
     * <ul>
     * <li><b>QUERY</b> - query a feed, entry, or description document.</li>
     * <li><b>INSERT</b> - insert a new entry into a feed.</li>
     * <li><b>UPDATE</b> - update an existing entry within a feed.</li>
     * <li><b>DELETE</b> - delete an existing entry within a feed.</li>
     * <li><b>BATCH</b> - execute several insert/update/delete operations</li>
     * </ul>
     */
    public enum RequestType {
      QUERY, INSERT, UPDATE, DELETE, BATCH
    }


    /**
     * Sets the number of milliseconds to wait for a connection to the
     * remote GData service before timing out.
     *
     * @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);


    /**
     * Sets the number of milliseconds to wait for a response from the
     * remote GData service before timing out.
     *
     * @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);


    /**
     * Sets the If-Modified-Since date precondition to be applied to the
     * request.  If this precondition is set, then the request will be
     * performed only if the target resource has been modified since the
     * specified date; otherwise, a {@code NotModifiedException} will be
     * thrown.   The default value is {@code null}, indicating no
     * precondition.
     *
     * @param conditionDate the date that should be used to limit the
     *          operation on the target resource.  The operation will only
     *          be performed if the resource has been modified later than
     *          the specified date.
     */
    public void setIfModifiedSince(DateTime conditionDate);

    /**
     * Returns a stream that can be used to write request data to the
     * GData service.
     *
     * @return OutputStream that can be used to write GData request data.
     * @throws IOException error obtaining the request output stream.
     */
    public OutputStream getRequestStream() throws IOException;

    /**
     * Executes the GData service request.
     *
     * @throws IOException error writing to or reading from GData service.
     * @throws ServiceForbiddenException request is not valid for the
     *                                   target resource.
     * @throws ResourceNotFoundException invalid request target resource.
     * @throws ServiceException system error executing request.
     */
    public void execute() throws IOException, ServiceException;

    /**
     * Returns a stream that can be used to read response data from the
     * GData service.
     * <p>
     * <b>The caller is responsible for ensuring that the response stream is
     * properly closed after the response has been read.</b>
     *
     * @return InputStream providing access to GData response data.
     * @throws IllegalStateException attempt to read response without
     *                               first calling {@link #execute()}.
     * @throws IOException error obtaining the response input stream.
     */
    public InputStream getResponseStream() throws IOException;
  }


  /**
   * The GDataRequestFactory interface defines a basic factory interface
   * for constructing a new GDataRequest interface.
   */
  public interface GDataRequestFactory {

    /**
     * Set a header that will be included in all requests
     * @param header the name of the header
     * @param value the value of the hdear
     */
    public void setHeader(String header, String value);

    /**
     * Set a header that will be included in all requests and do
     * not log the value.  Useful for values that are sensitive or
     * related to security.
     * @param header the name of the header
     * @param value the value of the header
     */
    public void setPrivateHeader(String header, String value);
    /**
     * Creates a new GDataRequest instance of the specified RequestType.
     */
    public GDataRequest getRequest(GDataRequest.RequestType type,
                                   URL requestUrl,
                                   ContentType contentType)
      throws IOException, ServiceException;
  }


  /**
   * Constructs a new Service instance that is configured to accept arbitrary
   * extension data within feed or entry elements.
   */
  public Service() {

    // Set the default User-Agent value for requests
    requestFactory.setHeader("User-Agent", getServiceVersion());

    // The default extension profile is configured to accept arbitrary XML
    // at the feed or entry level.   A client never wants to lose any
    // foreign markup, so capture everything even if not explicitly
    // understood.
    new Feed().declareExtensions(extProfile);
  }


  /**
   * Returns information about the service version.
   */
  public String getServiceVersion() {  return SERVICE_VERSION; }



  protected ExtensionProfile extProfile = new ExtensionProfile();

  /**
   * 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 extProfile) {
    this.extProfile = extProfile;
  }

  /**
   * 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 contentType)
      throws IOException, ServiceException {