svn commit: r430207 - /incubator/abdera/java/trunk/client/src/main/java/org/apache/abdera/protocol/client/Client.java

[ro...@apache.org]

Author: rooneg
Date: Wed Aug  9 18:44:30 2006
New Revision: 430207

URL: http://svn.apache.org/viewvc?rev=430207&view=rev
Log:
Add some javadocs to the client code.

* client/src/main/java/org/apache/abdera/protocol/client/Client.java
  (Client,
   getDefaultRequestOptions,
   addCredentials,
   setAuthenticationSchemePriority,
   execute,
   registerScheme): Document, at least a little.

Modified:
    incubator/abdera/java/trunk/client/src/main/java/org/apache/abdera/protocol/client/Client.java

Modified: incubator/abdera/java/trunk/client/src/main/java/org/apache/abdera/protocol/client/Client.java
URL: http://svn.apache.org/viewvc/incubator/abdera/java/trunk/client/src/main/java/org/apache/abdera/protocol/client/Client.java?rev=430207&r1=430206&r2=430207&view=diff
==============================================================================
--- incubator/abdera/java/trunk/client/src/main/java/org/apache/abdera/protocol/client/Client.java (original)
+++ incubator/abdera/java/trunk/client/src/main/java/org/apache/abdera/protocol/client/Client.java Wed Aug  9 18:44:30 2006
@@ -31,12 +31,29 @@
 import org.apache.commons.httpclient.methods.InputStreamRequestEntity;
 import org.apache.commons.httpclient.methods.RequestEntity;
 
+/**
+ * An Atom Publishing Protocol client.
+ */
 public abstract class Client {
 
   protected Cache cache = null;
 
+  /**
+   * Get the default request options used by this client.
+   */
   public abstract RequestOptions getDefaultRequestOptions();
-  
+
+  /**
+   * Add a set of authentication credentials to the client.
+   * 
+   * @param target The URI for which you wish to authenticate
+   * @param realm The authentication realm these credentials apply to,
+   *              or null if the credentials apply to any realm
+   * @param scheme The authentication scheme these credentials apply to,
+   *               or null if the credentials apply to any scheme
+   * @param credentials The credentials to use
+   * @throws URISyntaxException
+   */
   public abstract void addCredentials(
     String target, 
     String realm,
@@ -44,8 +61,13 @@
     Credentials credentials) 
       throws URISyntaxException;
   
+  /** Set the order in which authentication schemes should be used. */
   public abstract void setAuthenticationSchemePriority(String... scheme);
   
+  /**
+   * Indicates if the client should authenticate before attempting to do
+   * anything else.
+   */
   public abstract void usePreemptiveAuthentication(boolean val);
   
   public abstract void init(String userAgent);
@@ -169,13 +191,28 @@
     String uri) {
       return delete(uri, getDefaultRequestOptions());
   }
-  
+
+  /**
+   * Execute an arbitrary HTTP request
+   * 
+   * @param method The method name
+   * @param uri The URI to execute the request on
+   * @param entity The request entity to use for generating the request
+   * @param options The options to use for this request
+   * @return the server's response
+   */
   public abstract Response execute(
     String method, 
     String uri, 
     RequestEntity entity, 
     RequestOptions options);
-  
+
+  /**
+   * Register a new authentication scheme.
+   * 
+   * @param name
+   * @param scheme
+   */
   public static void registerScheme(String name, Class<AuthScheme> scheme) {
     AuthPolicy.registerAuthScheme(name, scheme);
   }