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 to receive response data from the service as an InputStream.
static interface Service.GDataRequestFactory
          The GDataRequestFactory interface defines a basic factory interface for constructing a new GDataRequest interface.
 
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
 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(java.net.URL queryUrl)
          Executes a GData query 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(Service.GDataRequest.RequestType type, java.net.URL requestUrl, ContentType contentType)
          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.URL entryUrl)
          Deletes an existing entry using the specified entry edit URL.
 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.
 ExtensionProfile getExtensionProfile()
          Returns the ExtensionProfile that defines any expected extensions to the base RSS/Atom content model.
<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.
 Service.GDataRequestFactory getRequestFactory()
          Returns the GDataRequestFactory currently associated with the service.
 java.lang.String getServiceVersion()
          Returns information about the service version.
<E extends BaseEntry>
E
insert(java.net.URL feedUrl, E entry)
          Inserts a new Entry into a feed associated with the target service.
<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.
 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 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.
<E extends BaseEntry>
E
update(java.net.URL entryUrl, E entry)
          Updates an existing Entry by writing it to the specified entry edit URL.
 
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

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.


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.


createRequest

protected Service.GDataRequest createRequest(Service.GDataRequest.RequestType type,
                                             java.net.URL requestUrl,
                                             ContentType contentType)
                                      throws java.io.IOException,
                                             ServiceException
Creates a new GDataRequest for use by the service.

Throws:
java.io.IOException
ServiceException

getContentType

public ContentType getContentType()
Returns the default ContentType for data associated with this GData service. If not explicitly set by a client, the default model is Atom content using the UTF-8 character set.


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)

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

createFeedRequest

public Service.GDataRequest createFeedRequest(java.net.URL queryUrl)
                                       throws java.io.IOException,
                                              ServiceException
Executes a GData query against the target service and returns the resulting feed results via an input stream.

Parameters:
queryUrl - URL that defines target feed and any query parameters.
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,
                                        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)
                             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.

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

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.
ServiceException - insert request failed due to system error.
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.

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

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 entryUrl)
            throws java.io.IOException,
                   ServiceException
Deletes an existing entry using the specified entry edit URL.

Parameters:
entryUrl - the URL used to edit the entry.
Throws:
java.io.IOException - error communicating with the GData service.
ResourceNotFoundException - invalid entry URL.
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.