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
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  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 BaseFeed<?,?>>
F
batch(java.net.URL feedUrl, F inputFeed)
          Executes several operations (insert, update or delete) on the entries that are part of the input Feed.
protected  void closeSource(ParseSource source)
          Closes streams and readers associated with a parse source.
 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.
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()
           
 ContentType getContentType()
          Returns the default ContentType for data associated with this GData service.
<E extends BaseEntry<?>>
E
getEntry(java.net.URL entryUrl, java.lang.Class<E> entryClass)
          Returns an Atom entry instance, given the URL of the entry.
<E extends BaseEntry<?>>
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 BaseEntry<?>>
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 BaseFeed<?,?>>
F
getFeed(Query query, java.lang.Class<F> feedClass)
          Returns the Feed associated with a particular query.
<F extends BaseFeed<?,?>>
F
getFeed(Query query, java.lang.Class<F> feedClass, DateTime ifModifiedSince)
          Returns the Feed associated with a particular query, if it's been modified since the specified date.
<F extends BaseFeed<?,?>>
F
getFeed(Query query, java.lang.Class<F> feedClass, java.lang.String etag)
          Returns the Feed associated with a particular query, if if the entity tag associated with it has changed.
<F extends BaseFeed<?,?>>
F
getFeed(java.net.URL feedUrl, java.lang.Class<F> feedClass)
          Returns the Feed associated with a particular feed URL.
<F extends BaseFeed<?,?>>
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 BaseFeed<?,?>>
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.
 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.
 java.lang.String getServiceVersion()
          Returns information about the service version.
 java.io.InputStream getStreamFromLink(Link link)
           
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 BaseEntry<?>>
E
insert(java.net.URL feedUrl, E entry)
          Inserts a new Entry into a feed associated with the target service.
<S extends ServiceDocument>
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 extends BaseEntry<?>>
E
parseEntry(java.lang.Class<E> entryClass, ParseSource entrySource)
          Parse an entry of the specified class from a parse source.
<F extends BaseFeed<?,?>>
F
query(Query query, java.lang.Class<F> feedClass)
          Executes a GData query against the target service and returns the Feed containing entries that match the query result.
<F extends BaseFeed<?,?>>
F
query(Query query, java.lang.Class<F> feedClass, DateTime ifModifiedSince)
          Executes a GData query against the target service and returns the Feed containing entries that match the query result, if it's been modified since the specified date.
<F extends BaseFeed<?,?>>
F
query(Query query, java.lang.Class<F> feedClass, java.lang.String etag)
          Executes a GData query against the target service and returns the Feed 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 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 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 BaseEntry<?>>
E
update(java.net.URL entryUrl, E entry)
          Updates an existing Entry by writing it to the specified entry edit URL.
<E extends BaseEntry<?>>
E
update(java.net.URL entryUrl, E entry, java.lang.String etag)
          Updates an existing Entry by writing it to the specified entry edit URL.
 void useSsl()
          Sets the HttpGDataRequest.Factory associate with the service to use secure connections.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

extProfile

protected ExtensionProfile extProfile

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.

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.


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.


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. For query requests, use createRequest(Query, ContentType) instead.

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.

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)

parseEntry

protected <E extends BaseEntry<?>> E parseEntry(java.lang.Class<E> entryClass,
                                                ParseSource entrySource)
                                     throws java.io.IOException,
                                            ServiceException
Parse an entry of the specified class from a parse source.

Throws:
java.io.IOException
ServiceException

introspect

public <S extends ServiceDocument> 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.
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 BaseFeed<?,?>> 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 BaseFeed<?,?>> 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 BaseFeed<?,?>> 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 BaseFeed<?,?>> F getFeed(Query query,
                                           java.lang.Class<F> feedClass)
                                throws java.io.IOException,
                                       ServiceException
Returns the Feed associated with a particular query.

Parameters:
query - feed query.
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 BaseFeed<?,?>> F getFeed(Query query,
                                           java.lang.Class<F> feedClass,
                                           DateTime ifModifiedSince)
                                throws java.io.IOException,
                                       ServiceException
Returns the Feed associated with a particular 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 BaseFeed<?,?>> F getFeed(Query query,
                                           java.lang.Class<F> feedClass,
                                           java.lang.String etag)
                                throws java.io.IOException,
                                       ServiceException
Returns the Feed associated with a particular query, if if the entity tag associated with it has changed.

Parameters:
query - feed query.
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.

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

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.

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 BaseEntry<?>> 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.
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 BaseEntry<?>> 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.
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 BaseEntry<?>> 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.
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.

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.

query

public <F extends BaseFeed<?,?>> 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 Feed 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.
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 BaseFeed<?,?>> 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 Feed 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.
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 BaseFeed<?,?>> 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 Feed 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.
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.

insert

public <E extends BaseEntry<?>> E insert(java.net.URL feedUrl,
                                         E entry)
                              throws java.io.IOException,
                                     ServiceException
Inserts a new Entry into a feed associated with the target service. It will return the inserted Entry, including any additional attributes or extensions set by the GData server.

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:
BaseFeed.getEntryPostLink(), BaseFeed.insert(BaseEntry)

batch

public <F extends BaseFeed<?,?>> 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 Feed. 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.getFeed().
See Also:
BaseFeed.getEntryPostLink(), BaseFeed.insert(BaseEntry)

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.

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.

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 BaseEntry<?>> E update(java.net.URL entryUrl,
                                         E entry)
                              throws java.io.IOException,
                                     ServiceException
Updates an existing Entry 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:
BaseEntry.getEditLink(), BaseEntry.update()

update

public <E extends BaseEntry<?>> E update(java.net.URL entryUrl,
                                         E entry,
                                         java.lang.String etag)
                              throws java.io.IOException,
                                     ServiceException
Updates an existing Entry 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:
BaseEntry.getEditLink(), BaseEntry.update()

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.

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.

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.

closeSource

protected void closeSource(ParseSource source)
                    throws java.io.IOException
Closes streams and readers associated with a parse source.

Parameters:
source - Parse source.
Throws:
java.io.IOException

getStreamFromLink

public java.io.InputStream getStreamFromLink(Link link)
                                      throws java.io.IOException,
                                             ServiceException
Throws:
java.io.IOException
ServiceException