Using the Java Client Library

The following subsections explain how to use the Google Apps Java client library to access Provisioning API functionality. Each subsection explains the Java client library methods for specific API functionality. These methods can be found in sample.appsforyourdomain.AppsForYourDomainClient class.

Methods for User Accounts Creating a User Account Retrieving a User Account Retrieving all Users in a Domain Retrieving List of 100 Users Updating a User Account Suspending a User Account Restoring a User Account Deleting a User Account Methods for Nicknames Creating a Nickname Retrieving a Nickname Retrieving all Nicknames for a User Retrieving all Nicknames in a Domain Retrieving List of 100 Nicknames Deleting a Nickname

Methods for Email Lists Creating an Email List Retrieving an Email List Retrieving all Email List Subscriptions for a User Retrieving all Email Lists in a Domain Retrieving List of 100 Email Lists Deleting an Email List Methods for Email List Recipients Adding an Address to an Email List Retrieving All Subscribers to an Email List Retrieving List of 100 Email List Subscribers Deleting an Address from an Email List Methods for Handling Errors Identifying Errors in API Responses

Methods for User Accounts

Creating a User Account

To create a user account using the Java client library, call one of the following methods. These methods all return a UserEntry XML response, which the Java client library converts to a UserEntry object.

createUser(String username, String givenName, String familyName, String password)
createUser(String username, String givenName, String familyName, String password, Integer quotaLimitInMb)
createUser(String username, String givenName, String familyName, String password, String passwordHashFunction)
createUser(String username, String givenName, String familyName, String password, String passwordHashFunction, Integer quotaLimitInMb)

Note: Not all partners have the ability to adjust the disk space quota allocated to users. This method takes the following arguments:

• The username argument contains the unique name that identifies the account owner.
• The givenName argument contains the user's first name.
• The familyName argument contains the user's last name.
• The password argument contains the password for the user account.
• The passwordHashFunction argument specifies the hash format of the password parameter.
• The quotaLimitInMb argument identifies the amount of disk space in MB that will be allocated to the user account.

Retrieving a User Account

To retrieve information about a user account using the Java client library, call the following method. This method returns a UserEntry XML response, which the Java client library converts to a UserEntry object.

retrieveUser(String username)

The only argument that you need to pass to the method is the username associated with the account that you wish to retrieve.

Retrieving all Users in a Domain

To retrieve all of the users in a domain, you can call the following method in the Java client library. This method returns a UserFeed XML response, which the Java client library converts to a UserFeed object.

retrieveAllUsers()

Retrieving List of 100 Users

This method allows you to control the size of your result set when you request all of the users in your domain. As discussed in the Results Pagination section, the Java client library offers methods that allow you to request all results or to request 100 results at a time. If you use the latter method, you will need to ensure that your code requests additional pages of results as necessary.

To retrieve a list of 100 users in your domain, you can call the following method in the Java client library. This method returns a UserFeed XML response, which the Java client library converts to a UserFeed object.

retrievePageOfUsers(String startUsername)

The only argument that you need to pass to the method is the first username that should appear in your result set. Usernames are ordered case-insensitively by ASCII value.

Updating a User Account

To update a user account using the Java client library, call the following method. This method returns a UserEntry XML response, which the Java client library converts to a UserEntry object.

updateUser(String username, UserEntry userEntry)

This method takes two arguments:

• The username argument identifies the account that you are updating.
• The userEntry object contains information about a user account, including the user's first name, last name, username and password. The createUser and retrieveUser methods both return a UserEntry object.

The common use case for this method will be to retrieve a user account, modify the UserEntry object that contains information about that account, and then submit the modified object to the updateUser method.

Suspending a User Account

To suspend a user account using the Java client library, call the following method. This method returns a UserEntry XML response, which the Java client library converts to a UserEntry object.

suspendUser(String username)

The only argument that you need to pass to the method is the name of the user whose account you wish to suspend.

Restoring a User Account

To restore a user account using the Java client library, call the following method. This method returns a UserEntry XML response, which the Java client library converts to a UserEntry object.

restoreUser(String username)

The only argument that you need to pass to the method is the name of the user whose account you wish to restore.

Deleting a User Account

To delete a user account using the Java client library, call the following method:

deleteUser(String username)

The only argument that you need to pass to the method is the name of the user whose account you wish to delete.

Methods for Nicknames

Creating a Nickname

To create a nickname using the Java client library, call the following method. This method returns a NicknameEntry XML response, which the Java client library converts to a NicknameEntry object.

createNickname(String username, String nickname)

This method takes two arguments:

• The username argument identifies the user account for which you are creating a nickname.
• The nickname argument identifies the nickname for the user account.

Retrieving a Nickname

To retrieve information about a nickname using the Java client library, call the following method. This method returns a NicknameEntry XML response, which the Java client library converts to a NicknameEntry object.

retrieveNickname(String nickname)

The only argument that you need to pass to the method is the nickname you wish to retrieve.

Retrieving all Nicknames for a User Account

To retrieve all of the nicknames created for a user account, you can call the following method in the Java client library. This method returns a NicknameFeed XML response, which the Java client library converts to a NicknameFeed object.

retrieveNicknames(String username)

The only argument that you need to pass to the method is the username for which you wish to retrieve nicknames.

Retrieving all Nicknames in a Domain

To retrieve all of the nicknames in a domain, you can call the following method in the Java client library. This method returns a NicknameFeed XML response, which the Java client library converts to a NicknameFeed object.

retrieveAllNicknames()

Retrieving List of 100 Nicknames

This method allows you to control the size of your result set when you request all of the nicknames in your domain. As discussed in the Results Pagination section, the Java client library offers methods that allow you to request all results or to request 100 results at a time. If you use the latter method, you will need to ensure that your code requests additional pages of results as necessary.

To retrieve a list of 100 nicknames in your domain, you can call the following method in the Java client library. This method returns a NicknameFeed XML response, which the Java client library converts to a NicknameFeed object.

retrievePageOfNicknames(String startNickname)

The only argument that you need to pass to the method is the first nickname that should appear in your result set. Nicknames are ordered case-insensitively by ASCII value.

Deleting a Nickname

To delete a nickname using the Java client library, call the following method:

deleteNickname(String nickname)

The only argument that you need to pass to the method is the name of the nickname that you wish to delete.

Methods for Email Lists

Creating an Email List

To create an email list using the Java client library, call the following method. This method returns an EmailListEntry XML response, which the Java client library converts to an EmailListEntry object.

createEmailList(String emailList)

The only argument that you need to pass to the method is the name of the email list that you wish to create.

Note: A newly created email list does not have any subscribers. You must call the addRecipientToEmailList method to add subscribers to an email list.

Retrieving an Email List

To retrieve information about an email list using the Java client library, call the following method. This method returns a EmailListEntry XML response, which the Java client library converts to a EmailListEntry object.

retrieveEmailList(String emailList)

The only argument that you need to pass to the method is the name of the email list that you wish to retrieve.

Retrieving all Email Lists for a User Account

To retrieve all of the email lists that a user is a recipient of, you can call the following method in the Java client library. This method returns a EmailListFeed XML response, which the Java client library converts to a EmailListFeed object.

retrieveEmailLists(String recipient)

The only argument that you need to pass to the method is the username or email address of a hosted user for which you wish to retrieve email list subscriptions.

Retrieving all Email Lists in a Domain

To retrieve all of the email lists in a domain, you can call the following method in the Java client library. This method returns a EmailListFeed XML response, which the Java client library converts to a EmailListFeed object.

retrieveAllEmailLists()

Retrieving List of 100 Email Lists

This method allows you to control the size of your result set when you request all of the email lists in your domain. As discussed in the Results Pagination section, the Java client library offers methods that allow you to request all results or to request 100 results at a time. If you use the latter method, you will need to ensure that your code requests additional pages of results as necessary.

To retrieve a list of 100 email lists in your domain, you can call the following method in the Java client library. This method returns a EmailListFeed XML response, which the Java client library converts to a EmailListFeed object.

retrievePageOfEmailLists(String startEmailListName)

The only argument that you need to pass to the method is the first email list that should appear in your result set. Email list names are ordered case-insensitively by ASCII value.

Deleting an Email List

To delete an email list using the Java client library, call the following method:

deleteEmailList(String emailList)

The only argument that you need to pass to the method is the name of the email list that you wish to delete.

Note: When you delete an email list, the Provisioning API will automatically delete all recipients from the email list as well.

Methods for Email List Recipients

Adding an Address to an Email List

To add an email address to an email list using the Java client library, call the following method. This method returns an EmailListRecipientEntry XML response, which the Java client library converts to a EmailListRecipientEntry object.

addRecipientToEmailList(String recipientAddress, String emailList)

This method takes two arguments:

• The recipientAddress argument identifies the email address that is being added to an email list.
• The emailList argument identifies the email list to which the address is being added.

Retrieving all Subscribers to an Email List

To retrieve a list of all of the subscribers to an email list, you can call the following method in the Java client library. This method returns a EmailListRecipientFeed XML response, which the Java client library converts to a EmailListRecipientFeed object.

retrieveAllRecipients(String emailList)

The only argument that you need to pass to the method is the name of the email list for which you wish to retrieve a subscriber list.

Retrieving List of 100 Email List Subscribers

This method allows you to control the size of your result set when you request all of the recipients of an email list. As discussed in the Results Pagination section, the Java client library offers methods that allow you to request all results or to request 100 results at a time. If you use the latter method, you will need to ensure that your code requests additional pages of results as necessary.

To retrieve a list of 100 email list recipients, you can call the following method in the Java client library. This method returns a EmailListRecipientFeed XML response, which the Java client library converts to a EmailListRecipientFeed object.

retrievePageOfRecipients(String emailList, String startRecipient)

This method takes two arguments. The first argument is the name of the email list for which you are retrieving recipients, and the second argument is the first email address that should appear in your result set. Email addresses are ordered case-insensitively by ASCII value.

Deleting an Address from an Email List

To delete an email address from an email list using the Java client library, call the following method:

removeRecipientFromEmailList(String recipientAddress, String emailList)

This method takes two arguments:

• The recipientAddress argument identifies the email address that is being removed from an email list.
• The emailList argument identifies the email address to which the address is being removed.

Methods for Handling Errors

Identifying Errors in API Responses

The Java client library will throw an AppsForYourDomainException when it receives an error response from the Provisioning API. Other types of exceptions may also be thrown for other types of errors. To process or log an AppsForYourDomainException, we recommend that you call the getErrorCode method on that object to determine the type of error that the Provisioning API returned. The sample code below demonstrates how you would catch an AppsForYourDomainException in the Provisioning API:

try {
    // Some API actions
} catch (AppsForYourDomainException e) {
    if (e.getErrorCode() == AppsForYourDomainErrorCode.EntityDoesNotExist ) {
        // Do some post-error processing or logging.
    }
}

A complete list of error codes is provided in Appendix D - GData Error Codes.