| // Copyright 2007 The Android Open Source Project |
| |
| package com.google.wireless.gdata.client; |
| |
| import com.google.wireless.gdata.serializer.GDataSerializer; |
| |
| import java.io.IOException; |
| import java.io.InputStream; |
| |
| /** |
| * Interface for interacting with a GData server. Specific platforms can |
| * provide their own implementations using the available networking and HTTP |
| * stack for that platform. |
| */ |
| public interface GDataClient { |
| |
| /** |
| * Closes this GDataClient, cleaning up any resources, persistent connections, etc., |
| * it may have. |
| */ |
| void close(); |
| |
| /** |
| * URI encodes the supplied uri (using UTF-8). |
| * @param uri The uri that should be encoded. |
| * @return The encoded URI. |
| */ |
| // TODO: get rid of this, if we write our own URI encoding library. |
| String encodeUri(String uri); |
| |
| /** |
| * Creates a new QueryParams that should be used to restrict the feed |
| * contents that are fetched. |
| * @return A new QueryParams. |
| */ |
| // TODO: get rid of this, if we write a generic QueryParams that can encode |
| // querystring params/values. |
| QueryParams createQueryParams(); |
| |
| /** |
| * Connects to a GData server (specified by the feedUrl) and fetches the |
| * specified feed as an InputStream. The caller is responsible for calling |
| * {@link InputStream#close()} on the returned {@link InputStream}. |
| * |
| * @param feedUrl The feed that should be fetched. |
| * @param authToken The authentication token that should be used when |
| * fetching the feed. |
| * @return An InputStream for the feed. |
| * @throws IOException Thrown if an io error occurs while communicating with |
| * the service. |
| * @throws HttpException if the service returns an error response. |
| */ |
| InputStream getFeedAsStream(String feedUrl, |
| String authToken) |
| throws HttpException, IOException; |
| |
| /** |
| * Connects to a GData server (specified by the mediaEntryUrl) and fetches the |
| * specified media entry as an InputStream. The caller is responsible for calling |
| * {@link InputStream#close()} on the returned {@link InputStream}. |
| * |
| * @param mediaEntryUrl The media entry that should be fetched. |
| * @param authToken The authentication token that should be used when |
| * fetching the media entry. |
| * @return An InputStream for the media entry. |
| * @throws IOException Thrown if an io error occurs while communicating with |
| * the service. |
| * @throws HttpException if the service returns an error response. |
| */ |
| InputStream getMediaEntryAsStream(String mediaEntryUrl, String authToken) |
| throws HttpException, IOException; |
| |
| // TODO: support batch update |
| |
| /** |
| * Connects to a GData server (specified by the feedUrl) and creates a new |
| * entry. The response from the server is returned as an |
| * {@link InputStream}. The caller is responsible for calling |
| * {@link InputStream#close()} on the returned {@link InputStream}. |
| * |
| * @param feedUrl The feed url where the entry should be created. |
| * @param authToken The authentication token that should be used when |
| * creating the entry. |
| * @param entry The entry that should be created. |
| * @throws IOException Thrown if an io error occurs while communicating with |
| * the service. |
| * @throws HttpException if the service returns an error response. |
| */ |
| InputStream createEntry(String feedUrl, |
| String authToken, |
| GDataSerializer entry) |
| throws HttpException, IOException; |
| |
| /** |
| * Connects to a GData server (specified by the editUri) and updates an |
| * existing entry. The response from the server is returned as an |
| * {@link InputStream}. The caller is responsible for calling |
| * {@link InputStream#close()} on the returned {@link InputStream}. |
| * |
| * @param editUri The edit uri that should be used for updating the entry. |
| * @param authToken The authentication token that should be used when |
| * updating the entry. |
| * @param entry The entry that should be updated. |
| * @throws IOException Thrown if an io error occurs while communicating with |
| * the service. |
| * @throws HttpException if the service returns an error response. |
| */ |
| InputStream updateEntry(String editUri, |
| String authToken, |
| GDataSerializer entry) |
| throws HttpException, IOException; |
| |
| /** |
| * Connects to a GData server (specified by the editUri) and deletes an |
| * existing entry. |
| * |
| * @param editUri The edit uri that should be used for deleting the entry. |
| * @param authToken The authentication token that should be used when |
| * deleting the entry. |
| * @throws IOException Thrown if an io error occurs while communicating with |
| * the service. |
| * @throws HttpException if the service returns an error response. |
| */ |
| void deleteEntry(String editUri, |
| String authToken) |
| throws HttpException, IOException; |
| |
| /** |
| * Connects to a GData server (specified by the editUri) and updates an |
| * existing media entry. The response from the server is returned as an |
| * {@link InputStream}. The caller is responsible for calling |
| * {@link InputStream#close()} on the returned {@link InputStream}. |
| * |
| * @param editUri The edit uri that should be used for updating the entry. |
| * @param authToken The authentication token that should be used when |
| * updating the entry. |
| * @param mediaEntryInputStream The {@link InputStream} that contains the new |
| * value of the resource |
| * @param contentType The contentType of the new media entry |
| * @throws IOException Thrown if an io error occurs while communicating with |
| * the service. |
| * @throws HttpException if the service returns an error response. |
| * @return The {@link InputStream} that contains the metadata associated with the |
| * new version of the media entry. |
| */ |
| public InputStream updateMediaEntry(String editUri, String authToken, |
| InputStream mediaEntryInputStream, String contentType) |
| throws HttpException, IOException; |
| } |