You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@abdera.apache.org by jm...@apache.org on 2006/11/10 20:34:29 UTC
svn commit: r473441 - in
/incubator/abdera/java/trunk/client/src/main/java/org/apache/abdera/protocol/client:
ClientResponse.java CommonsClient.java CommonsResponse.java
RequestOptions.java
Author: jmsnell
Date: Fri Nov 10 11:34:28 2006
New Revision: 473441
URL: http://svn.apache.org/viewvc?view=rev&rev=473441
Log:
Improved Javadocs
Modified:
incubator/abdera/java/trunk/client/src/main/java/org/apache/abdera/protocol/client/ClientResponse.java
incubator/abdera/java/trunk/client/src/main/java/org/apache/abdera/protocol/client/CommonsClient.java
incubator/abdera/java/trunk/client/src/main/java/org/apache/abdera/protocol/client/CommonsResponse.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/ClientResponse.java
URL: http://svn.apache.org/viewvc/incubator/abdera/java/trunk/client/src/main/java/org/apache/abdera/protocol/client/ClientResponse.java?view=diff&rev=473441&r1=473440&r2=473441
==============================================================================
--- incubator/abdera/java/trunk/client/src/main/java/org/apache/abdera/protocol/client/ClientResponse.java (original)
+++ incubator/abdera/java/trunk/client/src/main/java/org/apache/abdera/protocol/client/ClientResponse.java Fri Nov 10 11:34:28 2006
@@ -30,24 +30,54 @@
public interface ClientResponse extends Response {
+ /**
+ * Return the request method
+ */
String getMethod();
+ /**
+ * Return the request URI. The request was redirected, this will return the new URI
+ */
String getUri();
+ /**
+ * Release the resources associated with this response
+ */
void release();
+ /**
+ * Returns the inputstream used to read data from this response
+ */
InputStream getInputStream() throws IOException;
void setInputStream(InputStream in);
-
+
+ /**
+ * If the response contains an XML document, parse the document
+ */
<T extends Element>Document<T> getDocument() throws ParseException;
+ /**
+ * If the response contains an XML document, parse the document using the
+ * specified ParserOptions
+ */
<T extends Element>Document<T> getDocument(ParserOptions options) throws ParseException;
+ /**
+ * If the response contains an XML document, parse the document using the
+ * specified Parser
+ */
<T extends Element>Document<T> getDocument(Parser parser) throws ParseException;
+ /**
+ * If the response contains an XML document, parse the document using the
+ * specified Parser and ParserOptions
+ */
<T extends Element>Document<T> getDocument(Parser parser, ParserOptions options) throws ParseException;
+ /**
+ * Return the server-specified date returned in the response
+ */
Date getServerDate();
}
Modified: incubator/abdera/java/trunk/client/src/main/java/org/apache/abdera/protocol/client/CommonsClient.java
URL: http://svn.apache.org/viewvc/incubator/abdera/java/trunk/client/src/main/java/org/apache/abdera/protocol/client/CommonsClient.java?view=diff&rev=473441&r1=473440&r2=473441
==============================================================================
--- incubator/abdera/java/trunk/client/src/main/java/org/apache/abdera/protocol/client/CommonsClient.java (original)
+++ incubator/abdera/java/trunk/client/src/main/java/org/apache/abdera/protocol/client/CommonsClient.java Fri Nov 10 11:34:28 2006
@@ -38,6 +38,9 @@
import org.apache.commons.httpclient.methods.RequestEntity;
import org.apache.commons.httpclient.params.HttpClientParams;
+/**
+ * The primary Abdera HTTP Client
+ */
public class CommonsClient extends Client {
private static final String DEFAULT_USER_AGENT =
@@ -45,18 +48,30 @@
private final HttpClient client;
+ /**
+ * Initialize the Commons Client using the default Abdera instance and User agent
+ */
public CommonsClient() {
this(DEFAULT_USER_AGENT);
}
+ /**
+ * Initialize the Commons Client using the specified Abdera instance and default user agent
+ */
public CommonsClient(Abdera abdera) {
this(DEFAULT_USER_AGENT, abdera);
}
+ /**
+ * Initialize the Commons Client using the default Abdera instance and specified user agent
+ */
public CommonsClient(String userAgent) {
this(userAgent, new Abdera());
}
+ /**
+ * Initialize the Commons Client using the specified Abdera instance and user agent
+ */
public CommonsClient(String userAgent,Abdera abdera) {
super(abdera);
MultiThreadedHttpConnectionManager connManager =
@@ -71,6 +86,9 @@
CookiePolicy.BROWSER_COMPATIBILITY);
}
+ /**
+ * Configure the client to use preemptive authentication (HTTP Basic Authentication only)
+ */
public void usePreemptiveAuthentication(boolean val) {
client.getParams().setAuthenticationPreemptive(val);
}
Modified: incubator/abdera/java/trunk/client/src/main/java/org/apache/abdera/protocol/client/CommonsResponse.java
URL: http://svn.apache.org/viewvc/incubator/abdera/java/trunk/client/src/main/java/org/apache/abdera/protocol/client/CommonsResponse.java?view=diff&rev=473441&r1=473440&r2=473441
==============================================================================
--- incubator/abdera/java/trunk/client/src/main/java/org/apache/abdera/protocol/client/CommonsResponse.java (original)
+++ incubator/abdera/java/trunk/client/src/main/java/org/apache/abdera/protocol/client/CommonsResponse.java Fri Nov 10 11:34:28 2006
@@ -53,22 +53,37 @@
return method;
}
+ /**
+ * Return the request method
+ */
public String getMethod() {
return method.getName();
}
+ /**
+ * Return the status code of the response
+ */
public int getStatus() {
return method.getStatusCode();
}
+ /**
+ * Return the status text of the response
+ */
public String getStatusText() {
return method.getStatusText();
}
+ /**
+ * Release the resources associated with this response
+ */
public void release() {
method.releaseConnection();
}
+ /**
+ * Return the value of the named HTTP header
+ */
public String getHeader(String header) {
Header h = method.getResponseHeader(header);
if (h != null)
@@ -76,6 +91,9 @@
else return null;
}
+ /**
+ * Return the values of the named HTTP header
+ */
public List<Object> getHeaders(String header) {
Header[] headers = method.getResponseHeaders(header);
List<Object> values = new ArrayList<Object>();
@@ -85,6 +103,9 @@
return java.util.Collections.unmodifiableList(values);
}
+ /**
+ * Return all of the HTTP headers
+ */
public Map<String,List<Object>> getHeaders() {
Header[] headers = method.getResponseHeaders();
Map<String,List<Object>> map = new HashMap<String,List<Object>>();
@@ -99,6 +120,9 @@
return java.util.Collections.unmodifiableMap(map);
}
+ /**
+ * Return a listing of HTTP header names
+ */
public String[] getHeaderNames() {
Header[] headers = method.getResponseHeaders();
List<String> list = new ArrayList<String>();
@@ -110,6 +134,9 @@
return list.toArray(new String[list.size()]);
}
+ /**
+ * Return the request URI
+ */
public String getUri() {
try {
return method.getURI().toString();
@@ -117,6 +144,12 @@
return null; // shouldn't happen
}
+ /**
+ * Return the inputstream for reading the content of the response. The
+ * InputStream returned will automatically decode Content-Encodings and
+ * will automatically release the response when the stream has been
+ * read fully.
+ */
public InputStream getInputStream() throws IOException {
if (in == null) {
String ce = getHeader("Content-Encoding");
@@ -127,6 +160,9 @@
return new AutoReleasingInputStream(method,in);
}
+ /**
+ * Return the named HTTP header as a java.util.Date
+ */
public Date getDateHeader(String header) {
try {
String value = getHeader(header);
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?view=diff&rev=473441&r1=473440&r2=473441
==============================================================================
--- 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 Fri Nov 10 11:34:28 2006
@@ -102,26 +102,44 @@
return !noLocalCache;
}
+ /**
+ * True if the local client cache should be used
+ */
public void setUseLocalCache(boolean use_cache) {
this.noLocalCache = !use_cache;
}
+ /**
+ * Set the value of the HTTP Content-Type header
+ */
public void setContentType(String value) {
setHeader("Content-Type", value);
}
+ /**
+ * Set the value of the HTTP Content-Type header
+ */
public void setContentType(MimeType value) {
setHeader("Content-Type", value.toString());
}
+ /**
+ * Set the value of the HTTP Authorization header
+ */
public void setAuthorization(String auth) {
setHeader("Authorization", auth);
}
+ /**
+ * Set the value of a header using proper encoding of non-ascii characters
+ */
public void setEncodedHeader(String header, String charset, String value) {
setHeader(header, EncodingUtil.encode(value,charset));
}
+ /**
+ * Set the values of a header using proper encoding of non-ascii characters
+ */
public void setEncodedHeader(String header, String charset, String... values) {
if (values != null && values.length > 0) {
for (int n = 0; n < values.length; n++) {
@@ -134,6 +152,9 @@
}
}
+ /**
+ * Set the value of the specified HTTP header
+ */
public void setHeader(String header, String value) {
if (value != null)
setHeader(header, new String[] {value});
@@ -141,6 +162,9 @@
removeHeaders(header);
}
+ /**
+ * Set the value of the specified HTTP header
+ */
public void setHeader(String header, String... values) {
if (values != null && values.length > 0) {
List<String> list = Arrays.asList(new String[] {combine(values)});
@@ -150,16 +174,27 @@
}
}
+ /**
+ * Set the date value of the specified HTTP header
+ */
public void setDateHeader(String header, Date value) {
if (value != null)
setHeader(header, DateUtil.formatDate(value));
removeHeaders(header);
}
+ /**
+ * Similar to setEncodedHeader, but allows for multiple instances of the
+ * specified header
+ */
public void addEncodedHeader(String header, String charset, String value) {
addHeader(header, EncodingUtil.encode(value, charset));
}
+ /**
+ * Similar to setEncodedHeader, but allows for multiple instances of the
+ * specified header
+ */
public void addEncodedHeader(String header, String charset, String... values) {
if (values == null || values.length == 0) return;
for (int n = 0; n < values.length; n++) {
@@ -175,11 +210,17 @@
}
}
+ /**
+ * Similar to setHeader but allows for multiple instances of the specified header
+ */
public void addHeader(String header, String value) {
if (value != null)
addHeader(header, new String[] {value});
}
+ /**
+ * Similar to setHeader but allows for multiple instances of the specified header
+ */
public void addHeader(String header, String... values) {
if (values == null || values.length == 0) return;
List<String> list = getHeaders().get(header);
@@ -192,20 +233,32 @@
}
}
+ /**
+ * Similar to setDateHeader but allows for multiple instances of the specified header
+ */
public void addDateHeader(String header, Date value) {
if (value == null) return;
addHeader(header, DateUtil.formatDate(value));
}
+ /**
+ * Returns the text value of the specified header
+ */
public String getHeader(String header) {
List<String> list = getHeaders().get(header);
return (list != null) ? list.get(0) : null;
}
+ /**
+ * Return a listing of text values for the specified header
+ */
public List<String> getHeaders(String header) {
return getHeaders().get(header);
}
+ /**
+ * Returns the date value of the specified header
+ */
public Date getDateHeader(String header) {
String val = getHeader(header);
try {
@@ -215,91 +268,157 @@
}
}
+ /**
+ * Returns a listing of header names
+ */
public String[] getHeaderNames() {
Set<String> names = getHeaders().keySet();
return names.toArray(new String[names.size()]);
}
+ /**
+ * Sets the value of the HTTP If-Match header
+ */
public void setIfMatch(String entity_tag) {
setHeader("If-Match", entity_tag);
}
+ /**
+ * Sets the value of the HTTP If-Match header
+ */
public void setIfMatch(String... entity_tags) {
setHeader("If-Match", entity_tags);
}
+ /**
+ * Sets the value of the HTTP If-None-Match header
+ */
public void setIfNoneMatch(String entity_tag) {
setHeader("If-None-Match", entity_tag);
}
+ /**
+ * Sets the value of the HTTP If-None-Match header
+ */
public void setIfNoneMatch(String... entity_tags) {
setHeader("If-None-Match", entity_tags);
}
+ /**
+ * Sets the value of the HTTP If-Modified-Since header
+ */
public void setIfModifiedSince(Date date) {
setDateHeader("If-Modified-Since", date);
}
+ /**
+ * Sets the value of the HTTP If-Unmodified-Since header
+ */
public void setIfUnmodifiedSince(Date date) {
setDateHeader("If-Unmodified-Since", date);
}
+ /**
+ * Sets the value of the HTTP Accept header
+ */
public void setAccept(String accept) {
setAccept(new String[] {accept});
}
+ /**
+ * Sets the value of the HTTP Accept header
+ */
public void setAccept(String... accept) {
setHeader("Accept", combine(accept));
}
+ /**
+ * Sets the value of the HTTP Accept-Language header
+ */
public void setAcceptLanguage(String accept) {
setAcceptLanguage(new String[] {accept});
}
+ /**
+ * Sets the value of the HTTP Accept-Language header
+ */
public void setAcceptLanguage(String... accept) {
setHeader("Accept-Language", combine(accept));
}
+ /**
+ * Sets the value of the HTTP Accept-Charset header
+ */
public void setAcceptCharset(String accept) {
setAcceptCharset(new String[] {accept});
}
+ /**
+ * Sets the value of the HTTP Accept-Charset header
+ */
public void setAcceptCharset(String... accept) {
setHeader("Accept-Charset", combine(accept));
}
+ /**
+ * Sets the value of the HTTP Accept-Encoding header
+ */
public void setAcceptEncoding(String accept) {
setAcceptEncoding(new String[] {accept});
}
+ /**
+ * Sets the value of the HTTP Accept-Encoding header
+ */
public void setAcceptEncoding(String... accept) {
setHeader("Accept-Encoding", combine(accept));
}
+ /**
+ * Sets the value of the Atom Publishing Protocol Slug header
+ */
public void setSlug(String slug) {
setHeader("Slug", slug);
}
+ /**
+ * Sets the value of the Atom Publishing Protocol Slug header
+ */
public void setSlug(String slug, String charset) {
setEncodedHeader("Slug", charset, slug);
}
+ /**
+ * Sets the value of the HTTP Cache-Control header
+ */
public void setCacheControl(String cc) {
CacheControlUtil.parseCacheControl(cc, this);
}
+ /**
+ * Remove the specified HTTP header
+ */
public void removeHeaders(String name) {
getHeaders().remove(name);
}
-
+
+ /**
+ * Return the value of the Cache-Control header
+ */
public String getCacheControl() {
return CacheControlUtil.buildCacheControl(this);
}
+ /**
+ * Configure the Client Side cache to revalidate when using Authorization
+ */
public boolean getRevalidateWithAuth() {
return revalidateAuth;
}
+ /**
+ * Configure the Client Side cache to revalidate when using Authorization
+ */
public void setRevalidateWithAuth(boolean revalidateAuth) {
this.revalidateAuth= revalidateAuth;
}