Difference between revisions of "GxRest"
Manuele.simi (Talk | contribs) (→gxJRS) |
Manuele.simi (Talk | contribs) |
||
| Line 9: | Line 9: | ||
* it can be used only to return HTTP codes from the service. | * it can be used only to return HTTP codes from the service. | ||
| − | == | + | == gxHTTP == |
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
This module defines the HTTP interface for a client of a gCube service and basic extensions to plain HTTP requests with zero-dependencies. | This module 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. | 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. | ||
| − | + | === Distribution === | |
gxHTTP is available as Maven artifact and can be added to a maven-based project with the following dependency: | gxHTTP is available as Maven artifact and can be added to a maven-based project with the following dependency: | ||
<source lang="xml"> | <source lang="xml"> | ||
| Line 27: | Line 23: | ||
</source> | </source> | ||
| − | + | == gxJRS == | |
| − | gxJRS is much more advanced | + | gxJRS is much more advanced than gxHTTP and offers fully-fledged extensions built on top of JAX-RS and gxHTTP. It provides: |
** context-aware [[GxRest/GxJRS/Requests | requests]] sent from a client to a web application | ** context-aware [[GxRest/GxJRS/Requests | requests]] sent from a client to a web application | ||
** outbound status-aware [[GxRest/GxJRS/Responses#Outbound_Responses | responses]] returned from a web application | ** outbound status-aware [[GxRest/GxJRS/Responses#Outbound_Responses | responses]] returned from a web application | ||
| Line 40: | Line 36: | ||
* to return error responses at the familiar (for any Java programmer) level of exceptions and error codes, while web frameworks usually just let return an HTTP status, headers and streams. | * to return error responses at the familiar (for any Java programmer) level of exceptions and error codes, while web frameworks usually just let return an HTTP status, headers and streams. | ||
| − | + | === Correlation with the JAX-RS runtime === | |
The gxJRS approach is independent from the [https://jcp.org/en/jsr/detail?id=311 JAX-RS] implementation used to develop the web application, being entirely based on the <code lang="Java">javax.ws.rs</code> package. However, some features rely on a JAX-RS runtime implementation. It dynamically loads the implementation available on the classpath and uses it for modeling and sending the responses and requests. The reference implementation for JAX-RS is named [http://jersey.java.net/ Jersey], but it is not included in Java SE. You must explicitly add Jersey or another JAR-RS implementation to your classpath. | The gxJRS approach is independent from the [https://jcp.org/en/jsr/detail?id=311 JAX-RS] implementation used to develop the web application, being entirely based on the <code lang="Java">javax.ws.rs</code> package. However, some features rely on a JAX-RS runtime implementation. It dynamically loads the implementation available on the classpath and uses it for modeling and sending the responses and requests. The reference implementation for JAX-RS is named [http://jersey.java.net/ Jersey], but it is not included in Java SE. You must explicitly add Jersey or another JAR-RS implementation to your classpath. | ||
At request side, a JAX-RS runtime is not strictly required as one of the requests implementation builds atop of plain HTTP protocol. | At request side, a JAX-RS runtime is not strictly required as one of the requests implementation builds atop of plain HTTP protocol. | ||
| − | + | === Distribution === | |
gxJRS is available as Maven artifact and can be added to a maven-based project with the following dependency: | gxJRS is available as Maven artifact and can be added to a maven-based project with the following dependency: | ||
<source lang="xml"> | <source lang="xml"> | ||
Revision as of 05:42, 17 January 2019
Contents
Goals and Principles
The gCube eXtensions to the Rest Protocol (gxRest) is a Java library designed to provide convenient round-trip interaction between a Restful web application (also known as "service") and its clients.
Exploitation
gxRest has the flexibility for different degrees of exploitation of the library:
- it can be entirely adopted both at client and service side with full benefit of its conventions;
- it can be used just to send REST requests based only on plain HTTP;
- it can be used to parse the HTTP code of a response;
- it can be used only to return HTTP codes from the service.
gxHTTP
This module 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.
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>
gxJRS
gxJRS is much more advanced than gxHTTP and offers fully-fledged extensions built on top of JAX-RS and gxHTTP. It provides:
Prominent features of gxJRS are:
- to achieve independence from the web framework used to develop the web application;
- to guarantee the correctness of requests/responses across the D4Science infrastructure;
- to abstract over the HTTP-based details required by the gCube framework when invoking a remote service;
- to avoid that each service implements its own conventions over the returned responses;
- to return error responses at the familiar (for any Java programmer) level of exceptions and error codes, while web frameworks usually just let return an HTTP status, headers and streams.
Correlation with the JAX-RS runtime
The gxJRS approach is independent from the JAX-RS implementation used to develop the web application, being entirely based on the javax.ws.rs package. However, some features rely on a JAX-RS runtime implementation. It dynamically loads the implementation available on the classpath and uses it for modeling and sending the responses and requests. The reference implementation for JAX-RS is named Jersey, but it is not included in Java SE. You must explicitly add Jersey or another JAR-RS implementation to your classpath.
At request side, a JAX-RS runtime is not strictly required as one of the requests implementation builds atop of plain HTTP protocol.
Distribution
gxJRS 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>gxJRS</artifactId> <version>LATEST</version> </dependency>
Integration with the client libraries of FWS
gxRest smoothly integrates with the client libraries (common-jaxrs-client, common-clients) of the FeatherWeight Stack by providing a request (GXWebTargetAdapterRequest) fully compatible with javax.ws.rs.client.WebTarget. The integration is described in a dedicate section of the request page.
