jdisc_core/src/main/java/com/yahoo/jdisc/handler/ResponseHandler.java


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

// Copyright 2017 Yahoo Holdings. Licensed under the terms of the Apache 2.0 license. See LICENSE in the project root.
package com.yahoo.jdisc.handler;

import com.yahoo.jdisc.Request;
import com.yahoo.jdisc.Response;
import com.yahoo.jdisc.service.ClientProvider;

/**
 * <p>This interface defines a component that is capable of acting as a handler for a {@link Response}. An
 * implementation of this interface is required to be passed alongside every {@link Request} as part of the API (see
 * {@link ClientProvider#handleRequest(Request, ResponseHandler)} and {@link RequestHandler#handleRequest(Request,
 * ResponseHandler)}).</p>
 *
 * <p>The jDISC API has intentionally been designed as not to provide a implicit reference from Response to
 * corresponding Request, but rather leave that to the implementation of context-aware ResponseHandlers. By creating
 * light-weight ResponseHandlers on a per-Request basis, any necessary reference can be embedded within.</p>
 *
 * @author <a href="mailto:simon@yahoo-inc.com">Simon Thoresen</a>
 */
public interface ResponseHandler {

    /**
     * <p>This method will process the given {@link Response} and return a {@link ContentChannel} into which the caller
     * can write the Response's content.</p>
     *
     * @param response The Response to handle.
     * @return The ContentChannel to write the Response content to. Notice that the ContentChannel holds a Container
     *         reference, so failure to close this will prevent the Container from ever shutting down.
     */
    ContentChannel handleResponse(Response response);

}