1 files changed, 149 insertions, 0 deletions
diff --git a/src/com/google/wireless/gdata/client/GDataClient.java b/src/com/google/wireless/gdata/client/GDataClient.java
new file mode 100644
index 0000000..4162fae
--- /dev/null
+++ b/src/com/google/wireless/gdata/client/GDataClient.java
@@ -0,0 +1,149 @@
+// 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;
+}