yogsototh/clj-http-client
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

(TK-117) Add javadoc strings

Browse source 
Add javadoc strings to each of the user-facing Java classes, and
reference those javadoc strings in the documentation on the
Java client.
This commit is contained in:
Preben Ingvaldsen 2014-12-18 11:57:21 -08:00
parent 494f806f14
commit f92ff0396e
12 changed files with 587 additions and 170 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

189
doc/java-client.md
View file

@ -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<String, String> 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<Response>` 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> 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<String, String> 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:

16
src/java/com/puppetlabs/http/client/Async.java
View file

@ -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);

152
src/java/com/puppetlabs/http/client/AsyncHttpClient.java
View file

@ -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<Response> 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<Response> 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<Response> 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<Response> 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<Response> 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<Response> 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<Response> 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<Response> 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<Response> 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<Response> 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<Response> 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<Response> 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<Response> 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<Response> 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<Response> 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<Response> 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<Response> 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<Response> 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<Response> 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<Response> 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<Response> 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<Response> 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<Response> 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<Response> patch(RequestOptions requestOptions);
}

25
src/java/com/puppetlabs/http/client/ClientOptions.java
View file

@ -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,

6
src/java/com/puppetlabs/http/client/HttpClientException.java
View file

@ -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);

5
src/java/com/puppetlabs/http/client/HttpMethod.java
View file

@ -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),

28
src/java/com/puppetlabs/http/client/RequestOptions.java
View file

@ -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<String, String> 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<String, String> headers,
Object body,

6
src/java/com/puppetlabs/http/client/Response.java
View file

@ -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;
}

5
src/java/com/puppetlabs/http/client/ResponseBodyType.java
View file

@ -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;

10
src/java/com/puppetlabs/http/client/SimpleRequestOptions.java
View file

@ -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<String, String> headers;

157
src/java/com/puppetlabs/http/client/Sync.java
View file

@ -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);
}

158
src/java/com/puppetlabs/http/client/SyncHttpClient.java
View file

@ -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);
}