Google Data APIs Client Library (1.41.1)



com.google.gdata.client
Class Service

java.lang.Object
  extended by 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:


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


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)

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

protected 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

protected <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