abdera-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jmsn...@apache.org
Subject svn commit: r632971 - in /incubator/abdera/java/trunk/client/src/main/java/org/apache/abdera/protocol/client: AbderaClient.java AbstractClientResponse.java RequestOptions.java
Date Mon, 03 Mar 2008 07:46:30 GMT
Author: jmsnell
Date: Sun Mar  2 23:46:30 2008
New Revision: 632971

URL: http://svn.apache.org/viewvc?rev=632971&view=rev
Log:
javadocs and minor api updates

Modified:
    incubator/abdera/java/trunk/client/src/main/java/org/apache/abdera/protocol/client/AbderaClient.java
    incubator/abdera/java/trunk/client/src/main/java/org/apache/abdera/protocol/client/AbstractClientResponse.java
    incubator/abdera/java/trunk/client/src/main/java/org/apache/abdera/protocol/client/RequestOptions.java

Modified: incubator/abdera/java/trunk/client/src/main/java/org/apache/abdera/protocol/client/AbderaClient.java
URL: http://svn.apache.org/viewvc/incubator/abdera/java/trunk/client/src/main/java/org/apache/abdera/protocol/client/AbderaClient.java?rev=632971&r1=632970&r2=632971&view=diff
==============================================================================
--- incubator/abdera/java/trunk/client/src/main/java/org/apache/abdera/protocol/client/AbderaClient.java
(original)
+++ incubator/abdera/java/trunk/client/src/main/java/org/apache/abdera/protocol/client/AbderaClient.java
Sun Mar  2 23:46:30 2008
@@ -87,10 +87,19 @@
     this(new Abdera(),DEFAULT_USER_AGENT);
   }
   
+  /**
+   * Create an AbderaClient instance using the specified useragent name
+   * @param useragent
+   */
   public AbderaClient(String useragent) {
     this(new Abdera(), useragent);
   }
   
+  /**
+   * Create an AbderaClient instance using the specified Abdera instance and useragent name
+   * @param abdera
+   * @param useragent
+   */
   public AbderaClient(Abdera abdera, String useragent) {
     this.abdera = abdera;
     this.cache = initCache(initCacheFactory());
@@ -108,10 +117,14 @@
     setMaximumRedirects(DEFAULT_MAX_REDIRECTS);
   }
   
+  /**
+   * Create an AbderaClient instance using the specified Abdera instance
+   * @param abdera
+   */
   public AbderaClient(Abdera abdera) {
     this(abdera,DEFAULT_USER_AGENT);
   }
-    
+
   private CacheFactory initCacheFactory() {
     CacheFactory cacheFactory = 
       (CacheFactory)ServiceUtil.newInstance(
@@ -120,29 +133,51 @@
         abdera);
     return cacheFactory;
   }
-  
+
+  /**
+   * Returns the client HTTP cache instance
+   */
   public Cache getCache() {
     return cache;
   }
   
+  /**
+   * Initializes the client HTTP cache
+   */
   public Cache initCache(CacheFactory factory) {
     Cache cache = null;
     if (factory != null) cache = factory.getCache(abdera);
     return (cache != null) ? cache : new LRUCache(abdera);
   }
   
+  /**
+   * Sends an HTTP HEAD request to the specified URI.
+   * @param uri The request URI
+   * @param options The request options
+   */
   public ClientResponse head(
     String uri, 
     RequestOptions options) {
       return execute("HEAD", uri, (RequestEntity)null, options);
   }
-  
+
+  /**
+   * Sends an HTTP GET request to the specified URI.
+   * @param uri The request URI
+   * @param options The request options
+   */
   public ClientResponse get(
     String uri, 
     RequestOptions options) {
       return execute("GET", uri, (RequestEntity)null, options);
   }
   
+  /**
+   * Sends an HTTP POST request to the specified URI.
+   * @param uri The request URI
+   * @param provider An EntityProvider implementation providing the payload of the request
+   * @param options The request options
+   */
   public ClientResponse post(
     String uri, 
     EntityProvider provider, 
@@ -156,7 +191,13 @@
         ), 
         options);
   }
-  
+
+  /**
+   * Sends an HTTP POST request to the specified URI.
+   * @param uri The request URI
+   * @param entity A RequestEntity object providing the payload of the request
+   * @param options The request options
+   */
   public ClientResponse post(
     String uri, 
     RequestEntity entity, 
@@ -164,6 +205,12 @@
       return execute("POST", uri, entity, options);
   }
 
+  /**
+   * Sends an HTTP POST request to the specified URI.
+   * @param uri The request URI
+   * @param in An InputStream providing the payload of the request
+   * @param options The request options
+   */
   public ClientResponse post(
     String uri, 
     InputStream in, 
@@ -171,6 +218,12 @@
       return execute("POST", uri, new InputStreamRequestEntity(in), options);
   }
 
+  /**
+   * Sends an HTTP POST request to the specified URI.
+   * @param uri The request URI
+   * @param base An Abdera FOM Document or Element object providing the payload of the request
+   * @param options The request options
+   */
   public ClientResponse post(
     String uri, 
     Base base, 
@@ -184,6 +237,12 @@
       return execute("POST", uri, new BaseRequestEntity(base, options.isUseChunked()), options);
   }
 
+  /**
+   * Sends an HTTP PUT request to the specified URI.
+   * @param uri The request URI
+   * @param provider An EntityProvider implementation providing the payload of the request
+   * @param options The request options
+   */
   public ClientResponse put(
     String uri, 
     EntityProvider provider, 
@@ -207,6 +266,12 @@
         options);
   }
   
+  /**
+   * Sends an HTTP PUT request to the specified URI.
+   * @param uri The request URI
+   * @param entity A RequestEntity object providing the payload of the request
+   * @param options The request options
+   */
   public ClientResponse put(
     String uri, 
     RequestEntity entity, 
@@ -214,6 +279,12 @@
       return execute("PUT", uri, entity, options);
   }
 
+  /**
+   * Sends an HTTP PUT request to the specified URI.
+   * @param uri The request URI
+   * @param in An InputStream providing the payload of the request 
+   * @param options The request options
+   */
   public ClientResponse put(
     String uri, 
     InputStream in, 
@@ -221,6 +292,12 @@
       return execute("PUT", uri, new InputStreamRequestEntity(in), options);
   }
 
+  /**
+   * Sends an HTTP PUT request to the specified URI.
+   * @param uri The request URI
+   * @param base A FOM Document or Element providing the payload of the request
+   * @param options The request options
+   */
   public ClientResponse put(
       String uri, 
       Base base, 
@@ -242,56 +319,125 @@
     return execute("PUT", uri, new BaseRequestEntity(base, options.isUseChunked()), options);
   }
       
+  /**
+   * Sends an HTTP DELETE request to the specified URI.
+   * @param uri The request URI
+   * @param options The request options
+   */
   public ClientResponse delete(
     String uri, 
     RequestOptions options) {
       return execute("DELETE", uri, (RequestEntity)null, options);
   }
   
+  /**
+   * Sends an HTTP HEAD request to the specified URI using the default options
+   * @param uri The request URI
+   */
   public ClientResponse head(String uri) {
     return head(uri, getDefaultRequestOptions());
   }
   
+  /**
+   * Sends an HTTP GET request to the specified URI using the default options
+   * @param uri The request URI
+   */
   public ClientResponse get(String uri) {
     return get(uri, getDefaultRequestOptions());
   }
     
+  /**
+   * Sends an HTTP POST request to the specified URI using the default options
+   * @param uri The request URI
+   * @param provider An EntityProvider implementation providing the payload the request
+   */
+  public ClientResponse post(
+    String uri,
+    EntityProvider provider) {
+      return post(uri,provider,getDefaultRequestOptions());
+  }
+  
+  /**
+   * Sends an HTTP POST request to the specified URI using the default options
+   * @param uri The request URI
+   * @param entity A RequestEntity object providing the payload of the request
+   */
   public ClientResponse post(
     String uri, 
     RequestEntity entity) {
     return post(uri, entity, getDefaultRequestOptions());
   }
-  
+
+  /**
+   * Sends an HTTP POST request to the specified URI using the default options
+   * @param uri The request URI
+   * @param in An InputStream providing the payload of the request
+   */
   public ClientResponse post(
     String uri, 
     InputStream in) {
       return post(uri, in, getDefaultRequestOptions());
   }
   
+  /**
+   * Sends an HTTP POST request to the specified URI using the default options
+   * @param uri The request URI
+   * @param base A FOM Document or Element providing the payload of the request
+   */
   public ClientResponse post(
     String uri, 
     Base base) {
       return post(uri, base, getDefaultRequestOptions());
   }
 
+  /**
+   * Sends an HTTP PUT request to the specified URI using the default options
+   * @param uri The request URI
+   * @param provider An EntityProvider implementation providing the payload of the request
+   */
+  public ClientResponse put(
+    String uri,
+    EntityProvider provider) {
+      return put(uri,provider,getDefaultRequestOptions());
+  }
+  
+  /**
+   * Sends an HTTP PUT request to the specified URI using the default options
+   * @param uri The request URI
+   * @param entity A RequestEntity object providing the payload of the request
+   */
   public ClientResponse put(
     String uri, 
     RequestEntity entity) {
       return put(uri, entity, getDefaultRequestOptions());
   }
   
+  /**
+   * Sends an HTTP PUT request to the specified URI using the default options
+   * @param uri The request URI
+   * @param in An InputStream providing the payload of the request 
+   */
   public ClientResponse put(
     String uri, 
     InputStream in) {
       return put(uri, in, getDefaultRequestOptions());
   }
   
+  /**
+   * Sends an HTTP PUT request to the specified URI using the default options
+   * @param uri The request URI
+   * @param base A FOM Document or Element providing the payload of the request
+   */
   public ClientResponse put(
     String uri, 
     Base base) {
       return put(uri, base, getDefaultRequestOptions());
   }
 
+  /**
+   * Sends an HTTP DELETE request to the specified URI using the default options
+   * @param uri The request URI
+   */
   public ClientResponse delete(
     String uri) {
       return delete(uri, getDefaultRequestOptions());
@@ -311,6 +457,7 @@
   
   /**
    * Unregister a specific authentication scheme
+   * @param name The name of the authentication scheme (e.g. "basic", "digest", etc)
    */
   public static void unregisterScheme(
     String name) {
@@ -318,21 +465,33 @@
   }
   
   /**
-   * Unregister multiple schemes
+   * Unregister multiple HTTP authentication schemes
    */
   public static void unregisterScheme(String... names) {
     for (String name : names) unregisterScheme(name);
   }
   
+  /**
+   * Register the specified TrustManager for SSL support on the default port (443)
+   * @param trustManager The TrustManager implementation
+   */
   public static void registerTrustManager(
     TrustManager trustManager) {
       registerTrustManager(trustManager,443);
   }
   
+  /**
+   * Register the default TrustManager for SSL support on the default port (443)
+   */
   public static void registerTrustManager() {
     registerTrustManager(443);
   }
   
+  /**
+   * Register the specified TrustManager for SSL support on the specified port
+   * @param trustManager The TrustManager implementation
+   * @param port The port 
+   */
   public static void registerTrustManager(
     TrustManager trustManager, 
     int port) {
@@ -341,12 +500,19 @@
       registerFactory(f,port);
   }
   
+  /**
+   * Register the default trust manager on the specified port
+   * @param port The port
+   */
   public static void registerTrustManager(int port) {
     SimpleSSLProtocolSocketFactory f = 
       new SimpleSSLProtocolSocketFactory();
     registerFactory(f,port);
   }
   
+  /**
+   * Register the specified secure socket factory on the specified port
+   */
   public static void registerFactory(
     SecureProtocolSocketFactory factory, 
     int port) {
@@ -386,6 +552,14 @@
     return false;
   }
   
+  /**
+   * Sends the specified method request to the specified URI. This can be used
+   * to send extension HTTP methods to a server (e.g. PATCH, LOCK, etc)
+   * @param method The HTTP method
+   * @param uri The request URI
+   * @param base A FOM Document and Element providing the payload for the request
+   * @param options The Request Options
+   */
   public ClientResponse execute(
     String method,
     String uri,
@@ -397,7 +571,42 @@
         new BaseRequestEntity(base),
         options);
   }
+
+  /**
+   * Sends the specified method request to the specified URI. This can be used
+   * to send extension HTTP methods to a server (e.g. PATCH, LOCK, etc)
+   * @param method The HTTP method
+   * @param uri The request URI
+   * @param provider An EntityProvider implementation providing the payload of the request
+   * @param options The Request Options
+   */
+  public ClientResponse execute(
+    String method,
+    String uri,
+    EntityProvider provider,
+    RequestOptions options) {
+      if (options == null) 
+        options = getDefaultRequestOptions();
+      return execute(
+        method,
+        uri,
+        new EntityProviderRequestEntity(
+          abdera,
+          provider,
+          options.isUseChunked()
+        ),
+        options
+      );
+  }
     
+  /**
+   * Sends the specified method request to the specified URI. This can be used
+   * to send extension HTTP methods to a server (e.g. PATCH, LOCK, etc)
+   * @param method The HTTP method
+   * @param uri The request URI
+   * @param in An InputStream providing the payload of the request
+   * @param options The Request Options
+   */
   public ClientResponse execute(
     String method,
     String uri,
@@ -433,6 +642,14 @@
     return disp;
   }
   
+  /**
+   * Sends the specified method request to the specified URI. This can be used
+   * to send extension HTTP methods to a server (e.g. PATCH, LOCK, etc)
+   * @param method The HTTP method
+   * @param uri The request URI
+   * @param entity A RequestEntity object providing the payload for the request
+   * @param options The Request Options
+   */
   public ClientResponse execute(
     String method, 
     String uri, 
@@ -517,10 +734,16 @@
       return response;
   }
   
+  /**
+   * Get a copy of the default request options
+   */
   public RequestOptions getDefaultRequestOptions() {
     return MethodHelper.createDefaultRequestOptions();
   }
   
+  /**
+   * Add authentication credentials
+   */
   public AbderaClient addCredentials(
     String target,
     String realm,
@@ -545,12 +768,21 @@
     return this;
   }
 
+  /**
+   * Configure the client to use the default authentication scheme settings
+   */
   public AbderaClient setAuthenticationSchemeDefaults() {
     List authPrefs = AuthPolicy.getDefaultAuthPrefs();
     client.getParams().setParameter(AuthPolicy.AUTH_SCHEME_PRIORITY, authPrefs);
     return this;
   }
   
+  /**
+   * When multiple authentication schemes are supported by a server, the client
+   * will automatically select a scheme based on the configured priority.  For 
+   * instance, to tell the client to prefer "digest" over "basic", set the 
+   * priority by calling setAuthenticationSchemePriority("digest","basic")
+   */
   public AbderaClient setAuthenticationSchemePriority(String... scheme) {
     List authPrefs = java.util.Arrays.asList(scheme);
     client.getParams().setParameter(
@@ -559,8 +791,14 @@
     return this;
   }
   
-  public List getAuthenticationSchemePriority() {
-    return (List)client.getParams().getParameter(AuthPolicy.AUTH_SCHEME_PRIORITY);
+  /**
+   * Returns the current listing of preferred authentication schemes, in order
+   * of preference
+   * @see setAuthenticationSchemePriority 
+   */
+  public String[] getAuthenticationSchemePriority() {
+    List list = (List)client.getParams().getParameter(AuthPolicy.AUTH_SCHEME_PRIORITY);
+    return (String[])list.toArray(new String[list.size()]);
   }
   
   /**
@@ -595,7 +833,6 @@
   /**
    * Return the maximum number of connections allowed for a single host
    */
-  
   @SuppressWarnings("unchecked")
   public int getMaxConnectionsPerHost() {
     Map<HostConfiguration,Integer> m = (Map<HostConfiguration,Integer>) 

Modified: incubator/abdera/java/trunk/client/src/main/java/org/apache/abdera/protocol/client/AbstractClientResponse.java
URL: http://svn.apache.org/viewvc/incubator/abdera/java/trunk/client/src/main/java/org/apache/abdera/protocol/client/AbstractClientResponse.java?rev=632971&r1=632970&r2=632971&view=diff
==============================================================================
--- incubator/abdera/java/trunk/client/src/main/java/org/apache/abdera/protocol/client/AbstractClientResponse.java
(original)
+++ incubator/abdera/java/trunk/client/src/main/java/org/apache/abdera/protocol/client/AbstractClientResponse.java
Sun Mar  2 23:46:30 2008
@@ -38,6 +38,9 @@
 import org.apache.commons.httpclient.util.DateParseException;
 import org.apache.commons.httpclient.util.DateUtil;
 
+/**
+ * Abstract base class for a ClientResponse
+ */
 public abstract class AbstractClientResponse
   extends AbstractResponse
   implements ClientResponse {
@@ -63,23 +66,42 @@
     return parser;
   }
   
+  /**
+   * Get the response payload as a parsed Abdera FOM Document
+   */
   public <T extends Element>Document<T> getDocument() 
     throws ParseException {
       return getDocument(getParser());
   }
   
+  /**
+   * Get the response payload as a parsed Abdera FOM Document using
+   * the specified parser options
+   * @param options The parser options
+   */
   public <T extends Element>Document<T> getDocument(
     ParserOptions options) 
       throws ParseException {
     return getDocument(getParser(), options);
   }
 
+  /**
+   * Get the response payload as a parsed Abdera FOM Document
+   * using the specified parser
+   * @param parser The parser
+   */
   public <T extends Element>Document<T> getDocument(
     Parser parser) 
       throws ParseException {
     return getDocument(parser, parser.getDefaultParserOptions());
   }
   
+  /**
+   * Get the response payload as a parsed Abdera FOM Document using
+   * the specified parser and parser options
+   * @param parser The parser
+   * @param options The parser options
+   */
   public <T extends Element>Document<T> getDocument(
     Parser parser, 
     ParserOptions options) 
@@ -110,25 +132,41 @@
       throw new ParseException(e);
     }
   }
-  
+
+  /**
+   * Get the response payload as an input stream
+   */
   public InputStream getInputStream() throws IOException {
     return in;
   }
 
+  /**
+   * Set the response input stream (used internally by Abdera)
+   */
   public void setInputStream(InputStream in) {
     this.in = in;
   }
-  
+
+  /**
+   * Get the response payload as a reader (assumed UTF-8 charset)
+   */
   public Reader getReader() throws IOException {
     String charset = getCharacterEncoding();
     return getReader(charset != null ? charset : "UTF-8");
   }
   
+  /**
+   * Get the response payload as a reader using the specified charset
+   * @param charset The character set encoding
+   */
   public Reader getReader(String charset) throws IOException {
     if (charset == null) charset = "UTF-8";
     return new InputStreamReader(getInputStream(),charset);
   }
 
+  /**
+   * Return the date returned by the server in the response
+   */
   public Date getServerDate() {
     if (response_date == null) 
       response_date = initResponseDate();
@@ -141,6 +179,9 @@
       CacheControlUtil.parseCacheControl(cc, this);
   }
   
+  /**
+   * Get the character set encoding specified by the server in the Content-Type header
+   */
   public String getCharacterEncoding() {
     String charset = null;
     try {

Modified: incubator/abdera/java/trunk/client/src/main/java/org/apache/abdera/protocol/client/RequestOptions.java
URL: http://svn.apache.org/viewvc/incubator/abdera/java/trunk/client/src/main/java/org/apache/abdera/protocol/client/RequestOptions.java?rev=632971&r1=632970&r2=632971&view=diff
==============================================================================
--- incubator/abdera/java/trunk/client/src/main/java/org/apache/abdera/protocol/client/RequestOptions.java
(original)
+++ incubator/abdera/java/trunk/client/src/main/java/org/apache/abdera/protocol/client/RequestOptions.java
Sun Mar  2 23:46:30 2008
@@ -39,6 +39,10 @@
 import org.apache.commons.httpclient.util.DateParseException;
 import org.apache.commons.httpclient.util.DateUtil;
 
+/**
+ * The RequestOptions class allows a variety of options affecting the execution
+ * of the request to be modified. 
+ */
 public class RequestOptions
   extends AbstractRequest 
   implements Request {
@@ -57,33 +61,59 @@
   
   public RequestOptions() {}
 
+  /**
+   * Create the RequestOptions object with the specified If-Modified-Since header value
+   * @param ifModifiedSince
+   */
   public RequestOptions(Date ifModifiedSince) {
     this();
     setIfModifiedSince(ifModifiedSince);
   }
-  
+
+  /**
+   * Create the RequestOptions object with the specified If-None-Match header value
+   * @param IfNoneMatch
+   */
   public RequestOptions(String ifNoneMatch) {
     this();
     setIfNoneMatch(ifNoneMatch);
   }
   
+  /**
+   * Create the RequestOptions object with the specified If-None-Match header value
+   * @param IfNoneMatch
+   */
   public RequestOptions(String... ifNoneMatch) {
     this();
     setIfNoneMatch(ifNoneMatch);
   }
   
+  /**
+   * Create the RequestOptions object with the specified If-Modified-Since and If-None-Match
header values
+   * @param ifModifiedSince
+   * @param IfNoneMatch
+   */
   public RequestOptions(Date ifModifiedSince, String ifNoneMatch) {
     this();
     setIfModifiedSince(ifModifiedSince);
     setIfNoneMatch(ifNoneMatch);
   }
   
+  /**
+   * Create the RequestOptions object with the specified If-Modified-Since and If-None-Match
header values
+   * @param ifModifiedSince
+   * @param IfNoneMatch
+   */
   public RequestOptions(Date ifModifiedSince, String... ifNoneMatch) {
     this();
     setIfModifiedSince(ifModifiedSince);
     setIfNoneMatch(ifNoneMatch);
   }
   
+  /**
+   * Create the RequestOptions object
+   * @param no_cache True if the request will indicate that cached responses should not be
returned
+   */
   public RequestOptions(boolean no_cache) {
     this();
     setNoCache(no_cache);



Mime
View raw message