jetty-websocket/websocket-api/src/main/java/org/eclipse/jetty/websocket/api/UpgradeRequest.java - jetty/org.eclipse.jetty.project - Git at Google

 //
 //  ========================================================================
 //  Copyright (c) 1995-2015 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.websocket.api;

 import java.net.HttpCookie;
 import java.net.URI;
 import java.security.Principal;
 import java.util.List;
 import java.util.Map;

 import org.eclipse.jetty.websocket.api.extensions.ExtensionConfig;

 /**
  * The HTTP Upgrade to WebSocket Request
  */
 public interface UpgradeRequest
 {
     /**
      * Add WebSocket Extension Configuration(s) to Upgrade Request.
      * <p>
      * This is merely the list of requested Extensions to use, see {@link UpgradeResponse#getExtensions()} for what was
      * negotiated
      *
      * @param configs the configuration(s) to add
      */
     void addExtensions(ExtensionConfig... configs);

     /**
      * Add WebSocket Extension Configuration(s) to request
      * <p>
      * This is merely the list of requested Extensions to use, see {@link UpgradeResponse#getExtensions()} for what was
      * negotiated
      *
      * @param configs the configuration(s) to add
      */
     void addExtensions(String... configs);

     /**
      * Remove all headers from request.
      * @deprecated (no longer supported, as this can undo the required upgrade request headers)
      */
     @Deprecated
     void clearHeaders();

     /**
      * Get the list of Cookies on the Upgrade request
      *
      * @return the list of Cookies
      */
     List<HttpCookie> getCookies();

     /**
      * Get the list of WebSocket Extension Configurations for this Upgrade Request.
      * <p>
      * This is merely the list of requested Extensions to use, see {@link UpgradeResponse#getExtensions()} for what was
      * negotiated
      *
      * @return the list of Extension configurations (in the order they were specified)
      */
     List<ExtensionConfig> getExtensions();

     /**
      * Get a specific Header value from Upgrade Request
      *
      * @param name the name of the header
      * @return the value of the header (null if header does not exist)
      */
     String getHeader(String name);

     /**
      * Get the specific Header value, as an <code>int</code>, from the Upgrade Request.
      *
      * @param name the name of the header
      * @return the value of the header as an <code>int</code> (-1 if header does not exist)
      * @throws NumberFormatException if unable to parse value as an int.
      */
     int getHeaderInt(String name);

     /**
      * Get the headers as a Map of keys to value lists.
      *
      * @return the headers
      */
     Map<String, List<String>> getHeaders();

     /**
      * Get the specific header values (for multi-value headers)
      *
      * @param name the header name
      * @return the value list (null if no header exists)
      */
     List<String> getHeaders(String name);

     /**
      * The host of the Upgrade Request URI
      * <p>
      * Equivalent to {@link #getRequestURI()#getHost()}
      *
      * @return host of the request URI
      */
     String getHost();

     /**
      * The HTTP version used for this Upgrade Request
      * <p>
      * As of <a href="http://tools.ietf.org/html/rfc6455">RFC6455 (December 2011)</a> this is always
      * <code>HTTP/1.1</code>
      *
      * @return the HTTP Version used
      */
     String getHttpVersion();

     /**
      * The HTTP method for this Upgrade Request.
      * <p>
      * As of <a href="http://tools.ietf.org/html/rfc6455">RFC6455 (December 2011)</a> this is always <code>GET</code>
      *
      * @return the HTTP method used
      */
     String getMethod();

     /**
      * The WebSocket Origin of this Upgrade Request
      * <p>
      * See <a href="http://tools.ietf.org/html/rfc6455#section-10.2">RFC6455: Section 10.2</a> for details.
      * <p>
      * Equivalent to {@link #getHeader("Origin")}
      *
      * @return the Origin header
      */
     String getOrigin();

     /**
      * Returns a map of the query parameters of the request.
      *
      * @return a unmodifiable map of query parameters of the request.
      */
     Map<String, List<String>> getParameterMap();

     /**
      * Get the WebSocket Protocol Version
      * <p>
      * As of <a href="http://tools.ietf.org/html/rfc6455#section-11.6">RFC6455</a>, Jetty only supports version
      * <code>13</code>
      *
      * @return the WebSocket protocol version
      */
     String getProtocolVersion();

     /**
      * Get the Query String of the request URI.
      * <p>
      * Equivalent to {@link #getRequestURI()#getQueryString()}
      *
      * @return the request uri query string
      */
     String getQueryString();

     /**
      * Get the Request URI
      *
      * @return the request URI
      */
     URI getRequestURI();

     /**
      * Access the Servlet HTTP Session (if present)
      * <p>
      * Note: Never present on a Client UpgradeRequest.
      *
      * @return the Servlet HTTPSession on server side UpgradeRequests
      */
     Object getSession();

     /**
      * Get the list of offered WebSocket sub-protocols.
      *
      * @return the list of offered sub-protocols
      */
     List<String> getSubProtocols();

     /**
      * Get the User Principal for this request.
      * <p>
      * Only applicable when using UpgradeRequest from server side.
      *
      * @return the user principal
      */
     Principal getUserPrincipal();

     /**
      * Test if a specific sub-protocol is offered
      *
      * @param test the sub-protocol to test for
      * @return true if sub-protocol exists on request
      */
     boolean hasSubProtocol(String test);

     /**
      * Test if supplied Origin is the same as the Request
      *
      * @param test the supplied origin
      * @return true if the supplied origin matches the request origin
      */
     boolean isOrigin(String test);

     /**
      * Test if connection is secure.
      *
      * @return true if connection is secure.
      */
     boolean isSecure();

     /**
      * Set the list of Cookies on the request
      *
      * @param cookies the cookies to use
      */
     void setCookies(List<HttpCookie> cookies);

     /**
      * Set the list of WebSocket Extension configurations on the request.
      * @param configs the list of extension configurations
      */
     void setExtensions(List<ExtensionConfig> configs);

     /**
      * Set a specific header with multi-value field
      * <p>
      * Overrides any previous value for this named header
      *
      * @param name the name of the header
      * @param values the multi-value field
      */
     void setHeader(String name, List<String> values);

     /**
      * Set a specific header value
      * <p>
      * Overrides any previous value for this named header
      *
      * @param name the header to set
      * @param value the value to set it to
      */
     void setHeader(String name, String value);

     /**
      * Sets multiple headers on the request.
      * <p>
      * Only sets those headers provided, does not remove
      * headers that exist on request and are not provided in the
      * parameter for this method.
      * <p>
      * Convenience method vs calling {@link #setHeader(String, List)} multiple times.
      *
      * @param headers the headers to set
      */
     void setHeaders(Map<String, List<String>> headers);

     /**
      * Set the HTTP Version to use.
      * <p>
      * As of <a href="http://tools.ietf.org/html/rfc6455">RFC6455 (December 2011)</a> this should always be
      * <code>HTTP/1.1</code>
      *
      * @param httpVersion the HTTP version to use.
      */
     void setHttpVersion(String httpVersion);

     /**
      * Set the HTTP method to use.
      * <p>
      * As of <a href="http://tools.ietf.org/html/rfc6455">RFC6455 (December 2011)</a> this is always <code>GET</code>
      *
      * @param method the HTTP method to use.
      */
     void setMethod(String method);

     /**
      * Set the Request URI to use for this request.
      * <p>
      * Must be an absolute URI with scheme <code>'ws'</code> or <code>'wss'</code>
      *
      * @param uri the Request URI
      */
     void setRequestURI(URI uri);

     /**
      * Set the Session associated with this request.
      * <p>
      * Typically used to associate the Servlet HttpSession object.
      *
      * @param session the session object to associate with this request
      */
     void setSession(Object session);

     /**
      * Set the offered WebSocket Sub-Protocol list.
      *
      * @param protocols the offered sub-protocol list
      */
     void setSubProtocols(List<String> protocols);

     /**
      * Set the offered WebSocket Sub-Protocol list.
      *
      * @param protocols the offered sub-protocol list
      */
     void setSubProtocols(String... protocols);

 }
	//
	// ========================================================================
	// Copyright (c) 1995-2015 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.websocket.api;

	import java.net.HttpCookie;
	import java.net.URI;
	import java.security.Principal;
	import java.util.List;
	import java.util.Map;

	import org.eclipse.jetty.websocket.api.extensions.ExtensionConfig;

	/**
	* The HTTP Upgrade to WebSocket Request
	*/
	public interface UpgradeRequest
	{
	/**
	* Add WebSocket Extension Configuration(s) to Upgrade Request.
	* <p>
	* This is merely the list of requested Extensions to use, see {@link UpgradeResponse#getExtensions()} for what was
	* negotiated
	*
	* @param configs the configuration(s) to add
	*/
	void addExtensions(ExtensionConfig... configs);

	/**
	* Add WebSocket Extension Configuration(s) to request
	* <p>
	* This is merely the list of requested Extensions to use, see {@link UpgradeResponse#getExtensions()} for what was
	* negotiated
	*
	* @param configs the configuration(s) to add
	*/
	void addExtensions(String... configs);

	/**
	* Remove all headers from request.
	* @deprecated (no longer supported, as this can undo the required upgrade request headers)
	*/
	@Deprecated
	void clearHeaders();

	/**
	* Get the list of Cookies on the Upgrade request
	*
	* @return the list of Cookies
	*/
	List<HttpCookie> getCookies();

	/**
	* Get the list of WebSocket Extension Configurations for this Upgrade Request.
	* <p>
	* This is merely the list of requested Extensions to use, see {@link UpgradeResponse#getExtensions()} for what was
	* negotiated
	*
	* @return the list of Extension configurations (in the order they were specified)
	*/
	List<ExtensionConfig> getExtensions();

	/**
	* Get a specific Header value from Upgrade Request
	*
	* @param name the name of the header
	* @return the value of the header (null if header does not exist)
	*/
	String getHeader(String name);

	/**
	* Get the specific Header value, as an <code>int</code>, from the Upgrade Request.
	*
	* @param name the name of the header
	* @return the value of the header as an <code>int</code> (-1 if header does not exist)
	* @throws NumberFormatException if unable to parse value as an int.
	*/
	int getHeaderInt(String name);

	/**
	* Get the headers as a Map of keys to value lists.
	*
	* @return the headers
	*/
	Map<String, List<String>> getHeaders();

	/**
	* Get the specific header values (for multi-value headers)
	*
	* @param name the header name
	* @return the value list (null if no header exists)
	*/
	List<String> getHeaders(String name);

	/**
	* The host of the Upgrade Request URI
	* <p>
	* Equivalent to {@link #getRequestURI()#getHost()}
	*
	* @return host of the request URI
	*/
	String getHost();

	/**
	* The HTTP version used for this Upgrade Request
	* <p>
	* As of <a href="http://tools.ietf.org/html/rfc6455">RFC6455 (December 2011)</a> this is always
	* <code>HTTP/1.1</code>
	*
	* @return the HTTP Version used
	*/
	String getHttpVersion();

	/**
	* The HTTP method for this Upgrade Request.
	* <p>
	* As of <a href="http://tools.ietf.org/html/rfc6455">RFC6455 (December 2011)</a> this is always <code>GET</code>
	*
	* @return the HTTP method used
	*/
	String getMethod();

	/**
	* The WebSocket Origin of this Upgrade Request
	* <p>
	* See <a href="http://tools.ietf.org/html/rfc6455#section-10.2">RFC6455: Section 10.2</a> for details.
	* <p>
	* Equivalent to {@link #getHeader("Origin")}
	*
	* @return the Origin header
	*/
	String getOrigin();

	/**
	* Returns a map of the query parameters of the request.
	*
	* @return a unmodifiable map of query parameters of the request.
	*/
	Map<String, List<String>> getParameterMap();

	/**
	* Get the WebSocket Protocol Version
	* <p>
	* As of <a href="http://tools.ietf.org/html/rfc6455#section-11.6">RFC6455</a>, Jetty only supports version
	* <code>13</code>
	*
	* @return the WebSocket protocol version
	*/
	String getProtocolVersion();

	/**
	* Get the Query String of the request URI.
	* <p>
	* Equivalent to {@link #getRequestURI()#getQueryString()}
	*
	* @return the request uri query string
	*/
	String getQueryString();

	/**
	* Get the Request URI
	*
	* @return the request URI
	*/
	URI getRequestURI();

	/**
	* Access the Servlet HTTP Session (if present)
	* <p>
	* Note: Never present on a Client UpgradeRequest.
	*
	* @return the Servlet HTTPSession on server side UpgradeRequests
	*/
	Object getSession();

	/**
	* Get the list of offered WebSocket sub-protocols.
	*
	* @return the list of offered sub-protocols
	*/
	List<String> getSubProtocols();

	/**
	* Get the User Principal for this request.
	* <p>
	* Only applicable when using UpgradeRequest from server side.
	*
	* @return the user principal
	*/
	Principal getUserPrincipal();

	/**
	* Test if a specific sub-protocol is offered
	*
	* @param test the sub-protocol to test for
	* @return true if sub-protocol exists on request
	*/
	boolean hasSubProtocol(String test);

	/**
	* Test if supplied Origin is the same as the Request
	*
	* @param test the supplied origin
	* @return true if the supplied origin matches the request origin
	*/
	boolean isOrigin(String test);

	/**
	* Test if connection is secure.
	*
	* @return true if connection is secure.
	*/
	boolean isSecure();

	/**
	* Set the list of Cookies on the request
	*
	* @param cookies the cookies to use
	*/
	void setCookies(List<HttpCookie> cookies);

	/**
	* Set the list of WebSocket Extension configurations on the request.
	* @param configs the list of extension configurations
	*/
	void setExtensions(List<ExtensionConfig> configs);

	/**
	* Set a specific header with multi-value field
	* <p>
	* Overrides any previous value for this named header
	*
	* @param name the name of the header
	* @param values the multi-value field
	*/
	void setHeader(String name, List<String> values);

	/**
	* Set a specific header value
	* <p>
	* Overrides any previous value for this named header
	*
	* @param name the header to set
	* @param value the value to set it to
	*/
	void setHeader(String name, String value);

	/**
	* Sets multiple headers on the request.
	* <p>
	* Only sets those headers provided, does not remove
	* headers that exist on request and are not provided in the
	* parameter for this method.
	* <p>
	* Convenience method vs calling {@link #setHeader(String, List)} multiple times.
	*
	* @param headers the headers to set
	*/
	void setHeaders(Map<String, List<String>> headers);

	/**
	* Set the HTTP Version to use.
	* <p>
	* As of <a href="http://tools.ietf.org/html/rfc6455">RFC6455 (December 2011)</a> this should always be
	* <code>HTTP/1.1</code>
	*
	* @param httpVersion the HTTP version to use.
	*/
	void setHttpVersion(String httpVersion);

	/**
	* Set the HTTP method to use.
	* <p>
	* As of <a href="http://tools.ietf.org/html/rfc6455">RFC6455 (December 2011)</a> this is always <code>GET</code>
	*
	* @param method the HTTP method to use.
	*/
	void setMethod(String method);

	/**
	* Set the Request URI to use for this request.
	* <p>
	* Must be an absolute URI with scheme <code>'ws'</code> or <code>'wss'</code>
	*
	* @param uri the Request URI
	*/
	void setRequestURI(URI uri);

	/**
	* Set the Session associated with this request.
	* <p>
	* Typically used to associate the Servlet HttpSession object.
	*
	* @param session the session object to associate with this request
	*/
	void setSession(Object session);

	/**
	* Set the offered WebSocket Sub-Protocol list.
	*
	* @param protocols the offered sub-protocol list
	*/
	void setSubProtocols(List<String> protocols);

	/**
	* Set the offered WebSocket Sub-Protocol list.
	*
	* @param protocols the offered sub-protocol list
	*/
	void setSubProtocols(String... protocols);

	}