GxRest/GxHTTP

From Gcube Wiki
(Redirected from GxHTTP)
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.

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://wiki.gcube-system.org/index.php?title=GxRest/GxHTTP&oldid=32135"