We have now seen how our business domain is accessed from the outside via HTTP.

In order to perform the business logic, the majority of enterprise applications need to access other external systems as well. External systems don't include databases that are owned by our application. Usually external systems are external to the application's domain. They reside in another bounded context.

In order to access external HTTP services, we integrate a client component into our project, usually as a separate control. This control class encapsulates the functionality required to communicate with the external system. It is advisable to carefully construct the interface and not to mix domain concerns with communication implementation details. These details include potential payload mappings, the communication protocol, HTTP information if HTTP is being used, and any other aspect not relevant to the core domain.

JAX-RS ships with a sophisticated client feature that accesses HTTP services in a productive way. It provides the same type mapping functionalities as it does for resource classes. The following code represents a control that accesses an external system to order coffee beans:

import javax.annotation.PostConstruct;
import javax.annotation.PreDestroy;
import javax.enterprise.context.ApplicationScoped;
import javax.ws.rs.client.*;
import java.util.concurrent.TimeUnit;

@ApplicationScoped
public class CoffeePurchaser {

    private Client client;
    private WebTarget target;

    @PostConstruct
    private void initClient() {
        client = ClientBuilder.newClient();
        target = client.target("http://coffee.example.com/beans/purchases/");
    }

    public OrderId purchaseBeans(BeanType type) {
        // construct purchase payload from type
        Purchase purchase = ...

        BeanOrder beanOrder = target
                .request(MediaType.APPLICATION_JSON_TYPE)
                .post(Entity.json(purchase))
                .readEntity(BeanOrder.class);

        return beanOrder.getId();
    }

    @PreDestroy
    public void closeClient() {
        client.close();
    }
}

The JAX-RS client is built and configured by the client builder and uses web targets to access URLs. These targets can be modified using a URI builder functionality, similar to the one in the JAX-RS resources. Targets are used to build new invocations that represent the actual HTTP invocations. The invocations can be configured in regard to HTTP information, such as content types, headers, as well as specifics of mapped Java types.

In this example, the target that points to the external URL builds a new request for the JSON content type with a HTTP POST method. The returned JSON structure is expected to be mappable to a BeanOrder object. The client performs further logic to extract the necessary information.

The client instance will be closed properly on container shutdown in the @PreDestroy-method to prevent resource leaks.