From f92ff0396e9d1b13357c00a63de6fd4b9cae7a20 Mon Sep 17 00:00:00 2001 From: Preben Ingvaldsen Date: Thu, 18 Dec 2014 11:57:21 -0800 Subject: [PATCH] (TK-117) Add javadoc strings Add javadoc strings to each of the user-facing Java classes, and reference those javadoc strings in the documentation on the Java client. --- doc/java-client.md | 189 ++---------------- .../com/puppetlabs/http/client/Async.java | 16 ++ .../http/client/AsyncHttpClient.java | 152 ++++++++++++++ .../puppetlabs/http/client/ClientOptions.java | 25 +++ .../http/client/HttpClientException.java | 6 + .../puppetlabs/http/client/HttpMethod.java | 5 + .../http/client/RequestOptions.java | 28 +++ .../com/puppetlabs/http/client/Response.java | 6 + .../http/client/ResponseBodyType.java | 5 + .../http/client/SimpleRequestOptions.java | 10 + src/java/com/puppetlabs/http/client/Sync.java | 157 +++++++++++++++ .../http/client/SyncHttpClient.java | 158 +++++++++++++++ 12 files changed, 587 insertions(+), 170 deletions(-) diff --git a/doc/java-client.md b/doc/java-client.md index 1c07df8..2e88671 100644 --- a/doc/java-client.md +++ b/doc/java-client.md @@ -6,102 +6,23 @@ in two ways using Java: with and without a persistent client. ## `createClient(ClientOptions clientOptions)` clj-http-client allows you to create a persistent synchronous or asynchronous HTTP client using the static -`createClient()` method in the `Async` and `Sync` classes - -This method takes one argument, `clientOptions`, which is an instance of the `ClientOptions` class. `ClientOptions` -has two constructors: - -```java -public ClientOptions(); -public ClientOptions(SSLContext sslContext, - String sslCert, - String sslKey, - String sslCaCert, - String[] sslProtocols, - String[] sslCipherSuites, - boolean insecure, - boolean forceRedirects, - boolean followRedirects); -``` - -Each parameter in the second constructor is an option corresponding to options in the clojure `create-client` function. -See the page on [making requests with clojure clients](clojure-client.md) for more information. +`createClient()` method in the [`Async`](../src/java/com/puppetlabs/http/client/Async.java) and +[`Sync`](../src/java/com/puppetlabs/http/client/Sync.java) classes +This method takes one argument, `clientOptions`, which is an instance of the +[`ClientOptions`](../src/java/com/puppetlabs/http/client/ClientOptions.java) class, details on which can +be found in its javadoc strings, linked above. ### Making requests with a persistent client -The `createClient()` method returns an object with a number of request methods. For example, the -`createClient()` method in Sync.java would return an object implementing +The `createClient()` method returns an object implementing the [`SyncHttpClient`](../src/java/com/puppetlabs/http/client/SyncHttpClient.java) +interface in the case of `Sync`, and the [`AsyncHttpClient`](../src/java/com/puppetlabs/http/client/AsyncHttpClient.java) interface +in the case of `Async`. Information on the various methods available is detailed in the javadoc strings for the corresponding +interfaces, which are linked above. The various request methods provided by these interfaces can take +a [`RequestOptions`](../src/java/com/puppetlabs/http/client/RequestOptions.java) object, information on +which can be found in that class' javadoc strings, linked above. -```java -public Response request(RequestOptions requestOptions, HttpMethod method); - -public Response get(String url) throws URISyntaxException; -public Response get(URI uri); -public Response get(RequestOptions requestOptions); - -public Response head(String url) throws URISyntaxException; -public Response head(URI uri); -public Response head(RequestOptions requestOptions); - -public Response post(String url) throws URISyntaxException; -public Response post(URI uri); -public Response post(RequestOptions requestOptions); - -public Response put(String url) throws URISyntaxException; -public Response put(URI uri); -public Response put(RequestOptions requestOptions); - -public Response delete(String url) throws URISyntaxException; -public Response delete(URI uri); -public Response delete(RequestOptions requestOptions); - -public Response trace(String url) throws URISyntaxException; -public Response trace(URI uri); -public Response trace(RequestOptions requestOptions); - -public Response options(String url) throws URISyntaxException; -public Response options(URI uri); -public Response options(RequestOptions requestOptions); - -public Response patch(String url) throws URISyntaxException; -public Response patch(URI uri); -public Response patch(RequestOptions requestOptions); - -public void close(); -``` - -Each method will execute the corresponding HTTP request, with the exception of `close`, which -will close the client. - -Each request method has three signatures. The first takes one argument, `String url`, which is the URL -against which you want to make a request. The second takes one argument, `URI uri`, which is the URI against -which you want to make a request. - -The third takes a `RequestOptions` object. `RequestOptions` is an object allowing you to set options for a request. -This object has three constructors: - -```java -public RequestOptions (String url); -public RequestOptions(URI uri); -public RequestOptions (URI uri, - Map headers, - Object body, - boolean decompressBody, - ResponseBodyType as); -``` - -The first constructor takes one argument, `String url`, which is the URL against which you want to make the -request. The second takes one argument, `URI uri`, which is the URI against which you want to make the request. -The third takes five arguments. The first, `URI uri`, is the same as the `uri` argument in the second constructor. -The rest correspond to the similarly named options that can be passed to the clojure request functions. For more -details, see the page on [making requests with the clojure client](clojure-client.md). The `RequestOptions` class -provides getters and setters for all options. - -Note that the `RequestOptions` object has no `query-params` option like in the clojure request functions. All query -parameters should be set in the `uri`. - -So, for example, say you have a Persistent synchronous client, `client, and you want to make a GET request +For example, say you have a Persistent synchronous client, `client`, and you want to make a GET request against the URL `http://localhost:8080/test` with query parameter `abc` with value `def`. To make the request and print the body of the response, you could do the following: @@ -110,14 +31,7 @@ Response response = client.get(new URI("http://localhost:8080/test?abc=def")); System.out.println(response.getBody()); ``` -A synchronous HTTP client also provides the `request` method. This method takes two arguments: -`RequestOptions requestOptions`, and `HttpMethod method`. `HttpMethod` is an enum with the following fields: -`GET, HEAD, POST, PUT, DELETE, TRACE, OPTIONS, PATCH`. - -The object returned by the `createClient()` method in the `Async` class is nearly identical to that returned by the -`createClient()` method in the `Sync` class. However, the various request methods return a `Promise` instead -of a `Response`, and the async client does NOT provide a `request` method. So, in the above example, if client was -instead asynchronous, you would do the following: +If `client` was instead asynchronous, you would do the following: ```java Promise response = client.get(new URI("http://localhost:8080/test?abc=def")); @@ -134,78 +48,13 @@ collected. Once the client is closed, it can no longer be used to make requests. ## Making a Request without a persistent client In addition to allowing you to create a persistent client with the `createClient()` method, the -`Sync` class provides the following simple request methods that can be -called without a client: +[`Sync`](../src/java/com/puppetlabs/http/client/Sync.java) class contains a number of simple request methods +that allow for requests to be made without a persistent client. These are detailed in `Sync.java`'s +javadoc strings, linked above. Many of the provided request methods take a +[`SimpleRequestOptions`](../src/java/com/puppetlabs/http/client/SimpleRequestOptions.java) object. Information +on this class can be found in its javadoc strings, linked above. -```java -public Response get(String url) throws URISyntaxException; -public Response get(URI uri); -public Response get(SimpleRequestOptions simpleRequestOptions); - -public Response head(String url) throws URISyntaxException; -public Response head(URI uri); -public Response head(SimpleRequestOptions simpleRequestOptions); - -public Response post(String url) throws URISyntaxException; -public Response post(URI uri); -public Response post(SimpleRequestOptions simpleRequestOptions); - -public Response put(String url) throws URISyntaxException; -public Response put(URI uri); -public Response put(SimpleRequestOptions simpleRequestOptions); - -public Response delete(String url) throws URISyntaxException; -public Response delete(URI uri); -public Response delete(SimpleRequestOptions simpleRequestOptions); - -public Response trace(String url) throws URISyntaxException; -public Response trace(URI uri); -public Response trace(SimpleRequestOptions simpleRequestOptions); - -public Response options(String url) throws URISyntaxException; -public Response options(URI uri); -public Response options(SimpleRequestOptions simpleRequestOptions); - -public Response patch(String url) throws URISyntaxException; -public Response patch(URI uri); -public Response patch(SimpleRequestOptions simpleRequestOptions); -``` -These methods will, for every request, create a new client, make a new request with that client, and then -close the client once the response is received. These are similar to the request methods provided by a -persistent HTTP client, with one notable exception: they take a `SimpleRequestOptions` object rather than a -`RequestOptions` object. - -`SimpleRequestOptions` provides two constructors: - -```java -public SimpleRequestOptions (String url); -public SimpleRequestOptions(URI uri); -``` - -The `url` and `uri` arguments are the URL and the URI against which you want to make your request. -`SimpleRequestOptions` also has a number of options which can be set using corresponding setter methods. -These options are listed below. - -```java -URI uri; -Map headers; -SSLContext sslContext; -String sslCert; -String sslKey; -String sslCaCert; -String[] sslProtocols; -String[] sslCipherSuites; -boolean insecure; -Object body; -boolean decompressBody; -ResponseBodyType as; -boolean forceRedirects; -boolean followRedirects; -``` - -The options are simply the union of the options available in the `ClientOptions` and `RequestOptions` classes. - -For example, say you wanted to make a request to the URL `http://localhost:8080/test` without a persistent client. +As an example, say you wanted to make a request to the URL `http://localhost:8080/test` without a persistent client. You want the query parameter `abc` with value `def`, and you don't want redirects to be followed. In that case, you would do the following to print the body of the response: diff --git a/src/java/com/puppetlabs/http/client/Async.java b/src/java/com/puppetlabs/http/client/Async.java index 4efbc0a..d283802 100644 --- a/src/java/com/puppetlabs/http/client/Async.java +++ b/src/java/com/puppetlabs/http/client/Async.java @@ -5,7 +5,23 @@ import com.puppetlabs.http.client.impl.JavaClient; import com.puppetlabs.http.client.impl.PersistentAsyncHttpClient; import com.puppetlabs.http.client.impl.CoercedClientOptions; +/** + * This class allows you to create an AsyncHttpClient for use in making + * HTTP Requests. It consists exclusively of a static method to create + * a client. + * + * @author Jeremy Barlow + * @author Preben Ingvaldsen + */ public class Async { + + /** + * Allows you to create an instance of an AsyncHttpClient for use in + * making HTTP requests. + * + * @param clientOptions the list of options with which to configure the client + * @return an AsyncHttpClient that can be used to make requests + */ public static AsyncHttpClient createClient(ClientOptions clientOptions) { clientOptions = SslUtils.configureSsl(clientOptions); CoercedClientOptions coercedClientOptions = JavaClient.coerceClientOptions(clientOptions); diff --git a/src/java/com/puppetlabs/http/client/AsyncHttpClient.java b/src/java/com/puppetlabs/http/client/AsyncHttpClient.java index cc9c89f..5274a61 100644 --- a/src/java/com/puppetlabs/http/client/AsyncHttpClient.java +++ b/src/java/com/puppetlabs/http/client/AsyncHttpClient.java @@ -6,36 +6,188 @@ import java.io.Closeable; import java.net.URI; import java.net.URISyntaxException; +/** + * This interface represents an asynchronous HTTP client with which + * requests can be made. An object implementing this interface is returned by + * {@link com.puppetlabs.http.client.Async#createClient(ClientOptions)}. + * + * @author Preben Ingvaldsen + */ public interface AsyncHttpClient extends Closeable{ + + /** + * Performs a GET request + * @param url the URL against which to make the GET request + * @return a Promise with the contents of the response + * @throws URISyntaxException + */ public Promise get(String url) throws URISyntaxException; + + /** + * Performs a GET request + * @param uri the URI against which to make the GET request + * @return a Promise with the contents of the response + */ public Promise get(URI uri); + + /** + * Performs a GET request + * @param requestOptions options to configure the GET request + * @return a Promise with the contents of the response + */ public Promise get(RequestOptions requestOptions); + /** + * Performs a HEAD request + * @param url the URL against which to make the HEAD request + * @return a Promise with the contents of the response + * @throws URISyntaxException + */ public Promise head(String url) throws URISyntaxException; + + /** + * Performs a HEAD request + * @param uri the URI against which to make the HEAD request + * @return a Promise with the contents of the response + */ public Promise head(URI uri); + + /** + * Performs a HEAD request + * @param requestOptions options to configure the HEAD request + * @return a Promise with the contents of the response + */ public Promise head(RequestOptions requestOptions); + /** + * Performs a POST request + * @param url the URL against which to make the POST request + * @return a Promise with the contents of the response + * @throws URISyntaxException + */ public Promise post(String url) throws URISyntaxException; + + /** + * Performs a POST request + * @param uri the URI against which to make the POST request + * @return a Promise with the contents of the response + */ public Promise post(URI uri); + + /** + * Performs a POST request + * @param requestOptions options to configure the POST request + * @return a Promise with the contents of the response + */ public Promise post(RequestOptions requestOptions); + /** + * Performs a PUT request + * @param url the URL against which to make the PUT request + * @return a Promise with the contents of the response + * @throws URISyntaxException + */ public Promise put(String url) throws URISyntaxException; + + /** + * Performs a PUT request + * @param uri the URI against which to make the PUT request + * @return a Promise with the contents of the response + */ public Promise put(URI uri); + + /** + * Performs a PUT request + * @param requestOptions options to configure the PUT request + * @return a Promise with the contents of the response + */ public Promise put(RequestOptions requestOptions); + /** + * Performs a DELETE request + * @param url the URL against which to make the DELETE request + * @return a Promise with the contents of the response + * @throws URISyntaxException + */ public Promise delete(String url) throws URISyntaxException; + + /** + * Performs a DELETE request + * @param uri the URI against which to make the DELETE request + * @return a Promise with the contents of the response + */ public Promise delete(URI uri); + + /** + * Performs a DELETE request + * @param requestOptions options to configure the DELETE request + * @return a Promise with the contents of the response + */ public Promise delete(RequestOptions requestOptions); + /** + * Performs a TRACE request + * @param url the URL against which to make the TRACE request + * @return a Promise with the contents of the response + * @throws URISyntaxException + */ public Promise trace(String url) throws URISyntaxException; + + /** + * Performs a TRACE request + * @param uri the URI against which to make the TRACE request + * @return a Promise with the contents of the response + */ public Promise trace(URI uri); + + /** + * Performs a TRACE request + * @param requestOptions options to configure the TRACE request + * @return a Promise with the contents of the response + */ public Promise trace(RequestOptions requestOptions); + /** + * Performs an OPTIONS request + * @param url the URL against which to make the OPTIONS request + * @return a Promise with the contents of the response + * @throws URISyntaxException + */ public Promise options(String url) throws URISyntaxException; + + /** + * Performs an OPTIONS request + * @param uri the URI against which to make the OPTIONS request + * @return a Promise with the contents of the response + */ public Promise options(URI uri); + + /** + * Performs an OPTIONS request + * @param requestOptions options to configure the OPTIONS request + * @return a Promise with the contents of the response + */ public Promise options(RequestOptions requestOptions); + /** + * Performs a PATCH request + * @param url the URL against which to make the PATCH request + * @return a Promise with the contents of the response + * @throws URISyntaxException + */ public Promise patch(String url) throws URISyntaxException; + + /** + * Performs a PATCH request + * @param uri the URI against which to make the PATCH request + * @return a Promise with the contents of the response + */ public Promise patch(URI uri); + + /** + * Performs a PATCH request + * @param requestOptions options to configure the PATCH request + * @return a Promise with the contents of the response + */ public Promise patch(RequestOptions requestOptions); } diff --git a/src/java/com/puppetlabs/http/client/ClientOptions.java b/src/java/com/puppetlabs/http/client/ClientOptions.java index b395229..895478e 100644 --- a/src/java/com/puppetlabs/http/client/ClientOptions.java +++ b/src/java/com/puppetlabs/http/client/ClientOptions.java @@ -2,6 +2,15 @@ package com.puppetlabs.http.client; import javax.net.ssl.SSLContext; +/** + * This class is a wrapper around a number of options for use + * in configuring a persistent HTTP Client. + * + * @author Chris Price + * @author Preben Ingvaldsen + * @see com.puppetlabs.http.client.Async#createClient(ClientOptions) + * @see com.puppetlabs.http.client.Sync#createClient(ClientOptions) + */ public class ClientOptions { public static final String[] DEFAULT_SSL_PROTOCOLS = new String[] {"TLSv1", "TLSv1.1", "TLSv1.2"}; @@ -16,7 +25,23 @@ public class ClientOptions { private boolean forceRedirects = false; private boolean followRedirects = true; + /** + * Constructor for the ClientOptions class. + */ public ClientOptions() { } + + /** + * Constructor for the ClientOptions class. + * @param sslContext The SSL context for the client. + * @param sslCert The path to a PEM file containing the client cert + * @param sslKey The path to a PEM file containing the client private key + * @param sslCaCert The path to a PEM file containing the CA cert + * @param sslProtocols The SSL protocols that the client can select from when talking to the server + * @param sslCipherSuites The cipher suites that the client can select from when talking to the server + * @param insecure Whether or not the client should use an insecure connection. + * @param forceRedirects Whether or not the client should follow redirects on POST or PUT requests. Defaults to false. + * @param followRedirects Whether or not the client should follow redirects in general. Defaults to true, and overrides forceRedirects. + */ public ClientOptions(SSLContext sslContext, String sslCert, String sslKey, diff --git a/src/java/com/puppetlabs/http/client/HttpClientException.java b/src/java/com/puppetlabs/http/client/HttpClientException.java index 1339610..6241fa5 100644 --- a/src/java/com/puppetlabs/http/client/HttpClientException.java +++ b/src/java/com/puppetlabs/http/client/HttpClientException.java @@ -1,5 +1,11 @@ package com.puppetlabs.http.client; +/** + * This class represents an exception caused by an error in + * an HTTP request + * + * @author Chris Price + */ public class HttpClientException extends RuntimeException { public HttpClientException(String msg) { super(msg); diff --git a/src/java/com/puppetlabs/http/client/HttpMethod.java b/src/java/com/puppetlabs/http/client/HttpMethod.java index 3732885..f57f6e3 100644 --- a/src/java/com/puppetlabs/http/client/HttpMethod.java +++ b/src/java/com/puppetlabs/http/client/HttpMethod.java @@ -2,6 +2,11 @@ package com.puppetlabs.http.client; import org.apache.http.client.methods.*; +/** + * This enum represents the various HTTP methods that can be used to make requests. + * + * @author Chris Price + */ public enum HttpMethod { GET(HttpGet.class), HEAD(HttpHead.class), diff --git a/src/java/com/puppetlabs/http/client/RequestOptions.java b/src/java/com/puppetlabs/http/client/RequestOptions.java index 0e4ecfd..f949fee 100644 --- a/src/java/com/puppetlabs/http/client/RequestOptions.java +++ b/src/java/com/puppetlabs/http/client/RequestOptions.java @@ -4,6 +4,13 @@ import java.net.URI; import java.net.URISyntaxException; import java.util.Map; +/** + * This class is a wrapper around a number of options for use in + * configuring an HTTP request. + * + * @author Chris Price + * @author Preben Ingvaldsen + */ public class RequestOptions { private URI uri; private Map headers; @@ -11,10 +18,31 @@ public class RequestOptions { private boolean decompressBody = true; private ResponseBodyType as = ResponseBodyType.STREAM; + /** + * Constructor for the RequestOptions class + * @param url the URL against which to make the request + * @throws URISyntaxException + */ public RequestOptions (String url) throws URISyntaxException { this.uri = new URI(url); } + + /** + * Constructor for the RequestOptions class + * @param uri the URI against which to make the request + */ public RequestOptions(URI uri) { this.uri = uri; } + + /** + * Constructor for the RequestOptions class + * @param uri the URI against which to make the request + * @param headers A map of headers. Not required to be set. + * @param body The body of the request. Not required to be set. + * @param decompressBody If true, an "accept-encoding" header with a value of "gzip, deflate" will be + * automatically decompressed if it contains a recognized "content-encoding" header. + * Defaults to true. + * @param as Used to control the data type of the response body. Defaults to ResponseBodyType.STREAM + */ public RequestOptions (URI uri, Map headers, Object body, diff --git a/src/java/com/puppetlabs/http/client/Response.java b/src/java/com/puppetlabs/http/client/Response.java index de76184..6bfe4d4 100644 --- a/src/java/com/puppetlabs/http/client/Response.java +++ b/src/java/com/puppetlabs/http/client/Response.java @@ -5,6 +5,11 @@ import org.apache.http.entity.ContentType; import java.util.Map; +/** + * This class represents a response from an HTTP request. + * + * @author Chris Price + */ public class Response { private RequestOptions options; private String origContentEncoding; @@ -30,6 +35,7 @@ public class Response { this.contentType = contentType; } + public RequestOptions getOptions() { return options; } diff --git a/src/java/com/puppetlabs/http/client/ResponseBodyType.java b/src/java/com/puppetlabs/http/client/ResponseBodyType.java index 63727b2..16efa4f 100644 --- a/src/java/com/puppetlabs/http/client/ResponseBodyType.java +++ b/src/java/com/puppetlabs/http/client/ResponseBodyType.java @@ -1,5 +1,10 @@ package com.puppetlabs.http.client; +/** + * This Enum represents the possible types of the body of a response. + * + * @author Chris Price + */ public enum ResponseBodyType { STREAM, TEXT; diff --git a/src/java/com/puppetlabs/http/client/SimpleRequestOptions.java b/src/java/com/puppetlabs/http/client/SimpleRequestOptions.java index e082a14..421676d 100644 --- a/src/java/com/puppetlabs/http/client/SimpleRequestOptions.java +++ b/src/java/com/puppetlabs/http/client/SimpleRequestOptions.java @@ -5,6 +5,16 @@ import java.net.URI; import java.net.URISyntaxException; import java.util.Map; +/** + * This class represents is a wrapper around a number of options for use in + * making requests with the simple request functions contained in the Sync class. + * It is a combination of the options from ClientOptions and RequestOptions. + * + * @author Chris Price + * @author Preben Ingvaldsen + * @see com.puppetlabs.http.client.ClientOptions#ClientOptions(javax.net.ssl.SSLContext, String, String, String, String[], String[], boolean, boolean, boolean) + * @see com.puppetlabs.http.client.RequestOptions#RequestOptions(java.net.URI, java.util.Map, Object, boolean, ResponseBodyType) + */ public class SimpleRequestOptions { private URI uri; private Map headers; diff --git a/src/java/com/puppetlabs/http/client/Sync.java b/src/java/com/puppetlabs/http/client/Sync.java index cf2d626..ab91e23 100644 --- a/src/java/com/puppetlabs/http/client/Sync.java +++ b/src/java/com/puppetlabs/http/client/Sync.java @@ -13,6 +13,13 @@ import java.net.URI; import java.net.URISyntaxException; import java.util.Map; +/** + * This class allows for the creation of a persistent synchronous HTTP client. It also allows + * for sending synchronous HTTP requests without a persistent HTTP client. + * + * @author Jeremy Barlow + * @author Preben Ingvaldsen + */ public class Sync { private static final Logger LOGGER = LoggerFactory.getLogger(Sync.class); @@ -71,6 +78,11 @@ public class Sync { return response; } + /** + * Creates a synchronous persistent HTTP client + * @param clientOptions + * @return A persistent synchronous HTTP client + */ public static SyncHttpClient createClient(ClientOptions clientOptions) { CoercedClientOptions coercedClientOptions = JavaClient.coerceClientOptions( @@ -79,70 +91,215 @@ public class Sync { JavaClient.createClient(coercedClientOptions)); } + /** + * Makes a simple HTTP GET request + * @param url The URL against which to make the request + * @return The HTTP Response corresponding to the request + * @throws URISyntaxException + */ public static Response get(String url) throws URISyntaxException { return get(new URI(url)); } + + /** + * Makes a simple HTTP GET request + * @param uri The URI against which to make the request + * @return The HTTP Response corresponding to the request + */ public static Response get(URI uri) { return get(new SimpleRequestOptions(uri)); } + + /** + * Makes a simple HTTP GET request + * @param simpleRequestOptions The options to configure the request and the client making it + * @return The HTTP response corresponding to the request + */ public static Response get(SimpleRequestOptions simpleRequestOptions) { return request(simpleRequestOptions, HttpMethod.GET); } + /** + * Makes a simple HTTP HEAD request + * @param url The URL against which to make the request + * @return The HTTP Response corresponding to the request + * @throws URISyntaxException + */ public static Response head(String url) throws URISyntaxException { return head(new URI(url)); } + + /** + * Makes a simple HTTP HEAD request + * @param uri The URI against which to make the request + * @return The HTTP Response corresponding to the request + */ public static Response head(URI uri) { return head(new SimpleRequestOptions(uri)); } + + /** + * Makes a simple HTTP HEAD request + * @param simpleRequestOptions The options to configure the request and the client making it + * @return The HTTP response corresponding to the request + */ public static Response head(SimpleRequestOptions simpleRequestOptions) { return request(simpleRequestOptions, HttpMethod.HEAD); } + + /** + * Makes a simple HTTP POST request + * @param url The URL against which to make the request + * @return The HTTP Response corresponding to the request + * @throws URISyntaxException + */ public static Response post(String url) throws URISyntaxException { return post(new URI(url)); } + + /** + * Makes a simple HTTP POST request + * @param uri The URI against which to make the request + * @return The HTTP Response corresponding to the request + */ public static Response post(URI uri) { return post(new SimpleRequestOptions(uri)); } + + /** + * Makes a simple HTTP POST request + * @param simpleRequestOptions The options to configure the request and the client making it + * @return The HTTP response corresponding to the request + */ public static Response post(SimpleRequestOptions simpleRequestOptions) { return request(simpleRequestOptions, HttpMethod.POST); } + /** + * Makes a simple HTTP PUT request + * @param url The URL against which to make the request + * @return The HTTP Response corresponding to the request + * @throws URISyntaxException + */ public static Response put(String url) throws URISyntaxException { return put(new URI(url)); } + + /** + * Makes a simple HTTP PUT request + * @param uri The URI against which to make the request + * @return The HTTP Response corresponding to the request + */ public static Response put(URI uri) { return put(new SimpleRequestOptions(uri)); } + + /** + * Makes a simple HTTP PUT request + * @param simpleRequestOptions The options to configure the request and the client making it + * @return The HTTP response corresponding to the request + */ public static Response put(SimpleRequestOptions simpleRequestOptions) { return request(simpleRequestOptions, HttpMethod.PUT); } + /** + * Makes a simple HTTP DELETE request + * @param url The URL against which to make the request + * @return The HTTP Response corresponding to the request + * @throws URISyntaxException + */ public static Response delete(String url) throws URISyntaxException { return delete(new URI(url)); } + + /** + * Makes a simple HTTP DELETE request + * @param uri The URI against which to make the request + * @return The HTTP Response corresponding to the request + */ public static Response delete(URI uri) { return delete(new SimpleRequestOptions(uri)); } + + /** + * Makes a simple HTTP DELETE request + * @param simpleRequestOptions The options to configure the request and the client making it + * @return The HTTP response corresponding to the request + */ public static Response delete(SimpleRequestOptions simpleRequestOptions) { return request(simpleRequestOptions, HttpMethod.DELETE); } + /** + * Makes a simple HTTP TRACE request + * @param url The URL against which to make the request + * @return The HTTP Response corresponding to the request + * @throws URISyntaxException + */ public static Response trace(String url) throws URISyntaxException { return trace(new URI(url)); } + + /** + * Makes a simple HTTP TRACE request + * @param uri The URI against which to make the request + * @return The HTTP Response corresponding to the request + */ public static Response trace(URI uri) { return trace(new SimpleRequestOptions(uri)); } + + /** + * Makes a simple HTTP TRACE request + * @param simpleRequestOptions The options to configure the request and the client making it + * @return The HTTP response corresponding to the request + */ public static Response trace(SimpleRequestOptions simpleRequestOptions) { return request(simpleRequestOptions, HttpMethod.TRACE); } + /** + * Makes a simple HTTP OPTIONS request + * @param url The URL against which to make the request + * @return The HTTP Response corresponding to the request + * @throws URISyntaxException + */ public static Response options(String url) throws URISyntaxException { return options(new URI(url)); } + + /** + * Makes a simple HTTP OPTIONS request + * @param uri The URI against which to make the request + * @return The HTTP Response corresponding to the request + */ public static Response options(URI uri) { return options(new SimpleRequestOptions(uri)); } + + /** + * Makes a simple HTTP OPTIONS request + * @param simpleRequestOptions The options to configure the request and the client making it + * @return The HTTP response corresponding to the request + */ public static Response options(SimpleRequestOptions simpleRequestOptions) { return request(simpleRequestOptions, HttpMethod.OPTIONS); } + /** + * Makes a simple HTTP PATCH request + * @param url The URL against which to make the request + * @return The HTTP Response corresponding to the request + * @throws URISyntaxException + */ public static Response patch(String url) throws URISyntaxException { return patch(new URI(url)); } + + /** + * Makes a simple HTTP PATCH request + * @param uri The URI against which to make the request + * @return The HTTP Response corresponding to the request + */ public static Response patch(URI uri) { return patch(new SimpleRequestOptions(uri)); } + + /** + * Makes a simple HTTP PATCH request + * @param simpleRequestOptions The options to configure the request and the client making it + * @return The HTTP response corresponding to the request + */ public static Response patch(SimpleRequestOptions simpleRequestOptions) { return request(simpleRequestOptions, HttpMethod.PATCH); } diff --git a/src/java/com/puppetlabs/http/client/SyncHttpClient.java b/src/java/com/puppetlabs/http/client/SyncHttpClient.java index eedffe4..e1f69c4 100644 --- a/src/java/com/puppetlabs/http/client/SyncHttpClient.java +++ b/src/java/com/puppetlabs/http/client/SyncHttpClient.java @@ -4,38 +4,196 @@ import java.io.Closeable; import java.net.URI; import java.net.URISyntaxException; +/** + * This interface represents a synchronous HTTP client with which + * requests can be made. An object implementing this interface is + * returned by {@link com.puppetlabs.http.client.Sync#createClient(ClientOptions)} + * + * @author Preben Ingvaldsen + */ public interface SyncHttpClient extends Closeable { + + /** + * Makes a configurable HTTP request + * @param requestOptions the options to configure the request + * @param method the type of the HTTP request + * @return the HTTP response + */ public Response request(RequestOptions requestOptions, HttpMethod method); + /** + * Makes an HTTP GET request + * @param url the url against which to make the request + * @return the HTTP response + * @throws URISyntaxException + */ public Response get(String url) throws URISyntaxException; + + /** + * Makes an HTTP GET request + * @param uri the uri against which to make the request + * @return the HTTP response + */ public Response get(URI uri); + + /** + * Makes an HTTP GET request + * @param requestOptions the options to configure the request + * @return the HTTP response + */ public Response get(RequestOptions requestOptions); + /** + * Makes an HTTP HEAD request + * @param url the url against which to make the request + * @return the HTTP response + * @throws URISyntaxException + */ public Response head(String url) throws URISyntaxException; + + /** + * Makes an HTTP HEAD request + * @param uri the uri against which to make the request + * @return the HTTP response + */ public Response head(URI uri); + + /** + * Makes an HTTP HEAD request + * @param requestOptions the options to configure the request + * @return the HTTP response + */ public Response head(RequestOptions requestOptions); + /** + * Makes an HTTP POST request + * @param url the url against which to make the request + * @return the HTTP response + * @throws URISyntaxException + */ public Response post(String url) throws URISyntaxException; + + /** + * Makes an HTTP POST request + * @param uri the uri against which to make the request + * @return the HTTP response + */ public Response post(URI uri); + + /** + * Makes an HTTP POST request + * @param requestOptions the options to configure the request + * @return the HTTP response + */ public Response post(RequestOptions requestOptions); + /** + * Makes an HTTP PUT request + * @param url the url against which to make the request + * @return the HTTP response + * @throws URISyntaxException + */ public Response put(String url) throws URISyntaxException; + + /** + * Makes an HTTP PUT request + * @param uri the uri against which to make the request + * @return the HTTP response + */ public Response put(URI uri); + + /** + * Makes an HTTP PUT request + * @param requestOptions the options to configure the request + * @return the HTTP response + */ public Response put(RequestOptions requestOptions); + /** + * Makes an HTTP DELETE request + * @param url the url against which to make the request + * @return the HTTP response + * @throws URISyntaxException + */ public Response delete(String url) throws URISyntaxException; + + /** + * Makes an HTTP DELETE request + * @param uri the uri against which to make the request + * @return the HTTP response + */ public Response delete(URI uri); + + /** + * Makes an HTTP DELETE request + * @param requestOptions the options to configure the request + * @return the HTTP response + */ public Response delete(RequestOptions requestOptions); + /** + * Makes an HTTP TRACE request + * @param url the url against which to make the request + * @return the HTTP response + * @throws URISyntaxException + */ public Response trace(String url) throws URISyntaxException; + + /** + * Makes an HTTP TRACE request + * @param uri the uri against which to make the request + * @return the HTTP response + */ public Response trace(URI uri); + + /** + * Makes an HTTP TRACE request + * @param requestOptions the options to configure the request + * @return the HTTP response + */ public Response trace(RequestOptions requestOptions); + /** + * Makes an HTTP OPTIONS request + * @param url the url against which to make the request + * @return the HTTP response + * @throws URISyntaxException + */ public Response options(String url) throws URISyntaxException; + + /** + * Makes an HTTP OPTIONS request + * @param uri the uri against which to make the request + * @return the HTTP response + */ public Response options(URI uri); + + /** + * Makes an HTTP OPTIONS request + * @param requestOptions the options to configure the request + * @return the HTTP response + */ public Response options(RequestOptions requestOptions); + /** + * Makes an HTTP PATCH request + * @param url the url against which to make the request + * @return the HTTP response + * @throws URISyntaxException + */ public Response patch(String url) throws URISyntaxException; + + /** + * Makes an HTTP PATCH request + * @param uri the uri against which to make the request + * @return the HTTP response + */ public Response patch(URI uri); + + /** + * Makes an HTTP PATCH request + * @param requestOptions the options to configure the request + * @return the HTTP response + */ public Response patch(RequestOptions requestOptions); }