(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.
This commit is contained in:
parent
494f806f14
commit
f92ff0396e
12 changed files with 587 additions and 170 deletions
|
@ -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:
|
||||
|
||||
|
|
|
@ -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);
|
||||
|
|
|
@ -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);
|
||||
}
|
||||
|
|
|
@ -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,
|
||||
|
|
|
@ -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);
|
||||
|
|
|
@ -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),
|
||||
|
|
|
@ -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,
|
||||
|
|
|
@ -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;
|
||||
}
|
||||
|
|
|
@ -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;
|
||||
|
|
|
@ -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;
|
||||
|
|
|
@ -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);
|
||||
}
|
||||
|
|
|
@ -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);
|
||||
}
|
||||
|
|
Loading…
Reference in a new issue