appsforyourdomainclient.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 sample.appsforyourdomain;

import sample.util.SimpleCommandLineParser;

import com.google.gdata.client.appsforyourdomain.AppsForYourDomainQuery;
import com.google.gdata.client.appsforyourdomain.EmailListRecipientService;
import com.google.gdata.client.appsforyourdomain.EmailListService;
import com.google.gdata.client.appsforyourdomain.NicknameService;
import com.google.gdata.client.appsforyourdomain.UserService;
import com.google.gdata.data.Link;
import com.google.gdata.data.appsforyourdomain.AppsForYourDomainErrorCode;
import com.google.gdata.data.appsforyourdomain.AppsForYourDomainException;
import com.google.gdata.data.appsforyourdomain.EmailList;
import com.google.gdata.data.appsforyourdomain.Login;
import com.google.gdata.data.appsforyourdomain.Nickname;
import com.google.gdata.data.appsforyourdomain.Name;
import com.google.gdata.data.appsforyourdomain.Quota;
import com.google.gdata.data.appsforyourdomain.provisioning.EmailListEntry;
import com.google.gdata.data.appsforyourdomain.provisioning.EmailListFeed;
import com.google.gdata.data.appsforyourdomain.provisioning.EmailListRecipientEntry;
import com.google.gdata.data.appsforyourdomain.provisioning.EmailListRecipientFeed;
import com.google.gdata.data.appsforyourdomain.provisioning.NicknameEntry;
import com.google.gdata.data.appsforyourdomain.provisioning.NicknameFeed;
import com.google.gdata.data.appsforyourdomain.provisioning.UserEntry;
import com.google.gdata.data.appsforyourdomain.provisioning.UserFeed;
import com.google.gdata.data.extensions.Who;
import com.google.gdata.util.ServiceException;

import java.io.IOException;
import java.net.URL;
import java.util.Iterator;
import java.util.Random;
import java.util.logging.Level;
import java.util.logging.Logger;

/**
 * This is the client library for the Google Apps for Your Domain GData API.
 * It shows how the AppsForYourDomainService can be used to manage users on a 
 * domain.  This class contains a number of methods which can be used to
 * create, update, retrieve, and delete entities such as users, email lists
 * and nicknames.  Also included is sample usage of the client library.   
 * 
 */
public class AppsForYourDomainClient {

  private static final Logger LOGGER = Logger.getLogger(
      AppsForYourDomainClient.class.getName());

  private static final String APPS_FEEDS_URL_BASE =
    "https://www.google.com/a/feeds/";
  
  protected static final String SERVICE_VERSION = "2.0";

  protected final String domainUrlBase;

  protected EmailListRecipientService emailListRecipientService;
  protected EmailListService emailListService;
  protected NicknameService nicknameService;
  protected UserService userService;


  private String domain;

  /**
   * Constructs an AppsForYourDomainClient for the given domain using the
   * given admin credentials.
   *
   * @param adminEmail An admin user's email address such as [e-mail]
   * @param adminPassword The admin's password
   * @param domain The domain to administer
   */
  public AppsForYourDomainClient(String adminEmail, String adminPassword,
      String domain) throws Exception {

    this.domain = domain;
    domainUrlBase = APPS_FEEDS_URL_BASE + domain + "/";

    // Configure all of the different Provisioning services
    userService = new UserService(
	"gdata-sample-AppsForYourDomain-UserService");
    userService.setUserCredentials(adminEmail, adminPassword);

    nicknameService = new NicknameService(
	"gdata-sample-AppsForYourDomain-NicknameService");
    nicknameService.setUserCredentials(adminEmail, adminPassword);

    emailListService = new EmailListService(
	"gdata-sample-AppsForYourDomain-EmailListService");
    emailListService.setUserCredentials(adminEmail, adminPassword);

    emailListRecipientService = new EmailListRecipientService(
	"gdata-sample-AppsForYourDomain-EmailListRecipientService");
    emailListRecipientService.setUserCredentials(adminEmail, adminPassword);
  }

  /**
   * Driver for the sample.
   */
  public void run() throws Exception {
    String randomFactor =
        Integer.toString(1000 + (new Random()).nextInt(9000));

    // Create a new user.
    String username = "SusanJones-" + randomFactor;
    String givenName = "Susan";
    String familyName = "Jones";
    String password = "123$$abc";

    UserEntry createdUserEntry =
        createUser(username, givenName, familyName, password);

    // Update the user's family name.
    String newFamilyName = "Smith";
    createdUserEntry.getName().setFamilyName(newFamilyName);
    UserEntry updatedUserEntry = updateUser(username, createdUserEntry);

    // Create a nickname for the user.
    String nickname0 = "Susy-" + randomFactor;
    NicknameEntry createdNicknameEntry0 = createNickname(username, nickname0);

    // Create another nickname for the user.
    String nickname1 = "Suse-" + randomFactor;
    NicknameEntry createdNicknameEntry1 = createNickname(username, nickname1);

    // Retrieve the nicknames for user.
    NicknameFeed retrievedNicknameFeed = retrieveNicknames(username);
    StringBuffer nicknames = new StringBuffer();
    Iterator<NicknameEntry> nicknameIterator =
        retrievedNicknameFeed.getEntries().iterator();
    while (nicknameIterator.hasNext()) {
      nicknames.append(nicknameIterator.next().getNickname().getName());
      if (nicknameIterator.hasNext()) {
        nicknames.append(", ");
      }
    }
    LOGGER.log(Level.INFO,
        "User '" + username + "' has the following nicknames: {" +
        nicknames.toString() + "}.");

    // Delete the nicknames.
    deleteNickname(nickname0);
    deleteNickname(nickname1);

    // Create an email list.
    String emailList = "Staff-" + randomFactor;
    EmailListEntry createdEmailListEntry = createEmailList(emailList);

    // Add the user to the email list.
    addRecipientToEmailList(username + "@" + domain, emailList);

    // Add an external email address to the list.
    addRecipientToEmailList("[e-mail]", emailList);

    // Retrieve the email lists for which this user is subscribed.
    EmailListFeed retrievedEmailListFeed = retrieveEmailLists(username);
    StringBuffer emailLists = new StringBuffer();
    Iterator<EmailListEntry> emailListIterator =
        retrievedEmailListFeed.getEntries().iterator();
    while (emailListIterator.hasNext()) {
      emailLists.append(emailListIterator.next().getEmailList().getName());
      if (emailListIterator.hasNext()) {
        emailLists.append(", ");
      }
    }
    LOGGER.log(Level.INFO,
        "User '" + username + "' is in the following emailLists: {" +
        emailLists.toString() + "}.");

    // Delete the email list.
    deleteEmailList(emailList);

    // Delete the user.
    deleteUser(username);

    // Deleting a non-existent user and then catching the Exception.
    String fakeUsername = "SusanJones-fake"; 
    try {
      deleteUser(fakeUsername);
    } catch (AppsForYourDomainException e) {
      if (e.getErrorCode()
	   == AppsForYourDomainErrorCode.EntityDoesNotExist) {

	// Do some post-error processing or logging.
	LOGGER.log(Level.INFO,
	    "Do some post-error processing or logging.");
      }
    }

  }

  /**
   * Creates a new user with an email account.
   *
   * @param username The username of the new user.
   * @param givenName The given name for the new user.
   * @param familyName the family name for the new user.
   * @param password The password for the new user.
   * @return A UserEntry object of the newly created user.
   * @throws AppsForYourDomainException If a Provisioning API specific occurs.
   * @throws ServiceException If a generic GData framework error occurs.
   * @throws IOException If an error occurs communicating with the GData
   * service.
   */
  public UserEntry createUser(String username, String givenName,
      String familyName, String password) throws AppsForYourDomainException, 
      ServiceException, IOException {

    return createUser(username, givenName, familyName, password, null, null);
  }

  /**
   * Creates a new user with an email account.
   *
   * @param username The username of the new user.
   * @param givenName The given name for the new user.
   * @param familyName the family name for the new user.
   * @param password The password for the new user.
   * @param quotaLimitInMb User's quota limit in megabytes.  This field is only
   * used for domains with custom quota limits.
   * @return A UserEntry object of the newly created user.
   * @throws AppsForYourDomainException If a Provisioning API specific occurs.
   * @throws ServiceException If a generic GData framework error occurs.
   * @throws IOException If an error occurs communicating with the GData
   * service.
   */
  public UserEntry createUser(String username, String givenName,
      String familyName, String password, Integer quotaLimitInMb)
      throws AppsForYourDomainException, ServiceException, IOException {
    
    return createUser(username, givenName, familyName, password, null, 
        quotaLimitInMb);
  }

  /**
   * Creates a new user with an email account.
   *
   * @param username The username of the new user.
   * @param givenName The given name for the new user.
   * @param familyName the family name for the new user.
   * @param password The password for the new user.
   * @param passwordHashFunction The name of the hash function to hash the 
   * password
   * @return A UserEntry object of the newly created user.
   * @throws AppsForYourDomainException If a Provisioning API specific occurs.
   * @throws ServiceException If a generic GData framework error occurs.
   * @throws IOException If an error occurs communicating with the GData
   * service.
   */
  public UserEntry createUser(String username, String givenName,
      String familyName, String password, String passwordHashFunction)
      throws AppsForYourDomainException, ServiceException, IOException {
      
      return createUser(username, givenName, familyName, password,
        passwordHashFunction, null);
  }

  /**
   * Creates a new user with an email account.
   *
   * @param username The username of the new user.
   * @param givenName The given name for the new user.
   * @param familyName the family name for the new user.
   * @param password The password for the new user.
   * @param passwordHashFunction Specifies the hash format of the password
   * parameter
   * @param quotaLimitInMb User's quota limit in megabytes.  This field is only
   * used for domains with custom quota limits.
   * @return A UserEntry object of the newly created user.
   * @throws AppsForYourDomainException If a Provisioning API specific occurs.
   * @throws ServiceException If a generic GData framework error occurs.
   * @throws IOException If an error occurs communicating with the GData
   * service.
   */
  public UserEntry createUser(String username, String givenName,
      String familyName, String password, String passwordHashFunction,
      Integer quotaLimitInMb)
      throws AppsForYourDomainException, ServiceException, IOException {

    LOGGER.log(Level.INFO,
        "Creating user '" + username + "'. Given Name: '" + givenName +
        "' Family Name: '" + familyName +
        (passwordHashFunction != null 
            ? "' Hash Function: '" + passwordHashFunction : "") + 
        (quotaLimitInMb != null 
            ? "' Quota Limit: '" + quotaLimitInMb + "'." : "'.")
        );

    UserEntry entry = new UserEntry();
    Login login = new Login();
    login.setUserName(username);
    login.setPassword(password);
    if (passwordHashFunction != null) {
      login.setHashFunctionName(passwordHashFunction);
    }
    entry.addExtension(login);

    Name name = new Name();
    name.setGivenName(givenName);
    name.setFamilyName(familyName);
    entry.addExtension(name);

    if (quotaLimitInMb != null) {
      Quota quota = new Quota();
      quota.setLimit(quotaLimitInMb);
      entry.addExtension(quota);
    }

    URL insertUrl = new URL(domainUrlBase + "user/" + SERVICE_VERSION );
    return userService.insert(insertUrl, entry);
  }

  /**
   * Retrieves a user.
   * 
   * @param username The user you wish to retrieve.
   * @return A UserEntry object of the retrieved user. 
   * @throws AppsForYourDomainException If a Provisioning API specific occurs.
   * @throws ServiceException If a generic GData framework error occurs.
   * @throws IOException If an error occurs communicating with the GData
   * service.
   */
  public UserEntry retrieveUser(String username)
      throws AppsForYourDomainException, ServiceException, IOException {

    LOGGER.log(Level.INFO,
        "Retrieving user '" + username + "'.");

    URL retrieveUrl = new URL(domainUrlBase + "user/" 
	+ SERVICE_VERSION + "/" + username);
    return userService.getEntry(retrieveUrl, UserEntry.class);
  }

  /**
   * Retrieves all users in domain.  This method may be very slow for domains
   * with a large number of users.  Any changes to users, including creations
   * and deletions, which are made after this method is called may or may not be
   * included in the Feed which is returned.
   *
   * @return A UserFeed object of the retrieved users.
   * @throws AppsForYourDomainException If a Provisioning API specific occurs.
   * @throws ServiceException If a generic GData framework error occurs.
   * @throws IOException If an error occurs communicating with the GData
   * service.
   */