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

import com.google.gdata.client.appsforyourdomain.AppsForYourDomainQuery;
import com.google.gdata.client.appsforyourdomain.AppsGroupsService;
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 sample.util.SimpleCommandLineParser;
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.Name;
import com.google.gdata.data.appsforyourdomain.Nickname;
import com.google.gdata.data.appsforyourdomain.Quota;
import com.google.gdata.data.appsforyourdomain.generic.GenericEntry;
import com.google.gdata.data.appsforyourdomain.generic.GenericFeed;
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.security.SecureRandom;
import java.util.Iterator;
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://apps-apis.google.com/a/feeds/";

  protected static final String SERVICE_VERSION = "2.0";

  protected String domainUrlBase;

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

  /**
   * Public getter for AppsGroupsService
   * @return the groupService
   */
  public AppsGroupsService getGroupService() {
    return groupService;
  }

  protected final String domain;

  protected AppsForYourDomainClient(String domain) {
    this.domain = domain;
    this.domainUrlBase = APPS_FEEDS_URL_BASE + domain + "/";
  }

  /**
   * Constructs an AppsForYourDomainClient for the given domain using the
   * given admin credentials.
   *
   * @param adminEmail An admin user's email address such as admin@domain.com
   * @param adminPassword The admin's password
   * @param domain The domain to administer
   */
  public AppsForYourDomainClient(String adminEmail, String adminPassword,
      String domain) throws Exception {
    this(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);

    groupService = new AppsGroupsService(adminEmail, adminPassword, domain, 
        "gdata-sample-AppsForYourDomain-AppsGroupService");
  }

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

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

    String testGroupName = "discuss_general";
    String testGroupId = "newgroup-" + randomFactor;
    String testGroupDescription = "Discuss";

    String memberUserName = "john.doe." + randomFactor;
    String memberFirstName = "John";
    String memberLastName = "Doe";
    String memberPassword = "123$$$abc";

    String ownerUserName = "jane.doe." + randomFactor;
    String ownerFirstName = "Jane";
    String ownerLastName = "Doe";
    String ownerPassword = "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("jane.doe@externaldomain.com", 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() + "}.");
     //*/
    LOGGER.log(Level.INFO, "Creating users for groups sample run");
    createUser(memberUserName, memberFirstName, memberLastName, memberPassword);
    createUser(ownerUserName, ownerFirstName, ownerLastName, ownerPassword);

    GenericFeed groupsFeed = null;
    GenericEntry groupsEntry = null;
    Iterator<GenericEntry> groupsEntryIterator = null;

    LOGGER.log(Level.INFO, "Creating group: " + testGroupId);
    groupsEntry =
        groupService.createGroup(testGroupId, testGroupName,
            testGroupDescription, "");
    LOGGER.log(Level.INFO, "Group created with following properties:\n"
        + groupsEntry.getAllProperties());

    groupsEntry =
        groupService.addMemberToGroup(testGroupId, memberUserName);
    LOGGER.log(Level.INFO, "Added member: \n" + groupsEntry.getAllProperties());

    groupsEntry = groupService.addOwnerToGroup(testGroupId, ownerUserName);
    LOGGER.log(Level.INFO, "Added owner: \n" + groupsEntry.getAllProperties());

    groupsEntry =
        groupService.updateGroup(testGroupId, testGroupName,
            testGroupDescription + "Updated: ", "");
    LOGGER.log(Level.INFO, "Updated group description:\n"
        + groupsEntry.getAllProperties());

    groupsFeed = groupService.retrieveAllMembers(testGroupId);
    groupsEntryIterator = groupsFeed.getEntries().iterator();

    StringBuffer members = new StringBuffer();

    while (groupsEntryIterator.hasNext()) {
      members.append(groupsEntryIterator.next().getProperty(
          AppsGroupsService.APPS_PROP_GROUP_MEMBER_ID));
      if (groupsEntryIterator.hasNext()) {
        members.append(", ");
      }
    }
    LOGGER.log(Level.INFO, testGroupId + " has these members: "
        + members.toString());

    groupsFeed = groupService.retreiveGroupOwners(testGroupId);
    groupsEntryIterator = groupsFeed.getEntries().iterator();

    StringBuffer owners = new StringBuffer();
    while (groupsEntryIterator.hasNext()) {
      owners.append(groupsEntryIterator.next().getProperty(
          AppsGroupsService.APPS_PROP_GROUP_EMAIL));
      if (groupsEntryIterator.hasNext()) {
        owners.append(", ");
      }
    }

    LOGGER.log(Level.INFO, testGroupName + " has these owners: "
        + owners.toString());
    groupsFeed = groupService.retrieveAllGroups();
    groupsEntryIterator = groupsFeed.getEntries().iterator();

    StringBuffer groups = new StringBuffer();
    while (groupsEntryIterator.hasNext()) {
      groups.append(groupsEntryIterator.next().getProperty(
          AppsGroupsService.APPS_PROP_GROUP_ID));
      if (groupsEntryIterator.hasNext()) {
        groups.append(", ");
      }
    }
    LOGGER.log(Level.INFO, "Domain has these groups:\n" + groups.toString());

    groupsFeed = groupService.retrieveGroups(memberUserName, true);
    groupsEntryIterator = groupsFeed.getEntries().iterator();

    groups = new StringBuffer();
    while (groupsEntryIterator.hasNext()) {
      groups.append(groupsEntryIterator.next().getProperty(
          AppsGroupsService.APPS_PROP_GROUP_ID));
      if (groupsEntryIterator.hasNext()) {
        groups.append(", ");
      }
    }
    LOGGER.log(Level.INFO, memberUserName + " is subscribed to these groups:\n"
        + groups.toString());

    boolean isMember = groupService.isMember(testGroupId, memberUserName);
    LOGGER.log(Level.INFO, memberUserName + " is member of " + testGroupId
        + "?: " + isMember);

    boolean isOwner = groupService.isOwner(testGroupId, ownerUserName);
    LOGGER.log(Level.INFO, ownerUserName + " is owner of " + testGroupId
        + "?: " + isOwner);

    groupService.removeOwnerFromGroup(ownerUserName + "@" + domain,
        testGroupId);
    LOGGER.log(Level.INFO, "Removing " + ownerUserName + " as owner from group "
        + testGroupId);

    groupService.deleteGroup(testGroupId);
    deleteUser(memberUserName);
    deleteUser(ownerUserName);

    // 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.
   */
  public UserFeed retrieveAllUsers()
      throws AppsForYourDomainException, ServiceException, IOException {

    LOGGER.log(Level.INFO,
        "Retrieving all users.");

    URL retrieveUrl = new URL(domainUrlBase + "user/" + SERVICE_VERSION + "/");
    UserFeed allUsers = new UserFeed();
    UserFeed currentPage;
    Link nextLink;

    do {
      currentPage = userService.getFeed(retrieveUrl, UserFeed.class);
      allUsers.getEntries().addAll(currentPage.getEntries());
      nextLink = currentPage.getLink(Link.Rel.NEXT, Link.Type.ATOM);
      if (nextLink != null) {
        retrieveUrl = new URL(nextLink.getHref());
      }
    } while (nextLink != null);

    return allUsers;
  }

  /**
   * Retrieves one page (100) of users in domain.  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.  If the
   * optional startUsername parameter is specified, one page of users is
   * returned which have usernames at or after the startUsername as per ASCII
   * value ordering with case-insensitivity.  A value of null or empty string
   * indicates you want results from the beginning of the list.
   *
   * @param startUsername The starting point of the page (optional).
   * @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.
   */
  public UserFeed retrievePageOfUsers(String startUsername)
      throws AppsForYourDomainException, ServiceException, IOException {

    LOGGER.log(Level.INFO, "Retrieving one page of users"
        + (startUsername != null ? " starting at " + startUsername : "") + ".");

    URL retrieveUrl = new URL(domainUrlBase + "user/" + SERVICE_VERSION + "/");
    AppsForYourDomainQuery query = new AppsForYourDomainQuery(retrieveUrl);
    query.setStartUsername(startUsername);
    return userService.query(query, UserFeed.class);
  }

  /**
   * Updates a user.
   *
   * @param username The user to update.
   * @param userEntry The updated UserEntry for the user.
   * @return A UserEntry object of the newly updated 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 updateUser(String username, UserEntry userEntry)
      throws AppsForYourDomainException, ServiceException, IOException {

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

    URL updateUrl = new URL(domainUrlBase + "user/" + SERVICE_VERSION + "/" + username);
    return userService.update(updateUrl, userEntry);
  }

  /**
   * Deletes a user.
   * 
   * @param username The user you wish to delete.
   * @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 void deleteUser(String username)
      throws AppsForYourDomainException, ServiceException, IOException {

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

    URL deleteUrl = new URL(domainUrlBase + "user/" + SERVICE_VERSION + "/" + username);
    userService.delete(deleteUrl);
  }

  /**
   * Suspends a user. Note that executing this method for a user who is already
   * suspended has no effect.
   * 
   * @param username The user you wish to suspend.
   * @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 suspendUser(String username)
      throws AppsForYourDomainException, ServiceException, IOException {

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

    URL retrieveUrl = new URL(domainUrlBase + "user/" + SERVICE_VERSION + "/" + username);
    UserEntry userEntry = userService.getEntry(retrieveUrl, UserEntry.class);
    userEntry.getLogin().setSuspended(true);

    URL updateUrl = new URL(domainUrlBase + "user/" + SERVICE_VERSION + "/" + username);
    return userService.update(updateUrl, userEntry);
  }

  /**
   * Restores a user. Note that executing this method for a user who is not
   * suspended has no effect.
   * 
   * @param username The user you wish to restore.
   * @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 restoreUser(String username)
      throws AppsForYourDomainException, ServiceException, IOException {

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

    URL retrieveUrl = new URL(domainUrlBase + "user/" + SERVICE_VERSION + "/" + username);
    UserEntry userEntry = userService.getEntry(retrieveUrl, UserEntry.class);
    userEntry.getLogin().setSuspended(false);

    URL updateUrl = new URL(domainUrlBase + "user/" + SERVICE_VERSION + "/" + username);
    return userService.update(updateUrl, userEntry);
  }

  /**
   * Set admin privilege for user. Note that executing this method for a user
   * who is already an admin has no effect.
   * 
   * @param username The user you wish to make an admin.
   * @throws AppsForYourDomainException If a Provisioning API specific error
   *         occurs.
   * @throws ServiceException If a generic GData framework error occurs.
   * @throws IOException If an error occurs communicating with the GData
   *         service.
   */
  public UserEntry addAdminPrivilege(String username)
      throws AppsForYourDomainException, ServiceException, IOException {

    LOGGER.log(Level.INFO, "Setting admin privileges for user '" + username + "'.");

    URL retrieveUrl = new URL(domainUrlBase + "user/" + SERVICE_VERSION + "/" + username);
    UserEntry userEntry = userService.getEntry(retrieveUrl, UserEntry.class);
    userEntry.getLogin().setAdmin(true);

    URL updateUrl = new URL(domainUrlBase + "user/" + SERVICE_VERSION + "/" + username);
    return userService.update(updateUrl, userEntry);
  }

  /**
   * Remove admin privilege for user. Note that executing this method for a user
   * who is not an admin has no effect.
   * 
   * @param username The user you wish to remove admin privileges.
   * @throws AppsForYourDomainException If a Provisioning API specific error
   *         occurs.
   * @throws ServiceException If a generic GData framework error occurs.
   * @throws IOException If an error occurs communicating with the GData
   *         service.
   */
  public UserEntry removeAdminPrivilege(String username)
      throws AppsForYourDomainException, ServiceException, IOException {

    LOGGER.log(Level.INFO, "Removing admin privileges for user '" + username + "'.");

    URL retrieveUrl = new URL(domainUrlBase + "user/" + SERVICE_VERSION + "/" + username);
    UserEntry userEntry = userService.getEntry(retrieveUrl, UserEntry.class);
    userEntry.getLogin().setAdmin(false);

    URL updateUrl = new URL(domainUrlBase + "user/" + SERVICE_VERSION + "/" + username);
    return userService.update(updateUrl, userEntry);
  }

  /**
   * Require a user to change password at next login. Note that executing this
   * method for a user who is already required to change password at next login
   * as no effect.
   * 
   * @param username The user who must change his or her password.
   * @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 forceUserToChangePassword(String username)
      throws AppsForYourDomainException, ServiceException, IOException {

    LOGGER.log(Level.INFO, "Requiring " + username + " to change password at " +
        "next login.");

    URL retrieveUrl = new URL(domainUrlBase + "user/"
        + SERVICE_VERSION + "/" + username);
    UserEntry userEntry = userService.getEntry(retrieveUrl, UserEntry.class);
    userEntry.getLogin().setChangePasswordAtNextLogin(true);

    URL updateUrl = new URL(domainUrlBase + "user/"
        + SERVICE_VERSION + "/" + username);
    return userService.update(updateUrl, userEntry);
  }

  /**
   * Creates a nickname for the username.
   *
   * @param username The user for which we want to create a nickname.
   * @param nickname The nickname you wish to create.
   * @return A NicknameEntry object of the newly created nickname. 
   * @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 NicknameEntry createNickname(String username, String nickname) 
      throws AppsForYourDomainException, ServiceException, IOException {

    LOGGER.log(Level.INFO,
        "Creating nickname '" + nickname +
        "' for user '" + username + "'.");

    NicknameEntry entry = new NicknameEntry();
    Nickname nicknameExtension = new Nickname();
    nicknameExtension.setName(nickname);
    entry.addExtension(nicknameExtension);

    Login login = new Login();
    login.setUserName(username);
    entry.addExtension(login);

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

  /**
   * Retrieves a nickname.
   *
   * @param nickname The nickname you wish to retrieve.
   * @return A NicknameEntry object of the newly created nickname. 
   * @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 NicknameEntry retrieveNickname(String nickname) throws AppsForYourDomainException,
      ServiceException, IOException {
    LOGGER.log(Level.INFO, "Retrieving nickname '" + nickname + "'.");

    URL retrieveUrl = new URL(domainUrlBase + "nickname/" + SERVICE_VERSION + "/" + nickname);
    return nicknameService.getEntry(retrieveUrl, NicknameEntry.class);
  }

  /**
   * Retrieves all nicknames for the given username.
   * 
   * @param username The user for which you want all nicknames.
   * @return A NicknameFeed object with all the nicknames for the 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 NicknameFeed retrieveNicknames(String username)
      throws AppsForYourDomainException, ServiceException, IOException {
    LOGGER.log(Level.INFO,
        "Retrieving nicknames for user '" + username + "'.");

    URL feedUrl = new URL(domainUrlBase + "nickname/" + SERVICE_VERSION);
    AppsForYourDomainQuery query = new AppsForYourDomainQuery(feedUrl);
    query.setUsername(username);
    return nicknameService.query(query, NicknameFeed.class);
  }

  /**
   * Retrieves one page (100) of nicknames in domain.  Any changes to
   * nicknames, including creations and deletions, which are made after
   * this method is called may or may not be included in the Feed which is
   * returned.  If the optional startNickname parameter is specified, one page
   * of nicknames is returned which have names at or after startNickname as per
   * ASCII value ordering with case-insensitivity.  A value of null or empty
   * string indicates you want results from the beginning of the list.
   *
   * @param startNickname The starting point of the page (optional).
   * @return A NicknameFeed object of the retrieved nicknames.
   * @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 NicknameFeed retrievePageOfNicknames(String startNickname)
      throws AppsForYourDomainException, ServiceException, IOException {

    LOGGER.log(Level.INFO, "Retrieving one page of nicknames"
        + (startNickname != null ? " starting at " + startNickname : "") + ".");

    URL retrieveUrl = new URL(
        domainUrlBase + "nickname/" + SERVICE_VERSION + "/");
    AppsForYourDomainQuery query = new AppsForYourDomainQuery(retrieveUrl);
    query.setStartNickname(startNickname);
    return nicknameService.query(query, NicknameFeed.class);
  }

  /**
   * Retrieves all nicknames in domain.  This method may be very slow for
   * domains with a large number of nicknames.  Any changes to nicknames,
   * 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 NicknameFeed object of the retrieved nicknames.
   * @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 NicknameFeed retrieveAllNicknames()
      throws AppsForYourDomainException, ServiceException, IOException {

    LOGGER.log(Level.INFO,
        "Retrieving all nicknames.");

    URL retrieveUrl = new URL(domainUrlBase + "nickname/"
        + SERVICE_VERSION + "/");
    NicknameFeed allNicknames = new NicknameFeed();
    NicknameFeed currentPage;
    Link nextLink;

    do {
      currentPage = nicknameService.getFeed(retrieveUrl, NicknameFeed.class);
      allNicknames.getEntries().addAll(currentPage.getEntries());
      nextLink = currentPage.getLink(Link.Rel.NEXT, Link.Type.ATOM);
      if (nextLink != null) {
        retrieveUrl = new URL(nextLink.getHref());
      }
    } while (nextLink != null);

    return allNicknames;
  }

  /**
   * Deletes a nickname.
   *
   * @param nickname The nickname you wish to delete.
   * @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 void deleteNickname(String nickname)
      throws AppsForYourDomainException, ServiceException, IOException {

    LOGGER.log(Level.INFO, "Deleting nickname '" + nickname + "'.");

    URL deleteUrl = new URL(domainUrlBase + "nickname/" + SERVICE_VERSION + "/" + nickname);
    nicknameService.delete(deleteUrl);
  }

  /**
   * Creates an empty email list.
   *
   * @param emailList The name of the email list you wish to create.
   * @return An EmailListEntry object of the newly created email list.
   * @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.
   * @deprecated Email lists have been replaced by Groups. Use
   *             {@link AppsGroupsService#createGroup(String,String,String,String)} 
   *             with Groups instead.
   */
  @Deprecated
  public EmailListEntry createEmailList(String emailList) 
      throws AppsForYourDomainException, ServiceException, IOException {

    LOGGER.log(Level.INFO,
        "Creating email list '" + emailList + "'.");

    EmailListEntry entry = new EmailListEntry();
    EmailList emailListExtension = new EmailList();
    emailListExtension.setName(emailList);
    entry.addExtension(emailListExtension);

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

  /**
   * Retrieves all email lists in which the recipient is subscribed. Recipient
   * can be given as a username or an email address of a hosted user.
   *
   * @param recipient The email address or username of the recipient.
   * @return An EmailListFeed object containing the email lists.
   * @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.
   * @deprecated Email lists have been replaced by Groups. Use
   *             {@link AppsGroupsService#retrieveGroups(String,boolean)} 
   *             with Groups.instead
   */
  @Deprecated
  public EmailListFeed retrieveEmailLists(String recipient)
      throws AppsForYourDomainException, ServiceException, IOException {

    LOGGER.log(Level.INFO,
        "Retrieving email lists for '" + recipient + "'.");

    URL feedUrl = new URL(domainUrlBase + "emailList/"
        + SERVICE_VERSION);
    AppsForYourDomainQuery query = new AppsForYourDomainQuery(feedUrl);
    query.setRecipient(recipient);

    return emailListService.query(query, EmailListFeed.class);
  }

  /**
   * Retrieves all email lists in domain. This method may be very slow for
   * domains with a large number of email lists. Any changes to email lists,
   * 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 EmailListFeed object of the retrieved email lists.
   * @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.
   * @deprecated Email lists have been replaced by Groups. Use
   *             {@link AppsGroupsService#retrieveAllGroups()}
   *             with Groups instead.
   */
  @Deprecated
  public EmailListFeed retrieveAllEmailLists()
      throws AppsForYourDomainException, ServiceException, IOException {

    LOGGER.log(Level.INFO,
        "Retrieving all email lists.");

    URL retrieveUrl = new URL(domainUrlBase + "emailList/"
        + SERVICE_VERSION + "/");
    EmailListFeed allEmailLists = new EmailListFeed();
    EmailListFeed currentPage;
    Link nextLink;

    do {
      currentPage = emailListService.getFeed(retrieveUrl, EmailListFeed.class);
      allEmailLists.getEntries().addAll(currentPage.getEntries());
      nextLink = currentPage.getLink(Link.Rel.NEXT, Link.Type.ATOM);
      if (nextLink != null) {
        retrieveUrl = new URL(nextLink.getHref());
      }
    } while (nextLink != null);

    return allEmailLists;
  }

  /**
   * Retrieves one page (100) of email lists in domain. Any changes to email
   * lists, including creations and deletions, which are made after this method
   * is called may or may not be included in the Feed which is returned. If the
   * optional startEmailListName parameter is specified, one page of email lists
   * is returned which have names at or after startEmailListName as per ASCII
   * value ordering with case-insensitivity. A value of null or empty string
   * indicates you want results from the beginning of the list.
   *
   * @param startEmailListName The starting point of the page (optional).
   * @return A EmailListFeed object of the retrieved email lists.
   * @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.
   * @deprecated Email lists have been replaced by Groups. Use
   *             {@link AppsGroupsService#retrievePageOfGroups(Link)}
   *             with Groups instead.
   */
  @Deprecated
  public EmailListFeed retrievePageOfEmailLists(String startEmailListName)
      throws AppsForYourDomainException, ServiceException, IOException {

    LOGGER.log(Level.INFO, "Retrieving one page of email lists"
        + (startEmailListName != null ? " starting at " + startEmailListName : "") + ".");

    URL retrieveUrl = new URL(
          domainUrlBase + "emailList/" + SERVICE_VERSION + "/");
    AppsForYourDomainQuery query = new AppsForYourDomainQuery(retrieveUrl);
    query.setStartEmailListName(startEmailListName);
    return emailListService.query(query, EmailListFeed.class);
  }

  /**
   * Retrieves an email list.
   *
   * @param emailList The name of the email list you want to retrieve.
   * @return An EmailListEntry object of the retrieved email list.
   * @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.
   * @deprecated Email lists have been replaced by Groups. Use
   *             {@link AppsGroupsService#retrieveGroup(String)}
   *             with Groups instead.
   */
  @Deprecated
  public EmailListEntry retrieveEmailList(String emailList)
      throws AppsForYourDomainException, ServiceException, IOException {

    LOGGER.log(Level.INFO, "Retrieving email list '" + emailList + "'.");

    URL retrieveUrl = new URL(domainUrlBase + "emailList/" + SERVICE_VERSION + "/" + emailList);