public class

MediaService

extends GoogleService
java.lang.Object
   ↳ com.google.gdata.client.Service
     ↳ com.google.gdata.client.GoogleService
       ↳ com.google.gdata.client.media.MediaService
Known Direct Subclasses

Class Overview

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.

Summary

Constants
int DEFAULT_CHUNKED_BUFFER_SIZE Used to set the default buffer size when using Transfer-Encoding: chunked.
int NO_CHUNKED_MEDIA_REQUEST Used to specify that the media write requests will not be chunked, but sent in one piece.
Fields
private static final AltRegistry MEDIA_REGISTRY The DEFAULT_REGISTRY contains the default set of representations and associated parser/generator configurations for media services.
private static final PercentEscaper SLUG_ESCAPER An escaper for slug header values.
private int chunkedBufferSize The size of the buffer to send media write requests, when using Transfer-Encoding: chunked.
[Expand]
Inherited Fields
From class com.google.gdata.client.GoogleService
From class com.google.gdata.client.Service
Public Constructors
MediaService(String serviceName, String applicationName)
Constructs a MediaService instance connecting to the service with name serviceName for an application with the name applicationName.
MediaService(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(String serviceName, String applicationName, String protocol, String domainName)
Constructs a MediaService instance connecting to the service with name serviceName for an application with the name applicationName.
Public Methods
static AltRegistry getDefaultAltRegistry()
Returns an AltRegistry instance that is configured with the default parser/generator configuration for a media service.
MediaSource getMedia(IMediaContent mediaContent, DateTime ifModifiedSince)
Returns a MediaSource that can be used to read the external media content of an entry.
MediaSource getMedia(IMediaContent mediaContent)
Returns a MediaSource that can be used to read the external media content of an entry.
<E extends IEntry> E insert(URL feedUrl, E entry)
Inserts a new Entry into a feed associated with the target service.
<E extends IEntry> E insert(URL feedUrl, Class<E> entryClass, MediaSource media)
Inserts a new media resource read from MediaSource into a media 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(URL url, E entry)
Updates an existing entry metadata by writing it to the specified edit URL.
<E extends IEntry> E updateMedia(URL mediaUrl, 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(URL mediaUrl, E entry)
Updates an existing entry and associated media resource by writing it to the specified media edit URL.
[Expand]
Inherited Methods
From class com.google.gdata.client.GoogleService
From class com.google.gdata.client.Service
From class java.lang.Object
From interface com.google.gdata.client.AuthTokenFactory.TokenListener

Constants

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.

Constant Value: 0 (0x00000000)

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.

Constant Value: -1 (0xffffffff)

Fields

private static final AltRegistry MEDIA_REGISTRY

The DEFAULT_REGISTRY contains the default set of representations and associated parser/generator configurations for media services. It will be used as the default configuration for all MediaService instances unless setAltRegistry(AltRegistry) is called.

private static final PercentEscaper SLUG_ESCAPER

An escaper for slug header values. From the atom spec, the range %20-24 and %26-7E are unescaped. The PercentEscaper always includes [0-9a-zA-Z] as safe characters, so we add the rest of the unescaped characters: " !\"#$&'()*+,-./:;<=>?@[\\]^_`{|}~"

private int chunkedBufferSize

The size of the buffer to send media write requests, when using Transfer-Encoding: chunked. If the value is equal to NO_CHUNKED_MEDIA_REQUEST, no chunking will be performed.

Public Constructors

public MediaService (String serviceName, 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.

public MediaService (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

public MediaService (String serviceName, String applicationName, String protocol, 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

Public Methods

public static AltRegistry getDefaultAltRegistry ()

Returns an AltRegistry instance that is configured with the default parser/generator configuration for a media service.

public MediaSource getMedia (IMediaContent mediaContent, DateTime ifModifiedSince)

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
IOException error communicating with the GData service.
ServiceException entry request creation failed.

public MediaSource getMedia (IMediaContent mediaContent)

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
IOException error communicating with the GData service.
ServiceException entry request creation failed.

public E insert (URL feedUrl, E entry)

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 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 (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).

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
IOException error communicating with the GData service.
ParseException error parsing the return entry data.
ServiceException insert request failed due to system error.

public E insert (URL feedUrl, Class<E> entryClass, MediaSource media)

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 (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
IOException error communicating with the GData service.
ParseException error parsing the returned entry data.
ServiceException insert request failed due to system error.

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.

public E update (URL url, E entry)

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).

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
IOException error communicating with the GData service.
ParseException error parsing the updated entry data.
ServiceException update request failed due to system error.

public E updateMedia (URL mediaUrl, 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. 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
IOException error communicating with the GData service.
ParseException error parsing the updated entry data.
ServiceException update request failed due to system error.

public E updateMedia (URL mediaUrl, E entry)

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
IOException error communicating with the GData service.
ParseException error parsing the updated entry data.
ServiceException update request failed due to system error.