Google Data APIs Client Library

com.google.gdata.client.media
Class MediaService

java.lang.Object
  com.google.gdata.client.Service
      com.google.gdata.client.GoogleService
          com.google.gdata.client.media.MediaService

All Implemented Interfaces:

AuthTokenFactory.TokenListener

Direct Known Subclasses:

DocsService, GoogleBaseService, PicasawebService, YouTubeService

public class MediaService
extends GoogleService

The MediaService class extends the base GoogleService class to add support for media content handling. GData services that support posting of MIME content in addition to Atom metadata will be derived from this base class.

Nested Class Summary

Nested classes/interfaces inherited from class com.google.gdata.client.GoogleService

GoogleService.AccountDeletedException, GoogleService.AccountDisabledException, GoogleService.AuthSubToken, GoogleService.CaptchaRequiredException, GoogleService.InvalidCredentialsException, GoogleService.NotVerifiedException, GoogleService.ServiceUnavailableException, GoogleService.SessionExpiredException, GoogleService.TermsNotAgreedException, GoogleService.UserToken

Nested classes/interfaces inherited from class com.google.gdata.client.Service

Service.GDataRequest, Service.GDataRequestFactory, Service.Versions

Field Summary

Fields inherited from class com.google.gdata.client.Service

connectTimeout, extProfile, requestFactory

Constructor Summary

MediaService(java.lang.String serviceName, java.lang.String applicationName)
Constructs a MediaService instance connecting to the service with name serviceName for an application with the name applicationName.

MediaService(java.lang.String serviceName, java.lang.String applicationName, java.lang.String protocol, java.lang.String domainName)
Constructs a MediaService instance connecting to the service with name serviceName for an application with the name applicationName.

Method Summary

MediaSource	getMedia(MediaContent mediaContent) Returns a MediaSource that can be used to read the external media content of an entry.
MediaSource	getMedia(MediaContent mediaContent, DateTime ifModifiedSince) Returns a MediaSource that can be used to read the external media content of an entry.
<E extends BaseEntry> E	insert(java.net.URL feedUrl, java.lang.Class<E> entryClass, MediaSource media) Inserts a new media resource read from MediaSource into a media feed associated with the target service.
<E extends BaseEntry<?>> E	insert(java.net.URL feedUrl, E entry) Inserts a new Entry into a feed associated with the target service.
<E extends BaseEntry> E	updateMedia(java.net.URL mediaUrl, java.lang.Class<E> entryClass, MediaSource media) Updates an existing media resource with data read from the MediaSource by writing it it to the specified media edit URL.
<E extends BaseEntry> E	updateMedia(java.net.URL mediaUrl, E entry) Updates an existing entry and associated media resource by writing it to the specified media edit URL.

Methods inherited from class com.google.gdata.client.GoogleService

addCookie, createRequest, delete, delete, getAuthToken, getAuthTokenFactory, getCookieManager, getCookies, getEntry, getEntry, getFeed, getFeed, getFeed, getFeed, handleRedirectException, handlesCookies, handleSessionExpiredException, makePostRequest, setAuthSubToken, setAuthSubToken, setAuthTokenFactory, setCookieManager, setHandlesCookies, setUserCredentials, setUserCredentials, setUserToken, tokenChanged, update

Methods inherited from class com.google.gdata.client.Service

batch, closeSource, createBatchRequest, createDeleteRequest, createEntryRequest, createFeedRequest, createFeedRequest, createInsertRequest, createUpdateRequest, getContentType, getEntry, getExtensionProfile, getFeed, getFeed, getRequestFactory, getServiceVersion, getStreamFromLink, getVersion, initServiceVersion, introspect, parseEntry, query, query, query, setConnectTimeout, setContentType, setExtensionProfile, setReadTimeout, setRequestFactory, setTimeouts, update, useSsl

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MediaService

public MediaService(java.lang.String serviceName,
                    java.lang.String applicationName)

Constructs a MediaService 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.

MediaService

public MediaService(java.lang.String serviceName,
                    java.lang.String applicationName,
                    java.lang.String protocol,
                    java.lang.String domainName)

Constructs a MediaService 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

getMedia

public MediaSource getMedia(MediaContent mediaContent,
                            DateTime ifModifiedSince)
                     throws java.io.IOException,
                            ServiceException

Returns a MediaSource that can be used to read the external media content of an entry.

Parameters:

mediaContent - the media content describing the media

ifModifiedSince - used to set a precondition date that indicates the media should be returned only if it has been modified after the specified date. A value of null indicates no precondition.

Returns:

media source that can be used to access the media content.

Throws:

java.io.IOException - error communicating with the GData service.

ServiceException - entry request creation failed.

getMedia

public MediaSource getMedia(MediaContent mediaContent)
                     throws java.io.IOException,
                            ServiceException

Returns a MediaSource that can be used to read the external media content of an entry.

Parameters:

mediaContent - the media content describing the media

Returns:

GData request instance that can be used to read the entry.

Throws:

java.io.IOException - error communicating with the GData service.

ServiceException - entry request creation failed.

insert

public <E extends BaseEntry<?>> E insert(java.net.URL feedUrl,
                                         E entry)
                              throws java.io.IOException,
                                     ServiceException

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 MediaEntry.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 insert(URL, Class, MediaSource).

Overrides:

insert in class GoogleService

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)

insert

public <E extends BaseEntry> E insert(java.net.URL feedUrl,
                                      java.lang.Class<E> entryClass,
                                      MediaSource media)
                           throws java.io.IOException,
                                  ServiceException

Inserts a new media resource read from MediaSource into a media feed associated with the target service. It will return the resulting entry that describes the inserted media, including any additional attributes or extensions set by the GData server. To insert both the entry and the media content in a single request, use insert(URL, BaseEntry).

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.

Parameters:

feedUrl - the POST URI associated with the target feed.

entryClass - the class used to parse the returned entry.

media - the media source that contains the media content to insert.

Returns:

the newly inserted entry returned by the service.

Throws:

java.io.IOException - error communicating with the GData service.

ParseException - error parsing the returned entry data.

ServiceException - insert request failed due to system error.

See Also:

BaseFeed.getEntryPostLink(), MediaFeed.insert(MediaSource)

updateMedia

public <E extends BaseEntry> E updateMedia(java.net.URL mediaUrl,
                                           E entry)
                                throws java.io.IOException,
                                       ServiceException

Updates an existing entry and associated media resource by writing it to the specified media edit URL. The resulting entry (after update) will be returned. To update only the media content, use updateMedia(URL, Class, MediaSource).

Parameters:

mediaUrl - the media edit URL associated with the resource.

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

BaseEntry.getMediaEditLink(), MediaEntry.updateMedia(boolean)

updateMedia

public <E extends BaseEntry> E updateMedia(java.net.URL mediaUrl,
                                           java.lang.Class<E> entryClass,
                                           MediaSource media)
                                throws java.io.IOException,
                                       ServiceException

Updates an existing media resource with data read from the MediaSource by writing it it to the specified media edit URL. The resulting entry (after update) will be returned. To update both the entry and the media content in a single request, use updateMedia(URL, BaseEntry).

Parameters:

mediaUrl - the media edit URL associated with the resource.

entryClass - the class that will be used to represent the resulting entry.

media - the media source data 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.getMediaEditLink(), MediaEntry.updateMedia(boolean)