Google Data APIs Client Library (1.41.1)



com.google.gdata.client.media
Class MediaService

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
All Implemented Interfaces:
AuthTokenFactory.TokenListener
Direct Known Subclasses:
DocsService, GoogleBaseService, GttService, MailItemService, MapsService, PicasawebService, SitesService, 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.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, Service.Versions
 
Field Summary
static int DEFAULT_CHUNKED_BUFFER_SIZE
          Used to set the default buffer size when using Transfer-Encoding: chunked.
static int NO_CHUNKED_MEDIA_REQUEST
          Used to specify that the media write requests will not be chunked, but sent in one piece.
 
Fields inherited from class com.google.gdata.client.Service
connectTimeout, extProfile, metadataRegistry, requestFactory
 
Constructor Summary
MediaService(java.lang.String applicationName, Service.GDataRequestFactory requestFactory, AuthTokenFactory authTokenFactory)
          Constructs an instance connecting to the service for an application with the name applicationName and the given GDataRequestFactory and AuthTokenFactory.
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
static com.google.gdata.wireformats.AltRegistry getDefaultAltRegistry()
          Returns an AltRegistry instance that is configured with the default parser/generator configuration for a media service.
 MediaSource getMedia(IMediaContent mediaContent)
          Returns a MediaSource that can be used to read the external media content of an entry.
 MediaSource getMedia(IMediaContent mediaContent, DateTime ifModifiedSince)
          Returns a MediaSource that can be used to read the external media content of an entry.
<E extends IEntry>
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 IEntry>
E
insert(java.net.URL feedUrl, E entry)
          Inserts a new Entry into a feed associated with the target service.
 void setChunkedMediaUpload(int chunkSizeInBytes)
          Configures the service to use chunked streaming mode for media write requests.
<E extends IEntry>
E
update(java.net.URL url, E entry)
          Updates an existing entry metadata by writing it to the specified edit URL.
<E extends IEntry>
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 IEntry>
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, batch, 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, getServiceVersion, 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

DEFAULT_CHUNKED_BUFFER_SIZE

public static final int DEFAULT_CHUNKED_BUFFER_SIZE
Used to set the default buffer size when using Transfer-Encoding: chunked. Setting this to 0 uses the default which is 4MB.

See Also:
Constant Field Values

NO_CHUNKED_MEDIA_REQUEST

public static final int NO_CHUNKED_MEDIA_REQUEST
Used to specify that the media write requests will not be chunked, but sent in one piece.

See Also:
setChunkedMediaUpload(int), Constant Field Values
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 applicationName,
                    Service.GDataRequestFactory requestFactory,
                    AuthTokenFactory authTokenFactory)
Constructs an instance connecting to the service for an application with the name applicationName and the given GDataRequestFactory and AuthTokenFactory. Use this constructor to override the default factories.

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.
requestFactory - the request factory that generates gdata request objects
authTokenFactory - the factory that creates auth tokens

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

getDefaultAltRegistry

public static com.google.gdata.wireformats.AltRegistry getDefaultAltRegistry()
Returns an AltRegistry instance that is configured with the default parser/generator configuration for a media service.


setChunkedMediaUpload

public void setChunkedMediaUpload(int chunkSizeInBytes)
Configures the service to use chunked streaming mode for media write requests.

By default, the service is configured to use Transfer-Encoding: chunked using the DEFAULT_CHUNKED_BUFFER_SIZE. Use this method to change the size buffer size, or to disable the chunked mode entirely.

Parameters:
chunkSizeInBytes - specifies the buffer size (in bytes) to be used when sending a media write request. Use DEFAULT_CHUNKED_BUFFER_SIZE for the default value. Use NO_CHUNKED_MEDIA_REQUEST for not using chunked requests. Use a positive number to specify the size of each buffer.
See Also:
HttpURLConnection.setChunkedStreamingMode(int)

getMedia

public MediaSource getMedia(IMediaContent 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(IMediaContent 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 IEntry> 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 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 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:
IFeed.getEntryPostLink()

insert

public <E extends IEntry> 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, IEntry).

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:
IFeed.getEntryPostLink(), MediaFeed.insert(MediaSource)

update

public <E extends IEntry> E update(java.net.URL url,
                                   E entry)
                        throws java.io.IOException,
                               ServiceException
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 updateMedia(URL, IEntry). To update media only, use updateMedia(URL, Class, MediaSource).

Overrides:
update in class GoogleService
Parameters:
url - 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:
IEntry.getMediaEditLink()

updateMedia

public <E extends IEntry> 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:
IEntry.getMediaEditLink()

updateMedia

public <E extends IEntry> 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, IEntry).

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:
IEntry.getMediaEditLink()