|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.google.gdata.client.Service
com.google.gdata.client.GoogleService
public class GoogleService
The GoogleService class extends the basic GData Service
abstraction to add support for authentication and cookies.
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.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. |
Nested classes/interfaces inherited from class com.google.gdata.client.Service |
---|
Service.ClientOutputProperties, Service.GDataRequest, Service.GDataRequestFactory, Service.Versions |
Constructor Summary | |
---|---|
GoogleService(java.lang.String applicationName,
Service.GDataRequestFactory requestFactory,
AuthTokenFactory authTokenFactory)
Constructs a GoogleService instance connecting to the service for an application with the name applicationName . |
|
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. |
|
|
batch(java.net.URL feedUrl,
F inputFeed)
Executes several operations (insert, update or delete) on the entries that are part of the input IFeed . |
|
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 (and associated media content, if any) using the specified edit URL. |
|
void |
delete(java.net.URL entryUrl,
java.lang.String etag)
Deletes an existing entry (and associated media content, if any) using the specified 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. |
|
AuthTokenFactory |
getAuthTokenFactory()
Returns the AuthTokenFactory currently associated with the service. |
|
CookieManager |
getCookieManager()
Returns the CookieManager currently associated with the service. |
|
java.util.Set<GoogleGDataRequest.GoogleCookie> |
getCookies()
Returns the set of associated cookies returned by previous requests. |
|
|
getEntry(java.net.URL entryUrl,
java.lang.Class<E> entryClass,
DateTime ifModifiedSince)
Returns an Atom entry instance, given the URL of the entry and an if-modified-since date. |
|
|
getEntry(java.net.URL entryUrl,
java.lang.Class<E> entryClass,
java.lang.String etag)
Returns an Atom entry instance given the URL of the entry, if its current entity tag is different than the provided value. |
|
|
getFeed(Query query,
java.lang.Class<F> feedClass,
DateTime ifModifiedSince)
Returns the Feed resulting from executing a query, if it's been modified since the specified date. |
|
|
getFeed(Query query,
java.lang.Class<F> feedClass,
java.lang.String etag)
Returns the Feed resulting from query execution, if if the entity tag associated with it has changed. |
|
|
getFeed(java.net.URL feedUrl,
java.lang.Class<F> feedClass,
DateTime ifModifiedSince)
Returns the Feed associated with a particular feed URL, if it's been modified since the specified date. |
|
|
getFeed(java.net.URL feedUrl,
java.lang.Class<F> feedClass,
java.lang.String etag)
Returns the Feed associated with a particular feed URL if the entity tag associated with it has changed. |
|
boolean |
handlesCookies()
Returns true if the GoogleService is handling cookies. |
|
|
insert(java.net.URL feedUrl,
E entry)
Inserts a new IEntry into a feed associated
with the target service. |
|
static java.lang.String |
makePostRequest(java.net.URL url,
java.util.Map<java.lang.String,java.lang.String> parameters)
Makes a HTTP POST request to the provided url given the
provided parameters . |
|
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 |
setAuthTokenFactory(AuthTokenFactory authTokenFactory)
Sets the AuthTokenFactory currently associated with the service. |
|
void |
setCookieManager(CookieManager cookieManager)
Sets the CookieManager currently associated with the service. |
|
void |
setHandlesCookies(boolean handlesCookies)
Enables or disables cookie handling. |
|
void |
setOAuthCredentials(OAuthParameters parameters,
OAuthSigner signer)
Sets the OAuth credentials used to generate the authorization header. |
|
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,
ClientLoginAccountType accountType)
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. |
|
void |
setUserCredentials(java.lang.String username,
java.lang.String password,
java.lang.String captchaToken,
java.lang.String captchaAnswer,
ClientLoginAccountType accountType)
Sets the credentials of the user to authenticate requests to the server. |
|
void |
setUserToken(java.lang.String token)
Sets the AuthToken that should be used to authenticate requests to the server. |
|
void |
tokenChanged(AuthTokenFactory.AuthToken newToken)
|
|
|
update(java.net.URL entryUrl,
E entry)
Updates an existing IEntry by writing it to
the specified entry edit URL. |
Methods inherited from class java.lang.Object |
---|
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
public GoogleService(java.lang.String serviceName, java.lang.String applicationName)
serviceName
for an application with the name
applicationName
. The default domain (www.google.com) and the
default Google authentication methods will be used to authenticate.
A simple cookie manager is used.
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.public GoogleService(java.lang.String serviceName, java.lang.String applicationName, java.lang.String protocol, java.lang.String domainName)
serviceName
for an application with the name
applicationName
. The service will authenticate at the provided
domainName
. The default Google authentication methods will be
used to authenticate. A simple cookie manager is used.
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 handlerpublic GoogleService(java.lang.String applicationName, Service.GDataRequestFactory requestFactory, AuthTokenFactory authTokenFactory)
applicationName
. The provided
GDataRequestFactory
will create requests, and the given
AuthTokenFactory
will be used to generate auth tokens.
A simple cookie manager is used.
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.requestFactory
- the request factory that generates gdata requestsauthTokenFactory
- the auth token factory that generates auth tokensMethod Detail |
---|
public AuthTokenFactory getAuthTokenFactory()
AuthTokenFactory
currently associated with the service.
public void setAuthTokenFactory(AuthTokenFactory authTokenFactory)
AuthTokenFactory
currently associated with the service.
authTokenFactory
- Authentication factorypublic CookieManager getCookieManager()
CookieManager
currently associated with the service.
public void setCookieManager(CookieManager cookieManager)
CookieManager
currently associated with the service.
cookieManager
- Cookie managerpublic void tokenChanged(AuthTokenFactory.AuthToken newToken)
tokenChanged
in interface AuthTokenFactory.TokenListener
public void setUserCredentials(java.lang.String username, java.lang.String password) throws AuthenticationException
username
- the name of the user (an email address)password
- the password of the user
AuthenticationException
- if authentication failed.public void setUserCredentials(java.lang.String username, java.lang.String password, ClientLoginAccountType accountType) throws AuthenticationException
username
- the name of the user (an email address)password
- the password of the useraccountType
- the account type: HOSTED, GOOGLE, or HOSTED_OR_GOOGLE
AuthenticationException
- if authentication failed.public void setUserCredentials(java.lang.String username, java.lang.String password, java.lang.String captchaToken, java.lang.String captchaAnswer) throws AuthenticationException
username
- the name of the user (an email id)password
- the password of the usercaptchaToken
- the CAPTCHA token issued by the servercaptchaAnswer
- the answer to the respective CAPTCHA token
AuthenticationException
- if authentication failedpublic void setUserCredentials(java.lang.String username, java.lang.String password, java.lang.String captchaToken, java.lang.String captchaAnswer, ClientLoginAccountType accountType) throws AuthenticationException
username
- the name of the user (an email id)password
- the password of the usercaptchaToken
- the CAPTCHA token issued by the servercaptchaAnswer
- the answer to the respective CAPTCHA tokenaccountType
- the account type: HOSTED, GOOGLE, or HOSTED_OR_GOOGLE
AuthenticationException
- if authentication failedpublic void setUserToken(java.lang.String token)
token
- the AuthToken in ascii formpublic void setOAuthCredentials(OAuthParameters parameters, OAuthSigner signer) throws OAuthException
parameters
- the OAuth parameters to use to generated the headersigner
- the signing method to use for signing the header
OAuthException
public void setAuthSubToken(java.lang.String token)
token
- the AuthSub token retrieved from Googlepublic void setAuthSubToken(java.lang.String token, java.security.PrivateKey key)
token
- the AuthSub token retrieved from Googlekey
- the private key to be used to sign all requestspublic 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
username
- the name of the user (an email address)password
- the password of the usercaptchaToken
- 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 requiredapplicationName
- the application requesting the token
AuthenticationException
- if authentication failedpublic static java.lang.String makePostRequest(java.net.URL url, java.util.Map<java.lang.String,java.lang.String> parameters) throws java.io.IOException
url
given the
provided parameters
. It returns the output from the POST
handler as a String object.
url
- the URL to post the requestparameters
- the parameters to post to the handler
java.io.IOException
- if an I/O exception occurs while creating, writing,
or reading the requestpublic void setHandlesCookies(boolean handlesCookies)
public boolean handlesCookies()
true
if the GoogleService is handling cookies.
public void addCookie(GoogleGDataRequest.GoogleCookie cookie)
public java.util.Set<GoogleGDataRequest.GoogleCookie> getCookies()
public Service.GDataRequest createRequest(Service.GDataRequest.RequestType type, java.net.URL requestUrl, ContentType contentType) throws java.io.IOException, ServiceException
Service
Clients should be sure to call Service.GDataRequest.end()
on the
returned request once they have finished using it.
createRequest
in class Service
java.io.IOException
ServiceException
public <E extends IEntry> E getEntry(java.net.URL entryUrl, java.lang.Class<E> entryClass, DateTime ifModifiedSince) throws java.io.IOException, ServiceException
Service
getEntry
in class Service
entryUrl
- resource URL for the entry.entryClass
- class used to represent service entries,
not null
.ifModifiedSince
- used to set a precondition date that indicates the
entry should be returned only if it has been modified after the
specified date. A value of null
indicates no precondition.
java.io.IOException
- error communicating with the GData service.
NotModifiedException
- if the entry resource
has not been modified after the specified precondition date.
ParseException
- error parsing the returned
entry.
ResourceNotFoundException
- if the entry URL is
not valid.
ServiceForbiddenException
- if the GData
service cannot get the entry resource due to access constraints.
ServiceException
- if a system error occurred when retrieving the
entry.public <E extends IEntry> E getEntry(java.net.URL entryUrl, java.lang.Class<E> entryClass, java.lang.String etag) throws java.io.IOException, ServiceException
Service
getEntry
in class Service
entryUrl
- resource URL for the entry.entryClass
- class used to represent service entries,
not null
.etag
- used to provide an entity tag that indicates the entry should
be returned only if the entity tag of the current representation is
different from the provided value. A value of null
indicates
unconditional return.
java.io.IOException
- error communicating with the GData service.
NotModifiedException
- if the entry resource entity tag matches the
provided value.
ParseException
- error parsing the returned
entry.
ResourceNotFoundException
- if the entry URL is
not valid.
ServiceForbiddenException
- if the GData
service cannot get the entry resource due to access constraints.
ServiceException
- if a system error occurred when retrieving the
entry.public <E extends IEntry> E update(java.net.URL entryUrl, E entry) throws java.io.IOException, ServiceException
Service
IEntry
by writing it to
the specified entry edit URL. The resulting Entry (after update) will be
returned.
update
in class Service
entryUrl
- the edit URL associated with the entry.entry
- the modified Entry to be written to the server.
java.io.IOException
- error communicating with the GData service.
ParseException
- error parsing the updated
entry data.
ServiceException
- update request failed due to system error.IEntry.getEditLink()
public <E extends IEntry> E insert(java.net.URL feedUrl, E entry) throws java.io.IOException, ServiceException
Service
IEntry
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.
insert
in class Service
feedUrl
- the POST URI associated with the target feed.entry
- the new entry to insert into the feed.
java.io.IOException
- error communicating with the GData service.
ParseException
- error parsing the return entry
data.
ServiceForbiddenException
- the inserted Entry
has associated media content and can only be inserted using a media
service.
ServiceException
- insert request failed due to system error.IFeed.getEntryPostLink()
public <F extends IFeed> F getFeed(java.net.URL feedUrl, java.lang.Class<F> feedClass, DateTime ifModifiedSince) throws java.io.IOException, ServiceException
Service
getFeed
in class Service
feedUrl
- the URL associated with a feed. This URL can include GData
query parameters.feedClass
- the class used to represent a service Feed.ifModifiedSince
- used to set a precondition date that indicates the
feed should be returned only if it has been modified after the
specified date. A value of null
indicates no precondition.
java.io.IOException
- error sending request or reading the feed.
NotModifiedException
- if the feed resource has
not been modified since the specified precondition date.
ParseException
- error parsing the returned
feed data.
ResourceNotFoundException
- invalid feed URL.
ServiceException
- system error retrieving feed.public <F extends IFeed> F getFeed(java.net.URL feedUrl, java.lang.Class<F> feedClass, java.lang.String etag) throws java.io.IOException, ServiceException
Service
getFeed
in class Service
feedUrl
- the URL associated with a feed. This URL can include GData
query parameters.feedClass
- the class used to represent a service Feed.etag
- used to provide an entity tag that indicates the feed should be
returned only if the entity tag of the current representation is
different from the provided value. A value of null
indicates
unconditional return.
java.io.IOException
- error sending request or reading the feed.
NotModifiedException
- if the feed resource entity tag matches the
provided value.
ParseException
- error parsing the returned
feed data.
ResourceNotFoundException
- invalid feed URL.
ServiceException
- system error retrieving feed.public <F extends IFeed> F getFeed(Query query, java.lang.Class<F> feedClass, DateTime ifModifiedSince) throws java.io.IOException, ServiceException
Service
getFeed
in class Service
query
- feed query.feedClass
- the class used to represent a service Feed.ifModifiedSince
- used to set a precondition date that indicates the
feed should be returned only if it has been modified after the
specified date. A value of null
indicates no precondition.
java.io.IOException
- error sending request or reading the feed.
ServiceException
- system error retrieving feed.public <F extends IFeed> F getFeed(Query query, java.lang.Class<F> feedClass, java.lang.String etag) throws java.io.IOException, ServiceException
Service
getFeed
in class Service
query
- feed query.feedClass
- the class used to represent query results.etag
- used to provide an entity tag that indicates the feed should be
returned only if the entity tag of the current representation is
different from the provided value. A value of null
indicates
unconditional return.
java.io.IOException
- error sending request or reading the feed.
NotModifiedException
- if the feed resource entity tag matches the
provided value.
ParseException
- error parsing the returned feed data.
ResourceNotFoundException
- invalid feed URL.
ServiceException
- system error retrieving feed.public void delete(java.net.URL entryUrl) throws java.io.IOException, ServiceException
Service
delete
in class Service
entryUrl
- the edit or medit edit url associated with the resource.
java.io.IOException
- error communicating with the GData service.
ResourceNotFoundException
- invalid entry URL.
ServiceException
- delete request failed due to system error.public void delete(java.net.URL entryUrl, java.lang.String etag) throws java.io.IOException, ServiceException
Service
delete
in class Service
entryUrl
- the edit or medit edit url associated with the resource.etag
- the entity tag value that is the expected value for the target
resource. A value of null
will not set an etag
precondition and a value of "*"
will perform an
unconditional delete.
java.io.IOException
- error communicating with the GData service.
ResourceNotFoundException
- invalid entry URL.
ServiceException
- delete request failed due to system error.public <F extends IFeed> F batch(java.net.URL feedUrl, F inputFeed) throws java.io.IOException, ServiceException, BatchInterruptedException
IFeed
. It will return another feed that
describes what was done while executing these operations.
It is possible for one batch operation to fail even though other operations
have worked, so this method won't throw a ServiceException unless something
really wrong is going on. You need to check the entries in the returned
feed to know which operations succeeded and which operations failed (see
BatchStatus
and
BatchInterrupted
extensions.)
batch
in class Service
feedUrl
- the POST URI associated with the target feed.inputFeed
- a description of the operations to execute, described
using tags in the batch: namespace
java.io.IOException
- error communicating with the GData service.
ParseException
- error parsing the return entry
data.
ServiceException
- insert request failed due to system error.
BatchInterruptedException
- if something really wrong was detected by
the server while parsing the request, like invalid XML data. Some
operations might have succeeded when this exception is thrown.
Check BatchInterruptedException.getIFeed()
.IFeed.getEntryPostLink()
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |