{#========================================== Spincast HTTP Client plugin ==========================================#} {% extends "../../layout.html" %} {% block sectionClasses %}plugins hasBreadCrumb plugins-spincast-http-client{% endblock %} {% block meta_title %}Plugins - Spincast HTTP Client{% endblock %} {% block meta_description %}Client to easily create and send HTTP requests.{% endblock %} {% block scripts %} {% endblock %} {% block body %}
  1. Plugins
  2. Spincast HTTP Client plugin

Spincast HTTP Client plugin

Spincast HTTP Client plugin

Overview

Provides an easy way of creating and sending HTTP requests. The interface to inject to get the provided client is HttpClient

Please note that this is the light version of the Spincast HTTP client, without support for WebSockets. If you want your client to be able to establish WebSocket connections, use the Spincast HTTP Client With WebSocket version!

This client is built around Apache HttpClient. Note that no extra dependencies are added by this plugin because it uses the shaded version of Apache HttpClient, which is already included in the spincast-core artifact.

All the integration tests of Spincast use this HTTP client so have a look at them for a lot of examples!

Quick Examples

  • Simple GET request. We get the response as a string and print it : 

    HttpResponse response = httpClient.GET("https://www.google.com").send();
                                           
System.out.println(response.getContentAsString());

  • Complexe POST request. We send a Json object representing a user, with some extra HTTP headers : 

    User user = getUser();
HttpResponse response = httpClient.POST("https://example.com/api/users")
                                   .setEntityJson(user)
                                   .addCookie("cookieKey", "cookieValue")
                                   .addHeaderValue("headerKey", "headerValue")
                                   .send();
                                           
if(response.getStatus() == 200) { // or use : HttpStatus.SC_OK
    String content = response.getContentAsString();
    Cookie cookie = response.getCookie("someCookie");
    String header = response.getHeaderFirst("someHeader"); 
} else {
    //...
}

Installation

The Spincast Http Client is already available in the test Maven scope, when you include the spincast-testing-default or the spincast-testing-core artifacts to help you with your tests. If you want to use the Spincast Http Client in your application, and not only in your tests, you have to include it as a regular dependency: 

<dependency>
    <groupId>org.spincast</groupId>
    <artifactId>spincast-plugins-http-client</artifactId>
    <version>{{spincast.spincastCurrrentVersion}}</version>
</dependency>

Then, install the plugin's Guice module, by passing it to the Guice.createInjector(...) method: 

Injector guice = Guice.createInjector(
        new AppModule(args),
        new SpincastHttpClientPluginGuiceModule(AppRequestContext.class, 
                                                AppWebsocketContext.class)
        // other modules...
        );

... or by using the install(...) method from your custom Guice module: 

public class AppModule extends SpincastDefaultGuiceModule {

    //...

    @Override
    protected void configure() {
        super.configure();
        install(new SpincastHttpClientPluginGuiceModule(getRequestContextType(), 
                                                        getWebsocketContextType()));
        // other modules...
    }
    
    // ...
}

Usage

To use Spincast's HTTP Client, you can inject HttpClient where you need it. This object is a builder : it is thread safe and can be injected in multiple classes. Let's see an example : 

public class AppController {

    private final HttpClient httpClient;

    @Inject
    public AppController(HttpClient httpClient) {
        this.httpClient = httpClient;
    }

    protected HttpClient httpClient() {
        return this.httpClient;
    }

    public void myRouteHandler(AppRequestContext context) {

        HttpResponse response = httpClient().GET("https://www.google.com").send();
        if(response.getStatus() == HttpStatus.SC_OK) {
            //...
        }
    }
}

If you want, you can also extend your custom Request Context objects to add HttpClient as an add-on. To do that, let's tweak some components:

Your AppRequestContext interface 

public interface AppRequestContext extends RequestContext<AppRequestContext> {

    //...
    
    public HttpClient httpClient();
}

The Request Context implementation : 

public class AppRequestContext extends RequestContextBase<AppRequestContext>
                               implements AppRequestContext {

    private final HttpClient httpClient;

    @AssistedInject
    public AppRequestContext(@Assisted Object exchange,
                             RequestContextBaseDeps<AppRequestContext> requestContextBaseDeps,
                             HttpClient httpClient) {
        super(exchange, requestContextBaseDeps);
        this.httpClient = httpClient;
    }
    
    //...

    @Override
    public HttpClient httpClient() {
        return this.httpClient;
    }
}

Then, you can use the HTTP Client directly from your Route Handlers! : 

public class AppController {

    public void myRouteHandler(AppRequestContext context) {

        HttpResponse response = context.httpClient().GET("https://www.google.com").send();
        if(response.getStatus() == HttpStatus.SC_OK) {
            //...
        }
    }
}

Javadoc

{% endblock %}