GxRest/GxHTTP

From Gcube Wiki
Revision as of 03:15, 1 April 2019 by Manuele.simi (Talk | contribs)

Jump to: navigation, search

Scope and Features

gxHTTP defines the HTTP interface for a client of a gCube service and basic extensions to plain HTTP requests with zero-dependencies. More specifically, it provides context-aware requests sent from a client to a web application, but no support for managing responses both at service and client side.

Sample usages here.

Request interface

The org.gcube.common.gxhttp.reference interface defines the behavior of all the requests in gxRest. 

/**
 * 
 * HTTP methods for requests.
 * 
 * @author Manuele Simi (ISTI-CNR)
 *
 * @param <BODY> the type of the body request
 * @param <RESPONSE> the type of the response
 
 */
public interface GXHTTP<BODY,RESPONSE> {
 
	/**
	 * Sends the PUT request to the web application.
	 * @param body the body of the request
	 * @return the response
	 */
	RESPONSE put(BODY body) throws Exception;
 
	/**
	 * Sends the PUT request to the web application with no body.
	 * @return the response
	 */
	RESPONSE put() throws Exception;
 
	/**
	 * Sends the DELETE request to the web application.
	 * @return the response
	 */
	RESPONSE delete() throws Exception;
 
	/**
	 * Sends the HEAD request to the web application.
	 * @return the response
	 */
	RESPONSE head() throws Exception;
 
	/**
	 * Sends the GET request to the web application.
	 * @return the response
	 */
	RESPONSE get() throws Exception;
 
	/**
	 * Sends the POST request to the web application.
	 * @param body the body of the request
	 * @return the response
	 * @throws Exception
	 */
	RESPONSE post(BODY body) throws Exception;
 
	/**
	 * Sends the POST request to the web application with no body.
	 * @return the response
	 * @throws Exception
	 */
	RESPONSE post() throws Exception;
 
	/**
	 * Sends the TRACE request to the web application with no body.
	 * @return the response
	 * @throws Exception
	 */
	RESPONSE trace() throws Exception;
 
	/**
	 * Sends the PATCH request to the web application with no body.
	 * @return the response
	 * @throws Exception
	 */
	RESPONSE patch() throws Exception;
 
	/**
	 * Sends the OPTIONS request to the web application with no body.
	 * @return the response
	 * @throws Exception
	 */
	RESPONSE options() throws Exception;
 
	/**
	 * Sends the CONNECT request to the web application with no body.
	 * @return the response
	 * @throws Exception
	 */
	RESPONSE connect() throws Exception;
 
	/**
	 * Overrides the default security token.
	 * @param token the new token
	 */
	void setSecurityToken(String token);
 
	/**
	 * States if the service being called in an external service (not gCube).
	 * @param ext true if external, false otherwise
	 */
	void isExternalCall(boolean ext);
 
}

Requests

Given that gxHTTP brings no dependencies, there are two type of requests that can be created and submitted.

Working with Strings: GXHTTPStringRequest

The following snippet shows how to send a POST request with a string in the body: 

import java.net.HttpURLConnection;
import org.gcube.common.gxhttp.util.ContentUtils;
import org.gcube.common.gxhttp.request.GXHTTPStringRequest;
 
GXHTTPStringRequest request = GXHTTPStringRequest.newRequest("Service URL").from("agent");
String context = "...";
Map<String,String> queryParams = new WeakHashMap<>();
queryParams.put("name", value);
try {
	HttpURLConnection response = request.path("gxrest")
					.header("Another header", "GXHTTPRequestTest")
					.queryParams(queryParams).post(context);
	if(response.getResponseCode() == Status.CREATED.getStatusCode()) {
		String body =  ContentUtils.toString(ContentUtils.toByteArray(response.getInputStream()));
		System.out.println("Returned response " + body);
	}
} catch (Exception e) {
	// handle the error
}

Working with Streams: GXHTTPStreamRequest

The following snippet shows how to send a POST request with a file's content as body: 

import java.net.HttpURLConnection;
import org.gcube.common.gxhttp.util.ContentUtils;
import org.gcube.common.gxhttp.request.GXHTTPStreamRequest;
 
InputStream bodyStream = new FileInputStream("my path");
GXHTTPStreamRequest request = GXHTTPStreamRequest.newRequest("Service URL").from("agent");
Map<String,String> queryParams = new WeakHashMap<>();
queryParams.put("name", value);
try {
	HttpURLConnection response = request.path("gxrest")
					.header("Another header", "GXHTTPRequestTest")
					.queryParams(queryParams).post(bodyStream);
	if(response.getResponseCode() == Status.CREATED.getStatusCode()) {
		String body =  ContentUtils.toString(ContentUtils.toByteArray(response.getInputStream()));
		System.out.println("Returned response " + body);
	}
 
} catch (Exception e) {
	// handle the error
}


Distribution

gxHTTP is available as Maven artifact and can be added to a maven-based project with the following dependency: 

<dependency>
	<groupId>org.gcube.common</groupId>
	<artifactId>gxHTTP</artifactId>
	<version>LATEST</version>
</dependency>
Retrieved from "https://gcube.wiki.gcube-system.org/index.php?title=GxRest/GxHTTP&oldid=32120"