//
//  ========================================================================
//  Copyright (c) 1995-2017 Mort Bay Consulting Pty. Ltd.
//  ------------------------------------------------------------------------
//  All rights reserved. This program and the accompanying materials
//  are made available under the terms of the Eclipse Public License v1.0
//  and Apache License v2.0 which accompanies this distribution.
//
//      The Eclipse Public License is available at
//      http://www.eclipse.org/legal/epl-v10.html
//
//      The Apache License v2.0 is available at
//      http://www.opensource.org/licenses/apache2.0.php
//
//  You may elect to redistribute this code under either of these licenses.
//  ========================================================================
//

package org.eclipse.jetty.rhttp.gateway;

import java.io.IOException;
import java.util.List;

import javax.servlet.http.HttpServletRequest;

import org.eclipse.jetty.rhttp.client.RHTTPRequest;


/**
 * <p>A <tt>ClientDelegate</tt> is the server-side counterpart of a gateway client.</p>
 * <p>The gateway client, the comet protocol and the <tt>ClientDelegate</tt> form the
 * <em>Half-Object plus Protocol</em> pattern that is used between the gateway server
 * and the gateway client.</p>
 * <p><tt>ClientDelegate</tt> offers a server-side API on top of the comet communication.<br />
 * The API allows to enqueue server-side events to the gateway client, allows to
 * flush them to the gateway client, and allows to close and dispose server-side
 * resources when the gateway client disconnects.</p>
 *
 * @version $Revision$ $Date$
 */
public interface ClientDelegate
{
    /**
     * @return the targetId that uniquely identifies this client delegate.
     */
    public String getTargetId();

    /**
     * <p>Enqueues the given request to the delivery queue so that it will be sent to the
     * gateway client on the first flush occasion.</p>
     * <p>Requests may fail to be queued, for example because the gateway client disconnected
     * concurrently.</p>
     *
     * @param request the request to add to the delivery queue
     * @return whether the request has been queued or not
     * @see #process(HttpServletRequest)
     */
    public boolean enqueue(RHTTPRequest request);

    /**
     * <p>Flushes the requests that have been {@link #enqueue(RHTTPRequest) enqueued}.</p>
     * <p>If no requests have been enqueued, then this method may suspend the current request for
     * the long poll timeout. <br />
     * The request is suspended only if all these conditions holds true:
     * <ul>
     * <li>it is not the first time that this method is called for this client delegate</li>
     * <li>no requests have been enqueued</li>
     * <li>this client delegate is not closed</li>
     * <li>the previous call to this method did not suspend the request</li>
     * </ul>
     * In all other cases, a response if sent to the gateway client, possibly containing no requests.
     *
     * @param httpRequest the HTTP request for the long poll request from the gateway client
     * @return the list of requests to send to the gateway client, or null if no response should be sent
     * to the gateway client
     * @throws IOException in case of I/O exception while flushing content to the gateway client
     * @see #enqueue(RHTTPRequest)
     */
    public List<RHTTPRequest> process(HttpServletRequest httpRequest) throws IOException;

    /**
     * <p>Closes this client delegate, in response to a gateway client request to disconnect.</p>
     * @see #isClosed()
     */
    public void close();

    /**
     * @return whether this delegate client is closed
     * @see #close()
     */
    public boolean isClosed();
}