public class

Service

extends Object
java.lang.Object
   ↳ com.google.gdata.client.Service
Known Direct Subclasses
Known Indirect Subclasses

Class Overview

The Service class represents a client connection to a GData service. It encapsulates all protocol-level interactions with the GData server and acts as a helper class for higher level entities (feeds, entries, etc) that invoke operations on the server and process their results.

This class provides the base level common functionality required to access any GData service. It is also designed to act as a base class that can be customized for specific types of GData services. Examples of supported customizations include:

  • Authentication - implementing a custom authentication mechanism for services that require authentication and use something other than HTTP basic or digest authentication.
  • Extensions - define expected extensions for feed, entry, and other types associated with a the service.
  • Formats - define additional custom resource representations that might be consumed or produced by the service and client side parsers and generators to handle them.

Summary

Nested Classes
class Service.ClientInputProperties The ClientInputProperties class is an adaptor class that implements the InputProperties interface for content to be read from the target service based upon its attributes and a Service.GDataRequest. 
class Service.ClientOutputProperties The ClientOutputProperties class is an adaptor class that implements the OutputProperties interface for content to be written to the target service based upon its attributes and a Service.GDataRequest. 
class Service.ClientStreamProperties The ClientStreamProperties class is an abstract adaptor class that implements the StreamProperties interface for content to be written to or read from the target service based upon its attributes and a Service.GDataRequest. 
interface Service.GDataRequest The GDataRequest interface represents a streaming connection to a GData service that can be used either to send request data to the service using an OutputStream (or XmlWriter for XML content) or to receive response data from the service as an InputStream (or ParseSource for XML data). 
interface Service.GDataRequestFactory The GDataRequestFactory interface defines a basic factory interface for constructing a new GDataRequest interface. 
class Service.Versions The Versions class defines Version constants representing the set of active versions of the GData core protocol and common data model classes. 
Fields
private static final AltRegistry BASE_REGISTRY The DEFAULT_REGISTRY contains the default set of representations and associated parser/generator configurations for all services.
private static final Version CORE_VERSION Initializes the default client version for the GData core protocol.
private static final String SERVICE_VERSION
private AltRegistry altRegistry The alternate representation registry that describes formats supported by the remote GData service.
protected int connectTimeout Client-configured connection timeout value.
private ContentType contentType Content type of data posted to the GData service.
protected ExtensionProfile extProfile
protected final MetadataRegistry metadataRegistry
private Version protocolVersion The version of the service protocol to use for this service instance.
int readTimeout Client configured read timeout value.
protected Service.GDataRequestFactory requestFactory The GDataRequestFactory associated with this service.
private boolean strictValidation
Public Constructors
Service()
Constructs a new Service instance that is configured to accept arbitrary extension data within feed or entry elements.
Public Methods
<F extends IFeed> F batch(URL feedUrl, F inputFeed)
Executes several operations (insert, update or delete) on the entries that are part of the input IFeed.
Service.GDataRequest createBatchRequest(URL feedUrl)
Creates a new GDataRequest that can be used to execute several insert/update/delete operations in one request by writing a feed into the request stream to read a feed containing the result of the batch operations from the response stream.
Service.GDataRequest createDeleteRequest(URL entryUrl)
Creates a new GDataRequest that can be used to delete an Atom entry.
Service.GDataRequest createEntryRequest(URL entryUrl)
Returns a GDataRequest instance that can be used to access an entry's contents as a stream, given the URL of the entry.
Service.GDataRequest createFeedRequest(URL feedUrl)
Executes a GData feed request against the target service and returns the resulting feed results via an input stream.
Service.GDataRequest createFeedRequest(Query query)
Executes a GData query request against the target service and returns the resulting feed results via an input stream.
Service.GDataRequest createInsertRequest(URL feedUrl)
Creates a new GDataRequest that can be used to insert a new entry into a feed using the request stream and to read the resulting entry content from the response stream.
Service.GDataRequest createLinkQueryRequest(ILink link)
Returns a query (GET) request that targets the provided link.
Service.GDataRequest createPatchRequest(URL entryUrl)
Creates a new GDataRequest that can be used to update an existing Atom entry.
Service.GDataRequest createRequest(Service.GDataRequest.RequestType type, URL requestUrl, ContentType inputType)
Creates a new GDataRequest for use by the service.
Service.GDataRequest createUpdateRequest(URL entryUrl)
Creates a new GDataRequest that can be used to update an existing Atom entry.
void delete(URL resourceUrl, String etag)
Deletes an existing entry (and associated media content, if any) using the specified edit URL.
void delete(URL resourceUrl)
Deletes an existing entry (and associated media content, if any) using the specified edit URL.
void delete(URI resourceUri, String etag)
Deletes an existing entry (and associated media content, if any) using the specified edit URI.
void delete(URI resourceUri)
Deletes an existing entry (and associated media content, if any) using the specified edit URI.
AltRegistry getAltRegistry()
Returns the alternate registration registry that describes representations that may be parsed from or generated to the remote GData service.
ContentType getContentType()
Returns the default ContentType for data associated with this GData service.
static AltRegistry getDefaultAltRegistry()
Returns an AltRegistry instance that is configured with the default parser/generator configuration for a media service.
<E extends IEntry> E getEntry(URL entryUrl, Class<E> entryClass, String etag)
Returns an Atom entry instance given the URL of the entry, if its current entity tag is different than the provided value.
<E extends IEntry> E getEntry(URL entryUrl, Class<E> entryClass)
Returns an Atom entry instance, given the URL of the entry.
<E extends IEntry> E getEntry(URL entryUrl, Class<E> entryClass, DateTime ifModifiedSince)
Returns an Atom entry instance, given the URL of the entry and an if-modified-since date.
ExtensionProfile getExtensionProfile()
Returns the ExtensionProfile that defines any expected extensions to the base RSS/Atom content model.
<F extends IFeed> F getFeed(URL feedUrl, Class<F> feedClass)
Returns the Feed associated with a particular feed URL.
<F extends IFeed> F getFeed(URL feedUrl, Class<F> feedClass, DateTime ifModifiedSince)
Returns the Feed associated with a particular feed URL, if it's been modified since the specified date.
<F extends IFeed> F getFeed(Query query, Class<F> feedClass, DateTime ifModifiedSince)
Returns the Feed resulting from executing a query, if it's been modified since the specified date.
<F extends IFeed> F getFeed(URL feedUrl, Class<F> feedClass, String etag)
Returns the Feed associated with a particular feed URL if the entity tag associated with it has changed.
<F extends IFeed> F getFeed(Query query, Class<F> feedClass)
Returns the feed resulting from execution of a query.
<F extends IFeed> F getFeed(Query query, Class<F> feedClass, String etag)
Returns the Feed resulting from query execution, if if the entity tag associated with it has changed.
MetadataRegistry getMetadataRegistry()
Returns the MetadataRegistry that defines the expected metadata.
Version getProtocolVersion()
Returns the service protocol version that will be used for requests generated by this service.
Service.GDataRequestFactory getRequestFactory()
Returns the GDataRequestFactory currently associated with the service.
Schema getSchema()
Returns the Schema that contains the metadata about element types parsed or generated by this service.
String getServiceVersion()
Returns information about the service version.
InputStream getStreamFromLink(ILink link)
This method is deprecated. Use createLinkQueryRequest(ILink) instead.
boolean getStrictValidation()
Returns true if strict validation is enabled for this service.
static Version getVersion()
Returns the current Version of the GData core protocol.
<E extends IEntry> E insert(URL feedUrl, E entry)
Inserts a new IEntry into a feed associated with the target service.
<S extends IServiceDocument> S introspect(URL feedUrl, Class<S> serviceClass)
Returns the Atom introspection Service Document associated with a particular feed URL.
<E> E parseResponseData(Service.GDataRequest req, Class<E> resultType)
Parses the response stream for a request based upon request properties and an expected result type.
<E extends IEntry> E patch(URL entryUrl, String fields, E entry)
Patches an existing IEntry by removing a set of selected fields and then merging a partial entry representation into the resource at the specified entry edit URL.
<E extends IEntry> E patch(URL entryUrl, String fields, E entry, String etag)
Patches an existing IEntry by removing a set of selected fields and then merging a partial entry representation into the resource at the specified entry edit URL.
<F extends IFeed> F query(Query query, Class<F> feedClass, String etag)
Executes a GData query against the target service and returns the IFeed containing entries that match the query result if the etag for the target feed does not match the provided value.
<F extends IFeed> F query(Query query, Class<F> feedClass, DateTime ifModifiedSince)
Executes a GData query against the target service and returns the IFeed containing entries that match the query result, if it's been modified since the specified date.
<F extends IFeed> F query(Query query, Class<F> feedClass)
Executes a GData query against the target service and returns the IFeed containing entries that match the query result.
void setAcceptLanguage(String acceptedLanguages)
Defines the languages accepted by the application.
void setAltRegistry(AltRegistry altRegistry)
void setConnectTimeout(int timeout)
Sets the default wait timeout (in milliseconds) for a connection to the remote GData service.
void setContentType(ContentType contentType)
Sets the default ContentType for writing data to the GData service.
void setExtensionProfile(ExtensionProfile v)
Sets the ExtensionProfile that defines any expected extensions to the base RSS/Atom content model.
void setHeader(String header, String value)
Set a header that will be included in all requests.
void setOAuthProxyHeaders(Map<String, String> headers)
Adds OAuth Proxy-related headers to the request.
void setPrivateHeader(String header, String value)
Set a header that will be included in all requests and do not log the value.
void setProtocolVersion(Version v)
Sets the service protocol version that will be used for requests associated with this service.
void setReadTimeout(int timeout)
Sets the default wait timeout (in milliseconds) for a response from the remote GData service.
void setRequestFactory(Service.GDataRequestFactory requestFactory)
Sets the GDataRequestFactory currently associated with the service.
void setStrictValidation(boolean strictValidation)
Enables or disables strict validation.
void setTimeouts(Service.GDataRequest request)
Sets timeout value for GDataRequest.
<E extends IEntry> E update(URL entryUrl, E entry)
Updates an existing IEntry by writing it to the specified entry edit URL.
<E extends IEntry> E update(URL entryUrl, E entry, String etag)
Updates an existing IEntry by writing it to the specified entry edit URL.
void useSsl()
Sets the HttpGDataRequest.Factory associate with the service to use secure connections.
void writeRequestData(Service.GDataRequest req, Object source)
Writes the request body to the target service based upon the attributes of the request and the source object.
Protected Methods
<T> Class<T> classOf(T object)
Service.GDataRequest createRequest(Query query, ContentType inputType)
Creates a new GDataRequest for querying the service.
void endVersionScope()
static Version initServiceVersion(Class<? extends Service> serviceClass, Version defaultVersion)
Initializes the version information for a specific service type.
<E> E parseResponseData(ParseSource source, ContentType responseType, Class<E> resultType)
Parses the response stream for a request based upon response content type and an expected result type.
void startVersionScope()
void writeRequestData(Service.GDataRequest req, Service.ClientOutputProperties outProps, Object source)
Writes the request body to the target service based upon requested output properties and the source object.
[Expand]
Inherited Methods
From class java.lang.Object

Fields

private static final AltRegistry BASE_REGISTRY

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

private static final Version CORE_VERSION

Initializes the default client version for the GData core protocol.

private static final String SERVICE_VERSION

private AltRegistry altRegistry

The alternate representation registry that describes formats supported by the remote GData service.

protected int connectTimeout

Client-configured connection timeout value. A value of -1 indicates the client has not set any timeout.

private ContentType contentType

Content type of data posted to the GData service. Defaults to Atom using UTF-8 character set.

protected ExtensionProfile extProfile

protected final MetadataRegistry metadataRegistry

private Version protocolVersion

The version of the service protocol to use for this service instance. It will be initialized to the service default version but can be set explicitly by calling setProtocolVersion(Version).

int readTimeout

Client configured read timeout value. A value of -1 indicates the client has not set any timeout.

protected Service.GDataRequestFactory requestFactory

The GDataRequestFactory associated with this service. The default is the base HttpGDataRequest Factory class.

private boolean strictValidation

Public Constructors

public Service ()

Constructs a new Service instance that is configured to accept arbitrary extension data within feed or entry elements.

Public Methods

public F batch (URL feedUrl, F inputFeed)

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

Parameters
feedUrl The POST URI associated with the target feed.
inputFeed 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
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 getIFeed().
See Also

public Service.GDataRequest createBatchRequest (URL feedUrl)

Creates a new GDataRequest that can be used to execute several insert/update/delete operations in one request by writing a feed into the request stream to read a feed containing the result of the batch operations from the response stream.

Clients should be sure to call end() on the returned request once they have finished using it.

Parameters
feedUrl The POST URI associated with the target feed.
Returns
  • GDataRequest to interact with remote GData service.
Throws
IOException error reading from or writing to the GData service.
ServiceException insert request failed.

public Service.GDataRequest createDeleteRequest (URL entryUrl)

Creates a new GDataRequest that can be used to delete an Atom entry. For delete requests, no input is expected from the request stream nor will any response data be returned.

Clients should be sure to call end() on the returned request once they have finished using it.

Parameters
entryUrl The edit URL associated with the entry.
Throws
IOException error communicating with the GData service.
ServiceException creation of delete request failed.

public Service.GDataRequest createEntryRequest (URL entryUrl)

Returns a GDataRequest instance that can be used to access an entry's contents as a stream, given the URL of the entry.

Clients should be sure to call end() on the returned request once they have finished using it.

Parameters
entryUrl Resource URL for the entry.
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 Service.GDataRequest createFeedRequest (URL feedUrl)

Executes a GData feed request against the target service and returns the resulting feed results via an input stream.

Parameters
feedUrl URL that defines target feed.
Returns
  • GData request instance that can be used to read the feed data.
Throws
IOException error communicating with the GData service.
ServiceException creation of query feed request failed.
See Also

public Service.GDataRequest createFeedRequest (Query query)

Executes a GData query request against the target service and returns the resulting feed results via an input stream.

Clients should be sure to call end() on the returned request once they have finished using it.

Parameters
query Feed query.
Returns
  • GData request instance that can be used to read the feed data.
Throws
IOException error communicating with the GData service.
ServiceException creation of query feed request failed.
See Also

public Service.GDataRequest createInsertRequest (URL feedUrl)

Creates a new GDataRequest that can be used to insert a new entry into a feed using the request stream and to read the resulting entry content from the response stream.

Clients should be sure to call end() on the returned request once they have finished using it.

Parameters
feedUrl The POST URI associated with the target feed.
Returns
  • GDataRequest to interact with remote GData service.
Throws
IOException error reading from or writing to the GData service.
ServiceException insert request failed.

public Service.GDataRequest createLinkQueryRequest (ILink link)

Returns a query (GET) request that targets the provided link. This can be used to execute the request and access the link's content via the response stream of the request (if successful).

Clients should be sure to call end() on the returned request once they have finished using it.

Parameters
link Link to target resource for created request
Returns
  • query request to retrieve linked content.
Throws
IOException error communicating with the GData service.
ServiceException creation of query request failed.

public Service.GDataRequest createPatchRequest (URL entryUrl)

Creates a new GDataRequest that can be used to update an existing Atom entry. The updated entry content can be written to the GDataRequest request stream and the resulting updated entry can be obtained from the GDataRequest response stream.

Clients should be sure to call end() on the returned request once they have finished using it.

Parameters
entryUrl The edit URL associated with the entry.
Throws
IOException error communicating with the GData service.
ServiceException creation of update request failed.

public Service.GDataRequest createRequest (Service.GDataRequest.RequestType type, URL requestUrl, ContentType inputType)

Creates a new GDataRequest for use by the service.

Clients should be sure to call end() on the returned request once they have finished using it.

Parameters
type
requestUrl
inputType
Throws
IOException
ServiceException

public Service.GDataRequest createUpdateRequest (URL entryUrl)

Creates a new GDataRequest that can be used to update an existing Atom entry. The updated entry content can be written to the GDataRequest request stream and the resulting updated entry can be obtained from the GDataRequest response stream.

Clients should be sure to call end() on the returned request once they have finished using it.

Parameters
entryUrl The edit URL associated with the entry.
Throws
IOException error communicating with the GData service.
ServiceException creation of update request failed.

public void delete (URL resourceUrl, String etag)

Deletes an existing entry (and associated media content, if any) using the specified edit URL. This delete is conditional upon the provided tag matching the current entity tag for the entry. If (and only if) they match, the deletion will be performed.

Parameters
resourceUrl 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.
Throws
IOException error communicating with the GData service.
ResourceNotFoundException invalid entry URL.
ServiceException delete request failed due to system error.

public void delete (URL resourceUrl)

Deletes an existing entry (and associated media content, if any) using the specified edit URL.

Parameters
resourceUrl The edit or medit edit url associated with the resource.
Throws
IOException error communicating with the GData service.
ResourceNotFoundException invalid entry URL.
ServiceException delete request failed due to system error.

public void delete (URI resourceUri, String etag)

Deletes an existing entry (and associated media content, if any) using the specified edit URI. This delete is conditional upon the provided tag matching the current entity tag for the entry. If (and only if) they match, the deletion will be performed.

Parameters
resourceUri The edit or medit edit URI 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.
Throws
IOException error communicating with the GData service.
ResourceNotFoundException invalid entry URI.
ServiceException delete request failed due to system error.

public void delete (URI resourceUri)

Deletes an existing entry (and associated media content, if any) using the specified edit URI.

Parameters
resourceUri The edit or medit edit URI associated with the resource.
Throws
IOException error communicating with the GData service.
ResourceNotFoundException invalid entry URI.
ServiceException delete request failed due to system error.

public AltRegistry getAltRegistry ()

Returns the alternate registration registry that describes representations that may be parsed from or generated to the remote GData service.

public ContentType getContentType ()

Returns the default ContentType for data associated with this GData service.

public static AltRegistry getDefaultAltRegistry ()

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

public E getEntry (URL entryUrl, Class<E> entryClass, String etag)

Returns an Atom entry instance given the URL of the entry, if its current entity tag is different than the provided value.

Parameters
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.
Throws
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 getEntry (URL entryUrl, Class<E> entryClass)

Returns an Atom entry instance, given the URL of the entry.

Parameters
entryUrl Resource URL for the entry.
entryClass Class used to represent service entries, not null.
Returns
  • the entry referenced by the URL parameter.
Throws
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.

public E getEntry (URL entryUrl, Class<E> entryClass, DateTime ifModifiedSince)

Returns an Atom entry instance, given the URL of the entry and an if-modified-since date.

Parameters
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.
Returns
  • the entry referenced by the URL parameter.
Throws
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 ExtensionProfile getExtensionProfile ()

Returns the ExtensionProfile that defines any expected extensions to the base RSS/Atom content model.

public F getFeed (URL feedUrl, Class<F> feedClass)

Returns the Feed associated with a particular feed URL.

Parameters
feedUrl The URL associated with a feed. This URL can include GData query parameters.
feedClass The class used to represent a service Feed.
Returns
  • Feed resource referenced by the input URL.
Throws
IOException error sending request or reading the feed.
ParseException error parsing the returned feed data.
ResourceNotFoundException invalid feed URL.
ServiceException system error retrieving feed.

public F getFeed (URL feedUrl, Class<F> feedClass, DateTime ifModifiedSince)

Returns the 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.
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.
Returns
  • Feed resource referenced by the input URL.
Throws
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 getFeed (Query query, Class<F> feedClass, DateTime ifModifiedSince)

Returns the Feed resulting from executing a query, if it's been modified since the specified date.

Parameters
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.
Returns
  • Feed resource referenced by the input URL.
Throws
IOException error sending request or reading the feed.
ServiceException system error retrieving feed.

public F getFeed (URL feedUrl, Class<F> feedClass, String etag)

Returns the Feed associated with a particular feed URL if the entity tag associated with it has changed.

Parameters
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.
Throws
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 getFeed (Query query, Class<F> feedClass)

Returns the feed resulting from execution of a query.

Parameters
query Feed query.
feedClass The class used to represent query results.
Returns
  • feed resource referenced by the input URL.
Throws
IOException error sending request or reading the feed.
ParseException error parsing the returned feed data.
ResourceNotFoundException invalid feed URL.
ServiceException system error retrieving feed.

public F getFeed (Query query, Class<F> feedClass, String etag)

Returns the Feed resulting from query execution, if if the entity tag associated with it has changed.

Parameters
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.
Throws
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 MetadataRegistry getMetadataRegistry ()

Returns the MetadataRegistry that defines the expected metadata.

public Version getProtocolVersion ()

Returns the service protocol version that will be used for requests generated by this service.

Returns
  • service protocol version

public Service.GDataRequestFactory getRequestFactory ()

Returns the GDataRequestFactory currently associated with the service.

public Schema getSchema ()

Returns the Schema that contains the metadata about element types parsed or generated by this service.

public String getServiceVersion ()

Returns information about the service version.

public InputStream getStreamFromLink (ILink link)

This method is deprecated.
Use createLinkQueryRequest(ILink) instead.

Returns an InputStream that contains the content referenced by a link.

Parameters
link Link that references the target resource.
Returns
  • input stream that can be used to access the resource content.
Throws
IOException error communication with the remote service.
ServiceException resource access failed due to system error.

public boolean getStrictValidation ()

Returns true if strict validation is enabled for this service.

public static Version getVersion ()

Returns the current Version of the GData core protocol.

Returns
  • protocol version.

public E insert (URL feedUrl, E entry)

Inserts a new 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.

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.
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.
See Also

public S introspect (URL feedUrl, Class<S> serviceClass)

Returns the Atom introspection Service Document associated with a particular feed URL. This document provides service metadata about the set of Atom services associated with the target feed URL.

Parameters
feedUrl The URL associated with a feed. This URL can not include any query parameters.
serviceClass The class used to represent a service document, not null.
Returns
  • ServiceDocument resource referenced by the input URL.
Throws
IOException error sending request or reading the feed.
ParseException error parsing the returned service data.
ResourceNotFoundException invalid feed URL.
ServiceException system error retrieving service document.

public E parseResponseData (Service.GDataRequest req, Class<E> resultType)

Parses the response stream for a request based upon request properties and an expected result type. The parser will be selected based upon the request alt type or response content type and used to parse the response content into the result object.

Parameters
req Request that has been executed but not yet read from.
resultType Expected result type, not null.
Returns
  • an instance of the expected result type resulting from the parse.
Throws
ServiceException
IOException

public E patch (URL entryUrl, String fields, E entry)

Patches an existing IEntry by removing a set of selected fields and then merging a partial entry representation into the resource at the specified entry edit URL. The resulting entry (after update) will be returned.

Parameters
entryUrl The edit URL associated with the entry.
fields Selection representing the set of fields to be patched from the resource.
entry The partial entry to be merged with current resource.
Returns
  • the patched Entry returned by the service.
Throws
IOException error communicating with the GData service.
ParseException error parsing the returned entry data.
ServiceException update request failed due to system error.
See Also

public E patch (URL entryUrl, String fields, E entry, String etag)

Patches an existing IEntry by removing a set of selected fields and then merging a partial entry representation into the resource at the specified entry edit URL. The resulting entry (after update) will be returned. This update is conditional upon the provided tag matching the current entity tag for the entry. If (and only if) they match, the patch will be performed.

Parameters
entryUrl The edit URL associated with the entry.
fields Selection representing the set of fields to be removed from the resource.
entry The partial entry to be merged with current 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 update.
Returns
  • the patched Entry returned by the service.
Throws
IOException error communicating with the GData service.
PreconditionFailedException if the resource entity tag does not match the provided value.
ParseException error parsing the patched entry data.
ServiceException update request failed due to system error.
See Also

public F query (Query query, Class<F> feedClass, String etag)

Executes a GData query against the target service and returns the IFeed containing entries that match the query result if the etag for the target feed does not match the provided value.

Parameters
query Query instance defining target feed and query parameters.
feedClass The Class used to represent a service Feed, not null.
etag Used to provide an entity tag that indicates the query should be be performed only if the entity tag of the current representation is different from the provided value. A value of null indicates unconditional return.
Throws
IOException error communicating with the GData service.
NotModifiedException if the feed resource entity tag matches the provided value.
ServiceForbiddenException feed does not support the query.
ParseException error parsing the returned feed data.
ServiceException query request failed.

public F query (Query query, Class<F> feedClass, DateTime ifModifiedSince)

Executes a GData query against the target service and returns the IFeed 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.
feedClass The Class used to represent a service Feed, not null.
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
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.

public F query (Query query, Class<F> feedClass)

Executes a GData query against the target service and returns the IFeed containing entries that match the query result.

Parameters
query Query instance defining target feed and query parameters.
feedClass The Class used to represent a service Feed, not null.
Throws
IOException error communicating with the GData service.
ServiceForbiddenException feed does not support the query.
ParseException error parsing the returned feed data.
ServiceException query request failed.

public void setAcceptLanguage (String acceptedLanguages)

Defines the languages accepted by the application. This parameters defines the human language the service should use for generated strings. Different services support different languages, please check the service documentation. If no language on this list is accepted by the service, and if the list does not contain * to accept all languages, the exception in the exception NotAcceptableException. The service will choose the best available language on this list. Check the attribute xml:lang on the relevant tags, such as atom:content, atom:title and atom:category.

Parameters
acceptedLanguages List of accepted languages, as defined in section 14.4 of RFC 2616

public void setAltRegistry (AltRegistry altRegistry)

Parameters
altRegistry

public void setConnectTimeout (int timeout)

Sets the default wait timeout (in milliseconds) for a connection to the remote GData service.

Parameters
timeout The read timeout. A value of zero indicates an infinite timeout.
Throws
IllegalArgumentException if the timeout value is negative.
See Also

public void setContentType (ContentType contentType)

Sets the default ContentType for writing data to the GData service.

Parameters
contentType

public void setExtensionProfile (ExtensionProfile v)

Sets the ExtensionProfile that defines any expected extensions to the base RSS/Atom content model.

Parameters
v

public void setHeader (String header, String value)

Set a header that will be included in all requests. If header of the same name was previously set, then replace the previous header value.

Parameters
header The name of the header
value The value of the header, if null, then unset that header.

public void setOAuthProxyHeaders (Map<String, String> headers)

Adds OAuth Proxy-related headers to the request. The OAuth Proxy simplifies the OAuth dance on when running in App Engine.

Parameters
headers
See Also

public void setPrivateHeader (String header, String value)

Set a header that will be included in all requests and do not log the value. Useful for values that are sensitive or related to security. If header of the same name was previously set, then replace the previous header value.

Parameters
header The name of the header
value The value of the header. If null, then unset that header.

public void setProtocolVersion (Version v)

Sets the service protocol version that will be used for requests associated with this service.

Parameters
v New service protocol version.

public void setReadTimeout (int timeout)

Sets the default wait timeout (in milliseconds) for a response from the remote GData service.

Parameters
timeout The read timeout. A value of zero indicates an infinite timeout.
Throws
IllegalArgumentException if the timeout value is negative.
See Also

public void setRequestFactory (Service.GDataRequestFactory requestFactory)

Sets the GDataRequestFactory currently associated with the service.

Parameters
requestFactory

public void setStrictValidation (boolean strictValidation)

Enables or disables strict validation. It is enabled by default. When this flag is enabled, the client library rejects unknown attributes and validates both input and output data.

Parameters
strictValidation

public void setTimeouts (Service.GDataRequest request)

Sets timeout value for GDataRequest.

Parameters
request

public E update (URL entryUrl, E entry)

Updates an existing IEntry by writing it to the specified entry edit URL. The resulting Entry (after update) will be returned.

Parameters
entryUrl The edit URL associated with the entry.
entry The modified 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.
See Also

public E update (URL entryUrl, E entry, String etag)

Updates an existing IEntry by writing it to the specified entry edit URL. The resulting entry (after update) will be returned. This update is conditional upon the provided tag matching the current entity tag for the entry. If (and only if) they match, the update will be performed.

Parameters
entryUrl The edit URL associated with the entry.
entry The modified entry to be written to the server.
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 update.
Returns
  • the updated Entry returned by the service.
Throws
IOException error communicating with the GData service.
PreconditionFailedException if the resource entity tag does not match the provided value.
ParseException error parsing the updated entry data.
ServiceException update request failed due to system error.
See Also

public void useSsl ()

Sets the HttpGDataRequest.Factory associate with the service to use secure connections.

public void writeRequestData (Service.GDataRequest req, Object source)

Writes the request body to the target service based upon the attributes of the request and the source object.

Parameters
req Currently executing request
source Source object to be written
Throws
IOException

Protected Methods

protected Class<T> classOf (T object)

Parameters
object

protected Service.GDataRequest createRequest (Query query, ContentType inputType)

Creates a new GDataRequest for querying the service.

Clients should be sure to call end() on the returned request once they have finished using it.

Parameters
query
inputType
Throws
IOException
ServiceException

protected void endVersionScope ()

protected static Version initServiceVersion (Class<? extends Service> serviceClass, Version defaultVersion)

Initializes the version information for a specific service type. Subclasses of Service will generally call this method from within their static initializers to bind version information for the associated service.

Parameters
serviceClass The service type being initialized.
defaultVersion The service version expected by this client library.

protected E parseResponseData (ParseSource source, ContentType responseType, Class<E> resultType)

Parses the response stream for a request based upon response content type and an expected result type. The parser will be selected based upon the request alt type or response content type and used to parse the response content into the result object.

Parameters
source
responseType Content type of the response to parse.
resultType Expected result type, not null.
Returns
  • an instance of the expected result type resulting from the parse.
Throws
ServiceException
IOException

protected void startVersionScope ()

protected void writeRequestData (Service.GDataRequest req, Service.ClientOutputProperties outProps, Object source)

Writes the request body to the target service based upon requested output properties and the source object.

Parameters
req
outProps Client output properties
source Source object to be written
Throws
IOException