# Google Data APIs Client Library (1.43.0)

## com.google.gdata.client
Class Service

    java.lang.Object
      com.google.gdata.client.Service

Direct Known Subclasses:
  GoogleService

    public class Service

extends java.lang.Object

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.

Nested Class Summary
`protected 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`.
`protected 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`.
`static 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).
`static interface` `Service.GDataRequestFactory` The GDataRequestFactory interface defines a basic factory interface for constructing a new GDataRequest interface.
`static 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.

Field Summary
`protected int` `connectTimeout` Client-configured connection timeout value.
`protected ExtensionProfile` `extProfile`
`protected com.google.gdata.model.MetadataRegistry` `metadataRegistry`
`protected Service.GDataRequestFactory` `requestFactory` The GDataRequestFactory associated with this service.

Constructor Summary
`Service()` Constructs a new Service instance that is configured to accept arbitrary extension data within feed or entry elements.

Method Summary

`

`<F extends IFeed> F`

`

`batch(java.net.URL feedUrl, F inputFeed)`
Executes several operations (insert, update or delete) on the entries that are part of the input `IFeed`.

`protected

`<T> java.lang.Class<T>`

`

`classOf(T object)`

`Service.GDataRequest` `createBatchRequest(java.net.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(java.net.URL entryUrl)` Creates a new GDataRequest that can be used to delete an Atom entry.
`Service.GDataRequest` `createEntryRequest(java.net.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(Query query)` Executes a GData query request against the target service and returns the resulting feed results via an input stream.
`Service.GDataRequest` `createFeedRequest(java.net.URL feedUrl)` Executes a GData feed request against the target service and returns the resulting feed results via an input stream.
`Service.GDataRequest` `createInsertRequest(java.net.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(java.net.URL entryUrl)` Creates a new GDataRequest that can be used to update an existing Atom entry.
`protected Service.GDataRequest` `createRequest(Query query, ContentType inputType)` Creates a new GDataRequest for querying the service.
`Service.GDataRequest` `createRequest(Service.GDataRequest.RequestType type, java.net.URL requestUrl, ContentType inputType)` Creates a new GDataRequest for use by the service.
`Service.GDataRequest` `createUpdateRequest(java.net.URL entryUrl)` Creates a new GDataRequest that can be used to update an existing Atom entry.
`void` `delete(java.net.URI resourceUri)` Deletes an existing entry (and associated media content, if any) using the specified edit URI.
`void` `delete(java.net.URI resourceUri, java.lang.String etag)` Deletes an existing entry (and associated media content, if any) using the specified edit URI.
`void` `delete(java.net.URL resourceUrl)` Deletes an existing entry (and associated media content, if any) using the specified edit URL.
`void` `delete(java.net.URL resourceUrl, java.lang.String etag)` Deletes an existing entry (and associated media content, if any) using the specified edit URL.
`protected void` `endVersionScope()`
`com.google.gdata.wireformats.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 com.google.gdata.wireformats.AltRegistry` `getDefaultAltRegistry()` Returns an `AltRegistry` instance that is configured with the default parser/generator configuration for a media service.

`

`<E extends IEntry> E`

`

`getEntry(java.net.URL entryUrl, java.lang.Class<E> entryClass)`
Returns an Atom entry instance, given the URL of the entry.

`

`<E extends IEntry> E`

`

`getEntry(java.net.URL entryUrl, java.lang.Class<E> entryClass, DateTime ifModifiedSince)`
Returns an Atom entry instance, given the URL of the entry and an if-modified-since date.

`

`<E extends IEntry> E`

`

`getEntry(java.net.URL entryUrl, java.lang.Class<E> entryClass, java.lang.String etag)`
Returns an Atom entry instance given the URL of the entry, if its current entity tag is different than the provided value.

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

`

`<F extends IFeed> F`

`

`getFeed(Query query, java.lang.Class<F> feedClass)`
Returns the feed resulting from execution of a query.

`

`<F extends IFeed> F`

`

`getFeed(Query query, java.lang.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(Query query, java.lang.Class<F> feedClass, java.lang.String etag)`
Returns the Feed resulting from query execution, if if the entity tag associated with it has changed.

`

`<F extends IFeed> F`

`

`getFeed(java.net.URL feedUrl, java.lang.Class<F> feedClass)`
Returns the Feed associated with a particular feed URL.

`

`<F extends IFeed> F`

`

`getFeed(java.net.URL feedUrl, java.lang.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(java.net.URL feedUrl, java.lang.Class<F> feedClass, java.lang.String etag)`
Returns the Feed associated with a particular feed URL if the entity tag associated with it has changed.

`com.google.gdata.model.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.
`com.google.gdata.model.Schema` `getSchema()` Returns the `Schema` that contains the metadata about element types parsed or generated by this service.
`java.lang.String` `getServiceVersion()` Returns information about the service version.
`java.io.InputStream` `getStreamFromLink(ILink link)` 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.
`protected static Version` `initServiceVersion(java.lang.Class<? extends Service> serviceClass, Version defaultVersion)` Initializes the version information for a specific service type.

`

`<E extends IEntry> E`

`

`insert(java.net.URL feedUrl, E entry)`
Inserts a new `IEntry` into a feed associated with the target service.

`

`<S extends IServiceDocument> S`

`

`introspect(java.net.URL feedUrl, java.lang.Class<S> serviceClass)`
Returns the Atom introspection Service Document associated with a particular feed URL.

`protected

`<E> E`

`

`parseResponseData(ParseSource source, ContentType responseType, java.lang.Class<E> resultType)`
Parses the response stream for a request based upon response content type and an expected result type.

`

`<E> E`

`

`parseResponseData(Service.GDataRequest req, java.lang.Class<E> resultType)`
Parses the response stream for a request based upon request properties and an expected result type.

`

`<E extends IEntry> E`

`

`patch(java.net.URL entryUrl, java.lang.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(java.net.URL entryUrl, java.lang.String fields, E entry, java.lang.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, java.lang.Class<F> feedClass)`
Executes a GData query against the target service and returns the `IFeed` containing entries that match the query result.

`

`<F extends IFeed> F`

`

`query(Query query, java.lang.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, java.lang.Class<F> feedClass, java.lang.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.

`void` `setAcceptLanguage(java.lang.String acceptedLanguages)` Defines the languages accepted by the application.
`void` `setAltRegistry(com.google.gdata.wireformats.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(java.lang.String header, java.lang.String value)` Set a header that will be included in all requests.
`void` `setOAuthProxyHeaders(java.util.Map<java.lang.String,java.lang.String> headers)` Adds OAuth Proxy-related headers to the request.
`void` `setPrivateHeader(java.lang.String header, java.lang.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.
`protected void` `startVersionScope()`

`

`<E extends IEntry> E`

`

`update(java.net.URL entryUrl, E entry)`
Updates an existing `IEntry` by writing it to the specified entry edit URL.

`

`<E extends IEntry> E`

`

`update(java.net.URL entryUrl, E entry, java.lang.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, java.lang.Object source)` Writes the request body to the target service based upon the attributes of the request and the source object.
`protected void` `writeRequestData(Service.GDataRequest req, Service.ClientOutputProperties outProps, java.lang.Object source)` Writes the request body to the target service based upon requested output properties and the source object.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### extProfile

    protected ExtensionProfile extProfile

### metadataRegistry

    protected final com.google.gdata.model.MetadataRegistry metadataRegistry

### requestFactory

    protected Service.GDataRequestFactory requestFactory

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

### connectTimeout

    protected int connectTimeout

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

Constructor Detail

### Service

    public Service()

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

Method Detail

### initServiceVersion

    protected static Version initServiceVersion(java.lang.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.

### getVersion

    public static Version getVersion()

  Returns the current `Version` of the GData core protocol.

  Returns:
    protocol version.

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

### getProtocolVersion

    public Version getProtocolVersion()

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

  Returns:
    service protocol version

### setProtocolVersion

    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.

### startVersionScope

    protected void startVersionScope()

### endVersionScope

    protected void endVersionScope()

### getServiceVersion

    public java.lang.String getServiceVersion()

  Returns information about the service version.

### getExtensionProfile

    public ExtensionProfile getExtensionProfile()

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

### setExtensionProfile

    public void setExtensionProfile(ExtensionProfile v)

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

### getMetadataRegistry

    public com.google.gdata.model.MetadataRegistry getMetadataRegistry()

  Returns the `MetadataRegistry` that defines the expected metadata.

### getSchema

    public com.google.gdata.model.Schema getSchema()

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

### getRequestFactory

    public Service.GDataRequestFactory getRequestFactory()

  Returns the GDataRequestFactory currently associated with the service.

### setRequestFactory

    public void setRequestFactory(Service.GDataRequestFactory requestFactory)

  Sets the GDataRequestFactory currently associated with the service.

### setHeader

    public void setHeader(java.lang.String header,
                          java.lang.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.

### setPrivateHeader

    public void setPrivateHeader(java.lang.String header,
                                 java.lang.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.

### setOAuthProxyHeaders

    public void setOAuthProxyHeaders(java.util.Map<java.lang.String,java.lang.String> headers)

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

  See Also:
    http://sites.google.com/site/oauthgoog/Home/gaeoauthproxy

### useSsl

    public void useSsl()

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

### setAcceptLanguage

    public void setAcceptLanguage(java.lang.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

### createRequest

    public Service.GDataRequest createRequest(Service.GDataRequest.RequestType type,
                                              java.net.URL requestUrl,
                                              ContentType inputType)
                                       throws java.io.IOException,
                                              ServiceException

  Creates a new GDataRequest for use by the service.

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

  Throws:
    `java.io.IOException`
    `ServiceException`

### createRequest

    protected Service.GDataRequest createRequest(Query query,
                                                 ContentType inputType)
                                          throws java.io.IOException,
                                                 ServiceException

  Creates a new GDataRequest for querying the service.

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

  Throws:
    `java.io.IOException`
    `ServiceException`

### setTimeouts

    public void setTimeouts(Service.GDataRequest request)

  Sets timeout value for GDataRequest.

### getContentType

    public ContentType getContentType()

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

### setContentType

    public void setContentType(ContentType contentType)

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

### setConnectTimeout

    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:
    `java.lang.IllegalArgumentException` - if the timeout value is negative.
  See Also:
    `URLConnection.setConnectTimeout(int)`

### setReadTimeout

    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:
    `java.lang.IllegalArgumentException` - if the timeout value is negative.
  See Also:
    `URLConnection.setReadTimeout(int)`

### getAltRegistry

    public com.google.gdata.wireformats.AltRegistry getAltRegistry()

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

### setAltRegistry

    public void setAltRegistry(com.google.gdata.wireformats.AltRegistry altRegistry)

### getStrictValidation

    public boolean getStrictValidation()

  Returns `true` if strict validation is enabled for this service.

### setStrictValidation

    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.

### classOf

    protected <T> java.lang.Class<T> classOf(T object)

### introspect

    public <S extends IServiceDocument> S introspect(java.net.URL feedUrl,
                                                     java.lang.Class<S> serviceClass)
                                          throws java.io.IOException,
                                                 ServiceException

  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:
    `java.io.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.

### getFeed

    public <F extends IFeed> F getFeed(java.net.URL feedUrl,
                                       java.lang.Class<F> feedClass,
                                       DateTime ifModifiedSince)
                            throws java.io.IOException,
                                   ServiceException

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

### getFeed

    public <F extends IFeed> F getFeed(java.net.URL feedUrl,
                                       java.lang.Class<F> feedClass,
                                       java.lang.String etag)
                            throws java.io.IOException,
                                   ServiceException

  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:
    `java.io.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.

### getFeed

    public <F extends IFeed> F getFeed(java.net.URL feedUrl,
                                       java.lang.Class<F> feedClass)
                            throws java.io.IOException,
                                   ServiceException

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

### getFeed

    public <F extends IFeed> F getFeed(Query query,
                                       java.lang.Class<F> feedClass)
                            throws java.io.IOException,
                                   ServiceException

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

### getFeed

    public <F extends IFeed> F getFeed(Query query,
                                       java.lang.Class<F> feedClass,
                                       DateTime ifModifiedSince)
                            throws java.io.IOException,
                                   ServiceException

  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:
    `java.io.IOException` - error sending request or reading the feed.
    `ServiceException` - system error retrieving feed.

### getFeed

    public <F extends IFeed> F getFeed(Query query,
                                       java.lang.Class<F> feedClass,
                                       java.lang.String etag)
                            throws java.io.IOException,
                                   ServiceException

  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:
    `java.io.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.

### createFeedRequest

    public Service.GDataRequest createFeedRequest(java.net.URL feedUrl)
                                           throws java.io.IOException,
                                                  ServiceException

  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:
    `java.io.IOException` - error communicating with the GData service.
    `ServiceException` - creation of query feed request failed.
  See Also:
    `Query.getUrl()`

### query

    public <F extends IFeed> F query(Query query,
                                     java.lang.Class<F> feedClass)
                          throws java.io.IOException,
                                 ServiceException

  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:
    `java.io.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.

### query

    public <F extends IFeed> F query(Query query,
                                     java.lang.Class<F> feedClass,
                                     DateTime ifModifiedSince)
                          throws java.io.IOException,
                                 ServiceException

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

### query

    public <F extends IFeed> F query(Query query,
                                     java.lang.Class<F> feedClass,
                                     java.lang.String etag)
                          throws java.io.IOException,
                                 ServiceException

  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:
    `java.io.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.

### createFeedRequest

    public Service.GDataRequest createFeedRequest(Query query)
                                           throws java.io.IOException,
                                                  ServiceException

  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 `Service.GDataRequest.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:
    `java.io.IOException` - error communicating with the GData service.
    `ServiceException` - creation of query feed request failed.
  See Also:
    `Query.getUrl()`

### getEntry

    public <E extends IEntry> E getEntry(java.net.URL entryUrl,
                                         java.lang.Class<E> entryClass)
                              throws java.io.IOException,
                                     ServiceException

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

### getEntry

    public <E extends IEntry> E getEntry(java.net.URL entryUrl,
                                         java.lang.Class<E> entryClass,
                                         DateTime ifModifiedSince)
                              throws java.io.IOException,
                                     ServiceException

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

### getEntry

    public <E extends IEntry> E getEntry(java.net.URL entryUrl,
                                         java.lang.Class<E> entryClass,
                                         java.lang.String etag)
                              throws java.io.IOException,
                                     ServiceException

  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:
    `java.io.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.

### createEntryRequest

    public Service.GDataRequest createEntryRequest(java.net.URL entryUrl)
                                            throws java.io.IOException,
                                                   ServiceException

  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 `Service.GDataRequest.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:
    `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 `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:
    `java.io.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:
    `IFeed.getEntryPostLink()`

### batch

    public <F extends IFeed> F batch(java.net.URL feedUrl,
                                     F inputFeed)
                          throws java.io.IOException,
                                 ServiceException,
                                 BatchInterruptedException

  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:
    `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()`

### createInsertRequest

    public Service.GDataRequest createInsertRequest(java.net.URL feedUrl)
                                             throws java.io.IOException,
                                                    ServiceException

  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 `Service.GDataRequest.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:
    `java.io.IOException` - error reading from or writing to the GData service.
    `ServiceException` - insert request failed.

### createBatchRequest

    public Service.GDataRequest createBatchRequest(java.net.URL feedUrl)
                                            throws java.io.IOException,
                                                   ServiceException

  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 `Service.GDataRequest.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:
    `java.io.IOException` - error reading from or writing to the GData service.
    `ServiceException` - insert request failed.

### update

    public <E extends IEntry> E update(java.net.URL entryUrl,
                                       E entry)
                            throws java.io.IOException,
                                   ServiceException

  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:
    `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.getEditLink()`

### update

    public <E extends IEntry> E update(java.net.URL entryUrl,
                                       E entry,
                                       java.lang.String etag)
                            throws java.io.IOException,
                                   ServiceException

  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:
    `java.io.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:
    `IEntry.getEditLink()`

### createUpdateRequest

    public Service.GDataRequest createUpdateRequest(java.net.URL entryUrl)
                                             throws java.io.IOException,
                                                    ServiceException

  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 `Service.GDataRequest.end()` on the returned request once they have finished using it.

  Parameters:
    `entryUrl` - the edit URL associated with the entry.
  Throws:
    `java.io.IOException` - error communicating with the GData service.
    `ServiceException` - creation of update request failed.

### patch

    public <E extends IEntry> E patch(java.net.URL entryUrl,
                                      java.lang.String fields,
                                      E entry)
                           throws java.io.IOException,
                                  ServiceException

  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:
    `java.io.IOException` - error communicating with the GData service.
    `ParseException` - error parsing the returned entry data.
    `ServiceException` - update request failed due to system error.
  See Also:
    `IEntry.getEditLink()`

### patch

    public <E extends IEntry> E patch(java.net.URL entryUrl,
                                      java.lang.String fields,
                                      E entry,
                                      java.lang.String etag)
                           throws java.io.IOException,
                                  ServiceException

  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:
    `java.io.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:
    `IEntry.getEditLink()`

### createPatchRequest

    public Service.GDataRequest createPatchRequest(java.net.URL entryUrl)
                                            throws java.io.IOException,
                                                   ServiceException

  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 `Service.GDataRequest.end()` on the returned request once they have finished using it.

  Parameters:
    `entryUrl` - the edit URL associated with the entry.
  Throws:
    `java.io.IOException` - error communicating with the GData service.
    `ServiceException` - creation of update request failed.

### delete

    public void delete(java.net.URL resourceUrl)
                throws java.io.IOException,
                       ServiceException

  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:
    `java.io.IOException` - error communicating with the GData service.
    `ResourceNotFoundException` - invalid entry URL.
    `ServiceException` - delete request failed due to system error.

### delete

    public void delete(java.net.URI resourceUri)
                throws java.io.IOException,
                       ServiceException

  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:
    `java.io.IOException` - error communicating with the GData service.
    `ResourceNotFoundException` - invalid entry URI.
    `ServiceException` - delete request failed due to system error.

### delete

    public void delete(java.net.URL resourceUrl,
                       java.lang.String etag)
                throws java.io.IOException,
                       ServiceException

  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:
    `java.io.IOException` - error communicating with the GData service.
    `ResourceNotFoundException` - invalid entry URL.
    `ServiceException` - delete request failed due to system error.

### delete

    public void delete(java.net.URI resourceUri,
                       java.lang.String etag)
                throws java.io.IOException,
                       ServiceException

  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:
    `java.io.IOException` - error communicating with the GData service.
    `ResourceNotFoundException` - invalid entry URI.
    `ServiceException` - delete request failed due to system error.

### createDeleteRequest

    public Service.GDataRequest createDeleteRequest(java.net.URL entryUrl)
                                             throws java.io.IOException,
                                                    ServiceException

  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 `Service.GDataRequest.end()` on the returned request once they have finished using it.

  Parameters:
    `entryUrl` - the edit URL associated with the entry.
  Throws:
    `java.io.IOException` - error communicating with the GData service.
    `ServiceException` - creation of delete request failed.

### getStreamFromLink

    @Deprecated
    public java.io.InputStream getStreamFromLink(ILink link)
                                          throws java.io.IOException,
                                                 ServiceException

  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:
    `java.io.IOException` - error communication with the remote service.
    `ServiceException` - resource access failed due to system error.

### createLinkQueryRequest

    public Service.GDataRequest createLinkQueryRequest(ILink link)
                                                throws java.io.IOException,
                                                       ServiceException

  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 `Service.GDataRequest.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:
    `java.io.IOException` - error communicating with the GData service.
    `ServiceException` - creation of query request failed.

### writeRequestData

    public void writeRequestData(Service.GDataRequest req,
                                 java.lang.Object source)
                          throws java.io.IOException

  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:
    `java.io.IOException`

### writeRequestData

    protected void writeRequestData(Service.GDataRequest req,
                                    Service.ClientOutputProperties outProps,
                                    java.lang.Object source)
                             throws java.io.IOException

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

  Parameters:
    `outProps` - client output properties
    `source` - source object to be written
  Throws:
    `java.io.IOException`

### parseResponseData

    public <E> E parseResponseData(Service.GDataRequest req,
                                   java.lang.Class<E> resultType)
                        throws java.io.IOException,
                               ServiceException

  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.

  Type Parameters:
    `E` - expected result type
  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:
    `java.io.IOException`
    `ServiceException`

### parseResponseData

    protected <E> E parseResponseData(ParseSource source,
                                      ContentType responseType,
                                      java.lang.Class<E> resultType)
                           throws java.io.IOException,
                                  ServiceException

  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.

  Type Parameters:
    `E` - expected result type
  Parameters:
    `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:
    `java.io.IOException`
    `ServiceException`