com.google.gdata.client
Class GoogleService

java.lang.Object
  extended by com.google.gdata.client.Service
      extended by com.google.gdata.client.GoogleService
Direct Known Subclasses:
CalendarService

public class GoogleService
extends Service

The GoogleService class extends the basic GData Service abstraction to add support for authentication.


Nested Class Summary
static class GoogleService.AccountDeletedException
          Authentication failed, account has been deleted.
static class GoogleService.AccountDisabledException
          Authentication failed, account has been disabled.
static class GoogleService.AuthSubToken
          Encapsulates the token used by web applications to login on behalf of a user.
static class GoogleService.CaptchaRequiredException
          Authentication failed, CAPTCHA requires answering.
static class GoogleService.InvalidCredentialsException
          Authentication failed, invalid credentials presented to server.
static class GoogleService.NotVerifiedException
          Authentication failed, account has not been verified.
static class GoogleService.ServiceUnavailableException
          Authentication failed, authentication service not available.
static class GoogleService.SessionExpiredException
          Authentication failed, the token's session has expired.
static class GoogleService.TermsNotAgreedException
          Authentication failed, user did not agree to the terms of service.
static class GoogleService.UserToken
          The UserToken encapsulates the token retrieved as a result of authenticating to Google using a user's credentials.
 
Nested classes/interfaces inherited from class com.google.gdata.client.Service
Service.GDataRequest, Service.GDataRequestFactory
 
Field Summary
protected  java.util.Set<GoogleGDataRequest.GoogleCookie> cookies
          Stores the set of GoogleCookies that have been issued during previous requests.
static java.lang.String GOOGLE_ACCOUNTS_PATH
          The path name of the Google accounts management handler.
static java.lang.String GOOGLE_LOGIN_PATH
          The path name of the Google login handler.
protected  boolean handlesCookies
          Indicates whether the GoogleService should implement a local cache for cookies returned by the GData service.
 
Fields inherited from class com.google.gdata.client.Service
connectTimeout, extProfile, requestFactory
 
Constructor Summary
GoogleService(java.lang.String serviceName, java.lang.String applicationName)
          Constructs a GoogleService instance connecting to the service with name serviceName for an application with the name applicationName.
GoogleService(java.lang.String serviceName, java.lang.String applicationName, java.lang.String protocol, java.lang.String domainName)
          Constructs a GoogleService instance connecting to the service with name serviceName for an application with the name applicationName.
 
Method Summary
 void addCookie(GoogleGDataRequest.GoogleCookie cookie)
          Adds a new GoogleCookie instance to the cache.
protected  Service.GDataRequest createRequest(Service.GDataRequest.RequestType type, java.net.URL requestUrl, ContentType contentType)
          Creates a new GDataRequest for use by the service.
 void delete(java.net.URL entryUrl)
          Deletes an existing entry using the specified entry edit URL.
 java.lang.String getAuthToken(java.lang.String username, java.lang.String password, java.lang.String captchaToken, java.lang.String captchaAnswer, java.lang.String serviceName, java.lang.String applicationName)
          Retrieves the authentication token for the provided set of credentials.
 java.util.Set<GoogleGDataRequest.GoogleCookie> getCookies()
          Returns the set of associated cookies returned by previous requests.
<E extends BaseEntry>
E
getEntry(java.net.URL entryUrl, java.lang.Class<E> entryClass)
          Returns an Atom entry instance, given the URL of the entry.
<F extends BaseFeed>
F
getFeed(java.net.URL feedUrl, java.lang.Class<F> feedClass)
          Returns the Feed associated with a particular feed URL.
 boolean handlesCookies()
          Returns true if the GoogleService is handling cookies.
<E extends BaseEntry>
E
insert(java.net.URL feedUrl, E entry)
          Inserts a new Entry into a feed associated with the target service.
 void setAuthSubToken(java.lang.String token)
          Sets the AuthSub token to be used to authenticate a user.
 void setAuthSubToken(java.lang.String token, java.security.PrivateKey key)
          Sets the AuthSub token to be used to authenticate a user.
 void setHandlesCookies(boolean handlesCookies)
          Enables or disables cookie handling.
 void setRequestFactory(Service.GDataRequestFactory requestFactory)
          Sets the GDataRequestFactory currently associated with the service.
 void setUserCredentials(java.lang.String username, java.lang.String password)
          Sets the credentials of the user to authenticate requests to the server.
 void setUserCredentials(java.lang.String username, java.lang.String password, java.lang.String captchaToken, java.lang.String captchaAnswer)
          Sets the credentials of the user to authenticate requests to the server.
<E extends BaseEntry>
E
update(java.net.URL entryUrl, E entry)
          Updates an existing Entry by writing it to the specified entry edit URL.
 
Methods inherited from class com.google.gdata.client.Service
createDeleteRequest, createEntryRequest, createFeedRequest, createInsertRequest, createUpdateRequest, getContentType, getEntry, getExtensionProfile, getFeed, getRequestFactory, getServiceVersion, query, query, setConnectTimeout, setContentType, setReadTimeout
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

GOOGLE_ACCOUNTS_PATH

public static final java.lang.String GOOGLE_ACCOUNTS_PATH
The path name of the Google accounts management handler.

See Also:
Constant Field Values

GOOGLE_LOGIN_PATH

public static final java.lang.String GOOGLE_LOGIN_PATH
The path name of the Google login handler.

See Also:
Constant Field Values

cookies

protected java.util.Set<GoogleGDataRequest.GoogleCookie> cookies
Stores the set of GoogleCookies that have been issued during previous requests.


handlesCookies

protected boolean handlesCookies
Indicates whether the GoogleService should implement a local cache for cookies returned by the GData service. If true (the default value), then the GoogleService instance will maintain the cache and return cookies on subsequent requests.

Constructor Detail

GoogleService

public GoogleService(java.lang.String serviceName,
                     java.lang.String applicationName)
Constructs a GoogleService instance connecting to the service with name serviceName for an application with the name applicationName. The default domain (www.google.com) will be used to authenticate.

Parameters:
serviceName - the name of the Google service to which we are connecting. Sample names of services might include "cl" (Calendar), "mail" (GMail), or "blogger" (Blogger)
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.

GoogleService

public GoogleService(java.lang.String serviceName,
                     java.lang.String applicationName,
                     java.lang.String protocol,
                     java.lang.String domainName)
Constructs a GoogleService instance connecting to the service with name serviceName for an application with the name applicationName. The service will authenticate at the provided domainName.

Parameters:
serviceName - the name of the Google service to which we are connecting. Sample names of services might include "cl" (Calendar), "mail" (GMail), or "blogger" (Blogger)
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.
protocol - name of protocol to use for authentication ("http"/"https")
domainName - the name of the domain hosting the login handler
Method Detail

setUserCredentials

public void setUserCredentials(java.lang.String username,
                               java.lang.String password)
                        throws AuthenticationException
Sets the credentials of the user to authenticate requests to the server.

Parameters:
username - the name of the user (an email address)
password - the password of the user
Throws:
AuthenticationException - if authentication failed.

setUserCredentials

public void setUserCredentials(java.lang.String username,
                               java.lang.String password,
                               java.lang.String captchaToken,
                               java.lang.String captchaAnswer)
                        throws AuthenticationException
Sets the credentials of the user to authenticate requests to the server. A CAPTCHA token and a CAPTCHA answer can also be optionally provided to authenticate when the authentication server requires that a CAPTCHA be answered.

Parameters:
username - the name of the user (an email id)
password - the password of the user
captchaToken - the CAPTCHA token issued by the server
captchaAnswer - the answer to the respective CAPTCHA token
Throws:
AuthenticationException - if authentication failed

setAuthSubToken

public void setAuthSubToken(java.lang.String token)
Sets the AuthSub token to be used to authenticate a user.

Parameters:
token - the AuthSub token retrieved from Google

setAuthSubToken

public void setAuthSubToken(java.lang.String token,
                            java.security.PrivateKey key)
Sets the AuthSub token to be used to authenticate a user. The token will be used in secure-mode, and the provided private key will be used to sign all requests.

Parameters:
token - the AuthSub token retrieved from Google
key - the private key to be used to sign all requests

getAuthToken

public java.lang.String getAuthToken(java.lang.String username,
                                     java.lang.String password,
                                     java.lang.String captchaToken,
                                     java.lang.String captchaAnswer,
                                     java.lang.String serviceName,
                                     java.lang.String applicationName)
                              throws AuthenticationException
Retrieves the authentication token for the provided set of credentials.

Parameters:
username - the name of the user (an email address)
password - the password of the user
captchaToken - the CAPTCHA token if CAPTCHA is required (Optional)
captchaAnswer - the respective answer of the CAPTCHA token (Optional)
serviceName - the name of the service to which a token is required
applicationName - the application requesting the token
Returns:
the token
Throws:
AuthenticationException - if authentication failed

setHandlesCookies

public void setHandlesCookies(boolean handlesCookies)
Enables or disables cookie handling.


handlesCookies

public boolean handlesCookies()
Returns true if the GoogleService is handling cookies.


addCookie

public void addCookie(GoogleGDataRequest.GoogleCookie cookie)
Adds a new GoogleCookie instance to the cache.


getCookies

public java.util.Set<GoogleGDataRequest.GoogleCookie> getCookies()
Returns the set of associated cookies returned by previous requests.


setRequestFactory

public void setRequestFactory(Service.GDataRequestFactory requestFactory)
Description copied from class: Service
Sets the GDataRequestFactory currently associated with the service.

Overrides:
setRequestFactory in class Service

createRequest

protected Service.GDataRequest createRequest(Service.GDataRequest.RequestType type,
                                             java.net.URL requestUrl,
                                             ContentType contentType)
                                      throws java.io.IOException,
                                             ServiceException
Description copied from class: Service
Creates a new GDataRequest for use by the service.

Overrides:
createRequest in class Service
Throws:
java.io.IOException
ServiceException

getEntry

public <E extends BaseEntry> E getEntry(java.net.URL entryUrl,
                                        java.lang.Class<E> entryClass)
                             throws java.io.IOException,
                                    ServiceException
Description copied from class: Service
Returns an Atom entry instance, given the URL of the entry.

Overrides:
getEntry in class Service
Parameters:
entryUrl - resource URL for the entry.
entryClass - class used to represent service entries.
Returns:
the entry referenced by the URL parameter.
Throws:
java.io.IOException - error communicating with the GData service.
ParseException - error parsing the returned entry.
ResourceNotFoundException - if the entry URL is not valid.
ServiceException - if a system error occurred when retrieving the entry.

update

public <E extends BaseEntry> E update(java.net.URL entryUrl,
                                      E entry)
                           throws java.io.IOException,
                                  ServiceException
Description copied from class: Service
Updates an existing Entry by writing it to the specified entry edit URL. The resulting Entry (after update) will be returned.

Overrides:
update in class Service
Parameters:
entryUrl - the edit URL associated with the entry.
entry - the modified Entry to be written to the server.
Returns:
the updated Entry returned by the service.
Throws:
java.io.IOException - error communicating with the GData service.
ParseException - error parsing the updated entry data.
ServiceException - update request failed due to system error.
See Also:
BaseEntry.getEditLink(), BaseEntry.update()

insert

public <E extends BaseEntry> E insert(java.net.URL feedUrl,
                                      E entry)
                           throws java.io.IOException,
                                  ServiceException
Description copied from class: Service
Inserts a new Entry into a feed associated with the target service. It will return the inserted Entry, including any additional attributes or extensions set by the GData server.

Overrides:
insert in class Service
Parameters:
feedUrl - the POST URI associated with the target feed.
entry - the new entry to insert into the feed.
Returns:
the newly inserted Entry returned by the service.
Throws:
java.io.IOException - error communicating with the GData service.
ParseException - error parsing the return entry data.
ServiceException - insert request failed due to system error.
See Also:
BaseFeed.getEntryPostLink(), BaseFeed.insert(BaseEntry)

getFeed

public <F extends BaseFeed> F getFeed(java.net.URL feedUrl,
                                      java.lang.Class<F> feedClass)
                           throws java.io.IOException,
                                  ServiceException
Description copied from class: Service
Returns the Feed associated with a particular feed URL.

Overrides:
getFeed in class Service
Parameters:
feedUrl - the URL associated with a feed. This URL can include GData query parameters.
feedClass - the class used to represent a service Feed.
Returns:
Feed resource referenced by the input URL.
Throws:
java.io.IOException - error sending request or reading the feed.
ParseException - error parsing the returned feed data.
ResourceNotFoundException - invalid feed URL.
ServiceException - system error retrieving feed.

delete

public void delete(java.net.URL entryUrl)
            throws java.io.IOException,
                   ServiceException
Description copied from class: Service
Deletes an existing entry using the specified entry edit URL.

Overrides:
delete in class Service
Parameters:
entryUrl - the URL used to edit the entry.
Throws:
java.io.IOException - error communicating with the GData service.
ResourceNotFoundException - invalid entry URL.
ServiceException - delete request failed due to system error.