Difference between revisions of "GxRest/GxHTTP"

From Gcube Wiki
Jump to: navigation, search
(→‎Working with Strings: GXHTTPStringRequest)
m (Manuele.simi moved page GxHTTP to GxRest/GxHTTP)
 
(10 intermediate revisions by the same user not shown)
Line 1: Line 1:
 +
= 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 [[GxHTTP#Requests | requests]] sent from a client to a web application, but no support for managing responses both at service and client side.
 +
 
= Request interface =
 
= Request interface =
  
Line 106: Line 110:
 
</source>
 
</source>
 
= Requests =
 
= Requests =
 +
Given that gxHTTP brings no dependencies, there are two type of requests that can be created and submitted.
 +
 
== Working with Strings: GXHTTPStringRequest ==
 
== Working with Strings: GXHTTPStringRequest ==
 
The following snippet shows how to send a POST request with a string in the body:
 
The following snippet shows how to send a POST request with a string in the body:
 
<source lang="Java">
 
<source lang="Java">
 
import java.net.HttpURLConnection;
 
import java.net.HttpURLConnection;
 +
import org.gcube.common.gxhttp.util.ContentUtils;
 
import org.gcube.common.gxhttp.request.GXHTTPStringRequest;
 
import org.gcube.common.gxhttp.request.GXHTTPStringRequest;
  
Line 115: Line 122:
 
String context = "...";
 
String context = "...";
 
Map<String,String> queryParams = new WeakHashMap<>();
 
Map<String,String> queryParams = new WeakHashMap<>();
−
queryParams.put("rrURL", DEFAULT_RR_URL);
+
queryParams.put("name", value);
 
try {
 
try {
 
HttpURLConnection response = request.path("gxrest")
 
HttpURLConnection response = request.path("gxrest")
 
.header("Another header", "GXHTTPRequestTest")
 
.header("Another header", "GXHTTPRequestTest")
 
.queryParams(queryParams).post(context);
 
.queryParams(queryParams).post(context);
−
assertTrue("Unexpected returned code.", response.getResponseCode() == Status.CREATED.getStatusCode());
+
if(response.getResponseCode() == Status.CREATED.getStatusCode()) {
−
String body =  ContentUtils.toString(ContentUtils.toByteArray(response.getInputStream()));
+
String body =  ContentUtils.toString(ContentUtils.toByteArray(response.getInputStream()));
−
System.out.println("Returned resposnse " + body);
+
System.out.println("Returned response " + body);
 +
}
 
} catch (Exception e) {
 
} catch (Exception e) {
 
// handle the error
 
// handle the error
Line 129: Line 137:
  
 
== Working with Streams: GXHTTPStreamRequest ==
 
== Working with Streams: GXHTTPStreamRequest ==
−
The following snippet shows how to send a POST request that loads the body from an input stream:
+
The following snippet shows how to send a POST request with a file's content as body:
 
<source lang="Java">
 
<source lang="Java">
 +
import java.net.HttpURLConnection;
 +
import org.gcube.common.gxhttp.util.ContentUtils;
 
import org.gcube.common.gxhttp.request.GXHTTPStreamRequest;
 
import org.gcube.common.gxhttp.request.GXHTTPStreamRequest;
  
 +
InputStream bodyStream = new FileInputStream("my path");
 
GXHTTPStreamRequest request = GXHTTPStreamRequest.newRequest("Service URL").from("agent");
 
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
 +
}
 +
</source>
 +
 
 +
 
 +
= Distribution =
 +
gxHTTP is available as Maven artifact and can be added to a maven-based project with the following dependency:
 +
<source lang="xml">
 +
<dependency>
 +
<groupId>org.gcube.common</groupId>
 +
<artifactId>gxHTTP</artifactId>
 +
<version>LATEST</version>
 +
</dependency>
 
</source>
 
</source>

Latest revision as of 04:03, 2 April 2019

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