MailItemService.java

/* Copyright (c) 2008 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.appsforyourdomain.migration;

import com.google.gdata.client.Service;
import com.google.gdata.client.appsforyourdomain.AppsForYourDomainService;
import com.google.gdata.client.batch.BatchInterruptedException;
import com.google.gdata.client.media.MediaService;
import com.google.gdata.data.appsforyourdomain.migration.MailItemFeed;
import com.google.gdata.data.batch.BatchUtils;
import com.google.gdata.util.ServiceException;
import com.google.gdata.util.Version;

import java.io.IOException;
import java.net.MalformedURLException;
import java.net.URL;

/**
 * The MailItemService class is a {@link MediaService} that can upload mail to
 * the Google Apps Email Migration API.
 * 
 * <p>
 * The recommended way to perform mail migration is to issue multipart POST
 * requests, where the first part contains an Atom entry specifying the message
 * properties and labels, and the second part contains the complete RFC822
 * message as UTF-8 text.
 */
public class MailItemService extends MediaService {
  
  public static class Versions {
    
    /**
     * Version 1 of the Email Migration API. This is the initial version of the
     * API and is based upon Version 1 of the GData Protocol.
     */
    public static final Version V1 = new Version(MailItemService.class,
        "1.0", Service.Versions.V1);
    
    /**
     * Version 2 of the Email Migration API. This version of the API adds full
     * compliance with the Atom Publishing Protocol and is based upon Version 2
     * of the GData protocol.
     */
    public static final Version V2 = new Version(MailItemService.class,
        "2.0", Service.Versions.V2);
  }
  
  /**
   * Version 1 is the current default version for MailItemService.
   */
  public static final Version DEFAULT_VERSION = Service.initServiceVersion(
      MailItemService.class, Versions.V1);
  
  /**
   * Domain for sending API requests.
   */
  public static final String APPS_APIS_DOMAIN = "apps-apis.google.com";
  
  /**
   * URL prefix for accessing migration feeds.
   */
  public static final String URL_PREFIX = "/a/feeds/migration/2.0";
  
  /**
   * URL suffix for the mail item batch feed.
   */
  public static final String URL_SUFFIX = "/mail/batch";

  /**
   * Constructs a {@code MailItemService} instance for an application with the
   * name {@code applicationName}.
   * 
   * @param applicationName the name of the client application accessing the
   *        service. Application names should preferably have the format
   *        [company-id]-[app-name]-[app-version]. The name will be used by the
   *        Google servers to monitor the source of authentication.
   */
  public MailItemService(String applicationName) {
    this(applicationName, AppsForYourDomainService.HTTPS_PROTOCOL,
        AppsForYourDomainService.DOMAIN_NAME);
  }
  
  /**
   * Constructs a {@code MailItemService} instance connecting to the service
   * with name {@code serviceName} for an application with the name
   * {@code applicationName}. The service will authenticate at the provided
   * {@code domainName}.
   * 
   * @param applicationName the name of the client application accessing the
   *        service. Application names should preferably have the format
   *        [company-id]-[app-name]-[app-version]. The name will be used by the
   *        Google servers to monitor the source of authentication.
   * @param protocol name of protocol to use for authentication ("http"/"https")
   * @param domainName the name of the domain hosting the login handler
   */
  public MailItemService(String applicationName, String protocol, String domainName) {
    super(AppsForYourDomainService.APPS_SERVICE, applicationName, protocol, domainName);
    
    BatchUtils.declareExtensions(getExtensionProfile());
    new MailItemFeed().declareExtensions(getExtensionProfile());
  }

  /**
   * Inserts one or more MailItem entries in a single batch operation.  Using
   * {@code batch} instead of repeated calls to {@code insert} is helpful in
   * reducing HTTP overhead.
   * 
   * @param domain the domain into which mail is being migrated
   * @param feed a feed containing one or more {@code MailItemEntry} objects,
   *             each of which has been tagged with
   *             {@link BatchUtils#setBatchId(com.google.gdata.data.BaseEntry,
   *             String)}.  The batch operation type of each entry must be
   *             {@code BatchOperationType.INSERT}; however, there should be no
   *             need to call {@code BatchUtils.setBatchOperationType} on each
   *             entry, as this operation is already the default.
   * @return a feed with the result of each operation in a separate
   *         {@code MailItemEntry} object.
   * @throws IOException if an error occurs while communicating with the GData
   *                     service.
   * @throws MalformedURLException if the batch feed URL cannot be constructed.
   * @throws ServiceException if the insert request failed due to system error.
   * @throws BatchInterruptedException if an irrecoverable error 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()}.
   */
  public MailItemFeed batch(String domain, String userName, MailItemFeed feed)
      throws BatchInterruptedException, IOException, MalformedURLException,
      ServiceException {
    URL batchUrl = new URL(AppsForYourDomainService.HTTPS_PROTOCOL + "://" + APPS_APIS_DOMAIN
        + URL_PREFIX + "/" + domain + "/" + userName + URL_SUFFIX);
    return batch(batchUrl, feed);
  }


}