service.java

google的gdata 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.ParseSource;
import com.google.gdata.data.batch.BatchInterrupted;
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.ServiceException;
import com.google.gdata.util.VersionRegistry.Version;

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() +
      "(gzip)";         // Necessary to get GZIP encoded responses
  
  /**
   * The Alpha release of the GData core protocol that was released in
   * May 2006 and is in use for all current GData services.
   */
  public static final Version ALPHA = new Version(Service.class, 1, 0);
  
  /**
   * The upcoming Beta release of the GData core protocol that will bring
   * full alignment with the now standard Atom Publishing Protocol
   * specification, migration to OpenSearch 1.1, and other (TBD) features.
   */
  public static final Version BETA = new Version(Service.class, 2, 0);

  /**
   * 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);

    /**
     * Sets a request header (and logs it, if logging is enabled)
     *
     * @param name the header name
     * @param value the header value
     */
    public void setHeader(String name, String value);

    /**
     * Sets request header (and log just the name but not the value, if
     * logging is enabled)
     *
     * @param name the header name
     * @param value the header value
     */
    public void setPrivateHeader(String name, String value);

    /**
     * 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 com.google.gdata.util.ResourceNotFoundException invalid request 
     *         target resource.
     * @throws ServiceException system error executing request.
     */
    public void execute() throws IOException, ServiceException;

    /**
     * Returns the content type of the GData response.
     * <p>
     *
     * @return ContentType the GData response content type or {@code null}
     *                               if no response content.
     * @throws IllegalStateException attempt to read content type without
     *                               first calling {@link #execute()}.
     * @throws IOException error obtaining the response content type.
     */
    public ContentType getResponseContentType() throws IOException;

    /**
     * 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. If header of
     * the same name was previously set, then replace the previous header
     * value.
     *
     * @param header the name of the header
     * @param value the value of the header, if null, then unset that header.
     */
    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. If header of the same name was previously set,
     * then replace the previous header value.
     *
     * @param header the name of the header
     * @param value the value of the header.  If null, then unset that 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;
  }


  /**
   * Initializes the version information for a specific service type.
   * Subclasses of {@link Service} will generally call this method from within
   * their implementation of {@link #initVersionRegistry()} to bind
   * version information for the associated service.
   * @param version the service version expected by this client library.
   */
  protected static void initServiceVersion(Version version) {
    ClientVersion.init(version);
  }

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

    // Initialize the version registry information for this service (and its
    // subclasses).
    initVersionRegistry();

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

  /**
   * Called at service instantion to initialize the {@link VersionRegistry}
   * information for the service.  Service subclasses should override this
   * method to define service-specific versioning information.
   */
  protected void initVersionRegistry() {
    // Initialize version information for the GData core protocol.
    initServiceVersion(ALPHA);
  }

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



  protected ExtensionProfile extProfile = new ExtensionProfile();