Skip to content

chore: Update the Client file documentation #111

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Feb 19, 2020
Merged

chore: Update the Client file documentation #111

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
12d28b7
Updating the Client documentation
vinifarias Oct 27, 2018
f97a53c
Merge branch 'master' into master
thinkingserious Feb 19, 2020
6e1befc
Update Client.java
thinkingserious Feb 19, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
96 changes: 93 additions & 3 deletions src/main/java/com/sendgrid/Client.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,10 @@
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;

// Hack to get DELETE to accept a request body

/**
* Hack to get DELETE to accept a request body.
*/
class HttpDeleteWithBody extends HttpEntityEnclosingRequestBase {
public static final String METHOD_NAME = "DELETE";

Expand All @@ -41,6 +44,7 @@ public HttpDeleteWithBody(final String uri) {
}
}


/**
* Class Client allows for quick and easy access any REST or REST-like API.
*/
Expand All @@ -50,6 +54,7 @@ public class Client implements Closeable {
private Boolean test;
private boolean createdHttpClient;


/**
* Constructor for using the default CloseableHttpClient.
*/
Expand All @@ -59,6 +64,7 @@ public Client() {
this.createdHttpClient = true;
}


/**
* Constructor for passing in an httpClient, typically for mocking. Passed-in httpClient will not be closed
* by this Client.
Expand All @@ -70,8 +76,9 @@ public Client(CloseableHttpClient httpClient) {
this(httpClient, false);
}


/**
* Constructor for passing in a test parameter to allow for http calls
* Constructor for passing in a test parameter to allow for http calls.
*
* @param test
* is a Bool
Expand All @@ -80,8 +87,9 @@ public Client(Boolean test) {
this(HttpClients.createDefault(), test);
}


/**
* Constructor for passing in a an httpClient and test parameter to allow for http calls
* Constructor for passing in an httpClient and test parameter to allow for http calls.
*
* @param httpClient
* an Apache CloseableHttpClient
Expand All @@ -104,6 +112,8 @@ public Client(CloseableHttpClient httpClient, Boolean test) {
* (e.g. "/your/endpoint/path")
* @param queryParams
* map of key, values representing the query parameters
* @throws URISyntaxException
* in of a URI syntax error
*/
public URI buildUri(String baseUri, String endpoint, Map<String, String> queryParams) throws URISyntaxException {
URIBuilder builder = new URIBuilder();
Expand Down Expand Up @@ -133,11 +143,15 @@ public URI buildUri(String baseUri, String endpoint, Map<String, String> queryPa
return uri;
}


/**
* Prepare a Response object from an API call via Apache's HTTP client.
*
* @param response
* from a call to a CloseableHttpClient
* @throws IOException
* in case of a network error
* @return the response object
*/
public Response getResponse(CloseableHttpResponse response) throws IOException {
ResponseHandler<String> handler = new SendGridResponseHandler();
Expand All @@ -154,9 +168,18 @@ public Response getResponse(CloseableHttpResponse response) throws IOException {
return new Response(statusCode, responseBody, responseHeaders);
}


/**
* Make a GET request and provide the status code, response body and
* response headers.
*
* @param request
* the request object
* @throws URISyntaxException
* in case of a URI syntax error
* @throws IOException
* in case of a network error
* @return the response object
*/
public Response get(Request request) throws URISyntaxException, IOException {
URI uri = null;
Expand All @@ -177,9 +200,18 @@ public Response get(Request request) throws URISyntaxException, IOException {
return executeApiCall(httpGet);
}


/**
* Make a POST request and provide the status code, response body and
* response headers.
*
* @param request
* the request object
* @throws URISyntaxException
* in case of a URI syntax error
* @throws IOException
* in case of a network error
* @return the response object
*/
public Response post(Request request) throws URISyntaxException, IOException {
URI uri = null;
Expand All @@ -204,9 +236,18 @@ public Response post(Request request) throws URISyntaxException, IOException {
return executeApiCall(httpPost);
}


/**
* Make a PATCH request and provide the status code, response body and
* response headers.
*
* @param request
* the request object
* @throws URISyntaxException
* in case of a URI syntax error
* @throws IOException
* in case of a network error
* @return the response object
*/
public Response patch(Request request) throws URISyntaxException, IOException {
URI uri = null;
Expand All @@ -231,9 +272,18 @@ public Response patch(Request request) throws URISyntaxException, IOException {
return executeApiCall(httpPatch);
}


/**
* Make a PUT request and provide the status code, response body and
* response headers.
*
* @param request
* the request object
* @throws URISyntaxException
* in case of a URI syntax error
* @throws IOException
* in case of a network error
* @return the response object
*/
public Response put(Request request) throws URISyntaxException, IOException {
URI uri = null;
Expand All @@ -258,8 +308,17 @@ public Response put(Request request) throws URISyntaxException, IOException {
return executeApiCall(httpPut);
}


/**
* Make a DELETE request and provide the status code and response headers.
*
* @param request
* the request object
* @throws URISyntaxException
* in case of a URI syntax error
* @throws IOException
* in case of a network error
* @return the response object
*/
public Response delete(Request request) throws URISyntaxException, IOException {
URI uri = null;
Expand Down Expand Up @@ -290,6 +349,16 @@ private void writeContentTypeIfNeeded(Request request, HttpMessage httpMessage)
}
}


/**
* Makes a call to the client API.
*
* @param httpPost
* the request method object
* @throws IOException
* in case of a network error
* @return the response object
*/
private Response executeApiCall(HttpRequestBase httpPost) throws IOException {
try {
CloseableHttpResponse serverResponse = httpClient.execute(httpPost);
Expand All @@ -303,8 +372,15 @@ private Response executeApiCall(HttpRequestBase httpPost) throws IOException {
}
}


/**
* A thin wrapper around the HTTP methods.
*
* @param request
* the request object
* @throws IOException
* in case of a network error
* @return the response object
*/
public Response api(Request request) throws IOException {
try {
Expand Down Expand Up @@ -334,11 +410,25 @@ public Response api(Request request) throws IOException {
}
}


/**
* Closes the http client.
*
* @throws IOException
* in case of a network error
*/
@Override
public void close() throws IOException {
this.httpClient.close();
}


/**
* Closes and finalizes the http client.
*
* @throws Throwable
* in case of an error
*/
@Override
public void finalize() throws Throwable {
try {
Expand Down