Google Data APIs Client Library (1.41.1)



com.google.api.gbase.client
Class GoogleBaseService

java.lang.Object
  extended by com.google.gdata.client.Service
      extended by com.google.gdata.client.GoogleService
          extended by com.google.gdata.client.media.MediaService
              extended by com.google.api.gbase.client.GoogleBaseService
All Implemented Interfaces:
AuthTokenFactory.TokenListener

public class GoogleBaseService
extends MediaService

Creates a Google data service with extensions specific to Google Base. The methods returning Atom feeds and entries in this class default to returning instances of GoogleBaseFeed and GoogleBaseEntry.

Usage example

 GoogleBaseService service = new GoogleBaseService("mycompany-myapp-1.0");
 service.setUserCredentials(username, password);
 GoogleBaseQuery query = new GoogleBaseQuery(...);
 query.setGoogleBaseQuery(...);
 GoogleBaseFeed feed = service.query(query);
 


Nested Class Summary
static class GoogleBaseService.Versions
          The Versions class contains all released versions of the Google Base API
 
Nested classes/interfaces inherited from class com.google.gdata.client.GoogleService
GoogleService.AccountDeletedException, GoogleService.AccountDisabledException, GoogleService.CaptchaRequiredException, GoogleService.InvalidCredentialsException, GoogleService.NotVerifiedException, GoogleService.ServiceUnavailableException, GoogleService.SessionExpiredException, GoogleService.TermsNotAgreedException
 
Nested classes/interfaces inherited from class com.google.gdata.client.Service
Service.ClientInputProperties, Service.ClientOutputProperties, Service.ClientStreamProperties, Service.GDataRequest, Service.GDataRequestFactory
 
Field Summary
protected  java.lang.String application
          Name of the application passed to the constructor.
static Version DEFAULT_VERSION
          Version 1 is the current default version for GoogleBaseService.
static java.lang.String GOOGLE_BASE_SERVICE
          The official name of the service.
static java.lang.String GOOGLE_BASE_SERVICE_VERSION
          Version of this service.
 
Fields inherited from class com.google.gdata.client.media.MediaService
DEFAULT_CHUNKED_BUFFER_SIZE, NO_CHUNKED_MEDIA_REQUEST
 
Fields inherited from class com.google.gdata.client.Service
connectTimeout, extProfile, metadataRegistry, requestFactory
 
Constructor Summary
GoogleBaseService(java.lang.String applicationName)
          Creates a GoogleBaseService connecting to the default authentication domain (www.google.com) using the HTTPS.
GoogleBaseService(java.lang.String applicationName, java.lang.String developerKey)
          Creates a GoogleBaseService connecting to the default authentication domain (www.google.com) using the HTTPS.
GoogleBaseService(java.lang.String applicationName, java.lang.String protocol, java.lang.String domainName)
          Creates a GoogleBaseService connecting to a specific authentication domain using a specific protocol.
GoogleBaseService(java.lang.String applicationName, java.lang.String developerKey, java.lang.String protocol, java.lang.String domainName)
          Creates a GoogleBaseService connecting to a specific authentication domain using a specific protocol.
 
Method Summary
<F extends IFeed>
F
batch(java.net.URL url, F f)
          Executes several operations (insert, update or delete) on the entries that are part of the input IFeed.
 GoogleBaseEntry getEntry(java.net.URL entryUrl)
          Returns an Google Base entry instance, given the URL of the entry.
 GoogleBaseEntry getEntry(java.net.URL entryUrl, DateTime ifModifiedSince)
          Returns an Google Base entry instance, given the URL of the entry and an if-modified-since date.
 GoogleBaseFeed getFeed(java.net.URL feedUrl)
          Returns the Google base feed associated with a particular feed URL.
 GoogleBaseFeed getFeed(java.net.URL feedUrl, DateTime ifModifiedSince)
          Returns the Google Base feed associated with a particular feed URL, if it's been modified since the specified date.
 GoogleBaseMediaEntry getMediaEntry(java.net.URL entryUrl)
          Returns the media entry referenced by the entryUrl.
 GoogleBaseMediaEntry getMediaEntry(java.net.URL entryUrl, DateTime ifModifiedSince)
          Returns the media entry referenced by the entryUrl, if it's been modified since the specified date.
 GoogleBaseMediaFeed getMediaFeed(java.net.URL feedUrl)
          Returns the Google base media feed associated with the specified feed URL.
 GoogleBaseMediaFeed getMediaFeed(java.net.URL feedUrl, DateTime ifModifiedSince)
          Returns the Google Base media feed associated with a particular feed URL, if it's been modified since the specified date.
 java.lang.String getServiceVersion()
          Returns the google base service version followed by the gdata service version.
<E extends IEntry>
E
insert(java.net.URL url, E e)
          Inserts a new Entry into a feed associated with the target service.
 GoogleBaseFeed query(Query query)
          Executes a GData query against the target service and returns the Feed containing entries that match the query result.
 GoogleBaseFeed query(Query query, DateTime ifModifiedSince)
          Executes a GData query against the target service and returns the GoogleBaseFeed containing entries that match the query result, if it's been modified since the specified date.
<E extends IEntry>
E
update(java.net.URL url, E e)
          Updates an existing entry metadata by writing it to the specified edit URL.
 
Methods inherited from class com.google.gdata.client.media.MediaService
getDefaultAltRegistry, getMedia, getMedia, insert, setChunkedMediaUpload, updateMedia, updateMedia
 
Methods inherited from class com.google.gdata.client.GoogleService
addCookie, createRequest, createRequest, delete, delete, getAuthToken, getAuthTokenFactory, getCookieManager, getCookies, getEntry, getEntry, getFeed, getFeed, getFeed, getFeed, handleRedirectException, handlesCookies, handleSessionExpiredException, makePostRequest, setAuthSubToken, setAuthSubToken, setAuthTokenFactory, setCookieManager, setHandlesCookies, setOAuthCredentials, setUserCredentials, setUserCredentials, setUserCredentials, setUserCredentials, setUserToken, tokenChanged
 
Methods inherited from class com.google.gdata.client.Service
classOf, createBatchRequest, createDeleteRequest, createEntryRequest, createFeedRequest, createFeedRequest, createInsertRequest, createLinkQueryRequest, createPatchRequest, createUpdateRequest, delete, delete, endVersionScope, getAltRegistry, getContentType, getEntry, getExtensionProfile, getFeed, getFeed, getMetadataRegistry, getProtocolVersion, getRequestFactory, getSchema, getStreamFromLink, getVersion, initServiceVersion, introspect, parseResponseData, parseResponseData, patch, patch, query, query, query, setAcceptLanguage, setAltRegistry, setConnectTimeout, setContentType, setExtensionProfile, setHeader, setOAuthProxyHeaders, setPrivateHeader, setProtocolVersion, setReadTimeout, setRequestFactory, setTimeouts, startVersionScope, update, useSsl, writeRequestData, writeRequestData
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

GOOGLE_BASE_SERVICE

public static final java.lang.String GOOGLE_BASE_SERVICE
The official name of the service.

See Also:
Constant Field Values

GOOGLE_BASE_SERVICE_VERSION

public static final java.lang.String GOOGLE_BASE_SERVICE_VERSION
Version of this service.

See Also:
getServiceVersion()

DEFAULT_VERSION

public static final Version DEFAULT_VERSION
Version 1 is the current default version for GoogleBaseService.


application

protected java.lang.String application
Name of the application passed to the constructor.

Constructor Detail

GoogleBaseService

public GoogleBaseService(java.lang.String applicationName)
Creates a GoogleBaseService connecting to the default authentication domain (www.google.com) using the HTTPS.

Parameters:
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.

GoogleBaseService

public GoogleBaseService(java.lang.String applicationName,
                         java.lang.String developerKey)
Creates a GoogleBaseService connecting to the default authentication domain (www.google.com) using the HTTPS.

Parameters:
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.
developerKey - developer key (ignored)

GoogleBaseService

public GoogleBaseService(java.lang.String applicationName,
                         java.lang.String protocol,
                         java.lang.String domainName)
Creates a GoogleBaseService connecting to a specific authentication domain using a specific protocol.

Parameters:
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

GoogleBaseService

public GoogleBaseService(java.lang.String applicationName,
                         java.lang.String developerKey,
                         java.lang.String protocol,
                         java.lang.String domainName)
Creates a GoogleBaseService connecting to a specific authentication domain using a specific protocol.

Parameters:
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.
developerKey - developer key (ignored)
protocol - name of protocol to use for authentication ("http"/"https")
domainName - the name of the domain hosting the login handler
Method Detail

getFeed

public GoogleBaseFeed getFeed(java.net.URL feedUrl,
                              DateTime ifModifiedSince)
                       throws java.io.IOException,
                              ServiceException
Returns the Google Base feed associated with a particular feed URL, if it's been modified since the specified date.

Parameters:
feedUrl - the URL associated with a feed. This URL can include GData query parameters.
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.
Returns:
Feed resource referenced by the input URL.
Throws:
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.
See Also:
GoogleService.getFeed(java.net.URL, Class, com.google.gdata.data.DateTime)

getFeed

public GoogleBaseFeed getFeed(java.net.URL feedUrl)
                       throws java.io.IOException,
                              ServiceException
Returns the Google base feed associated with a particular feed URL.

Parameters:
feedUrl - the URL associated with a feed. This URL can include GData query parameters.
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.
See Also:
Service.getFeed(java.net.URL, Class)

getMediaFeed

public GoogleBaseMediaFeed getMediaFeed(java.net.URL feedUrl)
                                 throws java.io.IOException,
                                        ServiceException
Returns the Google base media feed associated with the specified feed URL. For the call to be valid, the user must be authenticated and own the item. The Google Base item has the link to its media feed registered as a FeedLink extension with the media relation.

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.
See Also:
GoogleService.getFeed(java.net.URL, Class, com.google.gdata.data.DateTime)

getMediaFeed

public GoogleBaseMediaFeed getMediaFeed(java.net.URL feedUrl,
                                        DateTime ifModifiedSince)
                                 throws java.io.IOException,
                                        ServiceException
Returns the Google Base media feed associated with a particular feed URL, if it's been modified since the specified date.

Parameters:
feedUrl - the URL associated with a media feed for one particular item.
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.
Returns:
Feed resource referenced by the input URL.
Throws:
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.
See Also:
GoogleService.getFeed(java.net.URL, Class, com.google.gdata.data.DateTime)

getEntry

public GoogleBaseEntry getEntry(java.net.URL entryUrl,
                                DateTime ifModifiedSince)
                         throws java.io.IOException,
                                ServiceException
Returns an Google Base entry instance, given the URL of the entry and an if-modified-since date.

Parameters:
entryUrl - resource URL for the entry.
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.
Returns:
the entry referenced by the URL parameter.
Throws:
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.
See Also:
GoogleService.getEntry(java.net.URL, Class, DateTime)

getEntry

public GoogleBaseEntry getEntry(java.net.URL entryUrl)
                         throws java.io.IOException,
                                ServiceException
Returns an Google Base entry instance, given the URL of the entry.

Parameters:
entryUrl - resource URL for the entry.
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.
ServiceForbiddenException - if the GData service cannot get the entry resource due to access constraints.
ServiceException - if a system error occurred when retrieving the entry.
See Also:
Service.getEntry(java.net.URL, Class)

getMediaEntry

public GoogleBaseMediaEntry getMediaEntry(java.net.URL entryUrl)
                                   throws java.io.IOException,
                                          ServiceException
Returns the media entry referenced by the entryUrl. If the URL is not pointing to a media entry, an exception will be thrown.

Parameters:
entryUrl - the url to the media entry.
Returns:
a media entry object representing the meta-data for the referenced media object (item image or attachment).
Throws:
java.io.IOException - error communicating with the GData service.
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

getMediaEntry

public GoogleBaseMediaEntry getMediaEntry(java.net.URL entryUrl,
                                          DateTime ifModifiedSince)
                                   throws java.io.IOException,
                                          ServiceException
Returns the media entry referenced by the entryUrl, if it's been modified since the specified date.

Parameters:
entryUrl - the url to the media entry.
Returns:
a media entry object representing the meta-data for the referenced media object (item image or attachment).
Throws:
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

query

public GoogleBaseFeed query(Query query,
                            DateTime ifModifiedSince)
                     throws java.io.IOException,
                            ServiceException
Executes a GData query against the target service and returns the GoogleBaseFeed containing entries that match the query result, if it's been modified since the specified date.

Parameters:
query - Query instance defining target feed and query parameters, usually a GoogleBaseQuery
ifModifiedSince - used to set a precondition date that indicates the query result feed should be returned only if contains entries that have been modified after the specified date. A value of null indicates no precondition.
Throws:
java.io.IOException - error communicating with the GData service.
NotModifiedException - if the query resource does not contain entries modified since the specified precondition date.
ServiceForbiddenException - feed does not support the query.
ParseException - error parsing the returned feed data.
ServiceException - query request failed.
See Also:
Service.query(com.google.gdata.client.Query, Class, DateTime)

query

public GoogleBaseFeed query(Query query)
                     throws java.io.IOException,
                            ServiceException
Executes a GData query against the target service and returns the Feed containing entries that match the query result.

Parameters:
query - Query instance defining target feed and query parameters, usually a GoogleBaseQuery
Throws:
java.io.IOException - error communicating with the GData service.
NotModifiedException - if the query resource does not contain entries modified since the specified precondition date.
ServiceForbiddenException - feed does not support the query.
ParseException - error parsing the returned feed data.
ServiceException - query request failed.

update

public <E extends IEntry> E update(java.net.URL url,
                                   E e)
                        throws java.io.IOException,
                               ServiceException
Description copied from class: MediaService
Updates an existing entry metadata by writing it to the specified edit URL. The resulting entry (after update) will be returned. If the entry has media resource, the media part will not be updated. To update both metadata and media, use MediaService.updateMedia(URL, IEntry). To update media only, use MediaService.updateMedia(URL, Class, MediaSource).

Overrides:
update in class MediaService
Parameters:
url - the media edit URL associated with the resource.
e - the updated 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:
IEntry.getMediaEditLink()

insert

public <E extends IEntry> E insert(java.net.URL url,
                                   E e)
                        throws java.io.IOException,
                               ServiceException
Description copied from class: MediaService
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. If the Entry has been associated with a MediaSource through the IMediaEntry.setMediaSource(MediaSource) method then both the entry and the media resource will be inserted into the media feed associated with the target service. If the media source has a name (DataSource.getName() that is non-null), the name will be provided as a Slug header that is sent along with request and may be used as a hint when determining the ID, url, and/or title of the inserted resource.

To insert only media content, use MediaService.insert(URL, Class, MediaSource).

Overrides:
insert in class MediaService
Parameters:
url - the POST URI associated with the target feed.
e - 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:
IFeed.getEntryPostLink()

batch

public <F extends IFeed> F batch(java.net.URL url,
                                 F f)
                      throws java.io.IOException,
                             ServiceException,
                             BatchInterruptedException
Description copied from class: GoogleService
Executes several operations (insert, update or delete) on the entries that are part of the input 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.)

Overrides:
batch in class GoogleService
Parameters:
url - the POST URI associated with the target feed.
f - a description of the operations to execute, described using tags in the batch: namespace
Returns:
a feed with the result of each operation in a separate entry
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.
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().
See Also:
IFeed.getEntryPostLink()

getServiceVersion

public java.lang.String getServiceVersion()
Returns the google base service version followed by the gdata service version.

Overrides:
getServiceVersion in class Service
Returns:
both versions, separated by a space
See Also:
GOOGLE_BASE_SERVICE_VERSION