//
//  ========================================================================
//  Copyright (c) 1995-2014 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.server;

import java.io.IOException;

import org.eclipse.jetty.io.Buffers;
import org.eclipse.jetty.io.EndPoint;
import org.eclipse.jetty.util.component.LifeCycle;

/** HTTP Connector.
 * Implementations of this interface provide connectors for the HTTP protocol.
 * A connector receives requests (normally from a socket) and calls the 
 * handle method of the Handler object.  These operations are performed using
 * threads from the ThreadPool set on the connector.
 * 
 * When a connector is registered with an instance of Server, then the server
 * will set itself as both the ThreadPool and the Handler.  Note that a connector
 * can be used without a Server if a thread pool and handler are directly provided.
 * 
 * 
 * 
 */
/**
 * @author gregw
 *
 */
public interface Connector extends LifeCycle
{ 
	/* ------------------------------------------------------------ */
	/**
	 * @return the name of the connector. Defaults to the HostName:port
	 */
	String getName();
	
	/* ------------------------------------------------------------ */
	/**
	 * Opens the connector 
	 * @throws IOException
	 */
	void open() throws IOException;

	/* ------------------------------------------------------------ */
	void close() throws IOException;

	/* ------------------------------------------------------------ */
	void setServer(Server server);
	
	/* ------------------------------------------------------------ */
	Server getServer();

	/* ------------------------------------------------------------ */
	/**
	 * @return Returns the request header buffer size in bytes.
	 */
	int getRequestHeaderSize();
	
	/* ------------------------------------------------------------ */
	/**
	 * Set the size of the buffer to be used for request headers.
	 * @param size The size in bytes.
	 */
	void setRequestHeaderSize(int size);

	/* ------------------------------------------------------------ */
	/**
	 * @return Returns the response header buffer size in bytes.
	 */
	int getResponseHeaderSize();
	
	/* ------------------------------------------------------------ */
	/**
	 * Set the size of the buffer to be used for request headers.
	 * @param size The size in bytes.
	 */
	void setResponseHeaderSize(int size);
	

	/* ------------------------------------------------------------ */
	/**
	 * @return factory for request buffers
	 */
	Buffers getRequestBuffers();

	/* ------------------------------------------------------------ */
	/**
	 * @return factory for response buffers
	 */
	Buffers getResponseBuffers();
	
	
	/* ------------------------------------------------------------ */
	/**
	 * @return Returns the requestBufferSize.
	 */
	int getRequestBufferSize();
	
	/* ------------------------------------------------------------ */
	/**
	 * Set the size of the content buffer for receiving requests. 
	 * These buffers are only used for active connections that have
	 * requests with bodies that will not fit within the header buffer.
	 * @param requestBufferSize The requestBufferSize to set.
	 */
	void setRequestBufferSize(int requestBufferSize);
	
	/* ------------------------------------------------------------ */
	/**
	 * @return Returns the responseBufferSize.
	 */
	int getResponseBufferSize();
	
	/* ------------------------------------------------------------ */
	/**
	 * Set the size of the content buffer for sending responses. 
	 * These buffers are only used for active connections that are sending 
	 * responses with bodies that will not fit within the header buffer.
	 * @param responseBufferSize The responseBufferSize to set.
	 */
	void setResponseBufferSize(int responseBufferSize);
	

	/* ------------------------------------------------------------ */
	/**
	 * @return The port to use when redirecting a request if a data constraint of integral is 
	 * required. See {@link org.eclipse.jetty.util.security.Constraint#getDataConstraint()}
	 */
	int getIntegralPort();

	/* ------------------------------------------------------------ */
	/**
	 * @return The schema to use when redirecting a request if a data constraint of integral is 
	 * required. See {@link org.eclipse.jetty.util.security.Constraint#getDataConstraint()}
	 */
	String getIntegralScheme();

	/* ------------------------------------------------------------ */
	/**
	 * @param request A request
	 * @return true if the request is integral. This normally means the https schema has been used.
	 */
	boolean isIntegral(Request request);

	/* ------------------------------------------------------------ */
	/**
	 * @return The port to use when redirecting a request if a data constraint of confidential is 
	 * required. See {@link org.eclipse.jetty.util.security.Constraint#getDataConstraint()}
	 */
	int getConfidentialPort();
	

	/* ------------------------------------------------------------ */
	/**
	 * @return The schema to use when redirecting a request if a data constraint of confidential is 
	 * required. See {@link org.eclipse.jetty.util.security.Constraint#getDataConstraint()}
	 */
	String getConfidentialScheme();
	
	/* ------------------------------------------------------------ */
	/**
	 * @param request A request
	 * @return true if the request is confidential. This normally means the https schema has been used.
	 */
	boolean isConfidential(Request request);

	/* ------------------------------------------------------------ */
	/** Customize a request for an endpoint.
	 * Called on every request to allow customization of the request for
	 * the particular endpoint (eg security properties from a SSL connection).
	 * @param endpoint
	 * @param request
	 * @throws IOException
	 */
	void customize(EndPoint endpoint, Request request) throws IOException;

	/* ------------------------------------------------------------ */
	/** Persist an endpoint.
	 * Called after every request if the connection is to remain open.
	 * @param endpoint
	 * @throws IOException
	 */
	void persist(EndPoint endpoint) throws IOException;
	
	/* ------------------------------------------------------------ */
	/**
	 * @return The hostname representing the interface to which 
	 * this connector will bind, or null for all interfaces.
	 */
	String getHost();
	
	/* ------------------------------------------------------------ */
	/**
	 * Set the hostname of the interface to bind to.
	 * @param hostname The hostname representing the interface to which 
	 * this connector will bind, or null for all interfaces.
	 */
	void setHost(String hostname);

	/* ------------------------------------------------------------ */
	/**
	 * @param port The port to listen of for connections or 0 if any available
	 * port may be used.
	 */
	void setPort(int port);
	
	/* ------------------------------------------------------------ */
	/**
	 * @return The configured port for the connector or 0 if any available
	 * port may be used.
	 */
	int getPort();
	
	/* ------------------------------------------------------------ */
	/**
	 * @return The actual port the connector is listening on or
	 * -1 if it has not been opened, or -2 if it has been closed.
	 */
	int getLocalPort();
	
	/* ------------------------------------------------------------ */
	/**
	 * @return Max Idle time for connections in milliseconds
	 */
	int getMaxIdleTime();
	
	/**
	 * @param ms Max Idle time for connections in milliseconds
	 */
	void setMaxIdleTime(int ms);
	
	/* ------------------------------------------------------------ */
	int getLowResourceMaxIdleTime();
	void setLowResourceMaxIdleTime(int ms);
	
	/* ------------------------------------------------------------ */
	/**
	 * @return the underlying socket, channel, buffer etc. for the connector.
	 */
	Object getConnection();
	
	
	/* ------------------------------------------------------------ */
	/**
	 * @return true if names resolution should be done.
	 */
	boolean getResolveNames();
	
	

	/* ------------------------------------------------------------ */
	/** Check if low on resources.
	 * For most connectors, low resources is measured by calling 
	 * {@link Server#isLowOnThreads()} on the connector threadpool
	 * or the server threadpool if there is no connector threadpool.
	 * <p>
	 * For blocking connectors, low resources is used to trigger
	 * usage of {@link #getLowResourceMaxIdleTime()} for the timeout
	 * of an idle connection.
	 * <p>
	 * for non-blocking connectors, the number of connections is
	 * used instead of this method, to select the timeout of an 
	 * idle connection.
	 * <p>
	 * For all connectors, low resources is used to trigger the 
	 * usage of {@link #getLowResourceMaxIdleTime()} for read and 
	 * write operations.
	 * 
	 * @return true if this connector is low on resources.
	 */
	public boolean isLowResources();
}