gdx/src/com/badlogic/gdx/Net.java

/*******************************************************************************
 * Copyright 2011 See AUTHORS file.
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *   http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 ******************************************************************************/

package com.badlogic.gdx;

import java.io.InputStream;
import java.io.OutputStream;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

import com.badlogic.gdx.Application.ApplicationType;
import com.badlogic.gdx.net.HttpRequestHeader;
import com.badlogic.gdx.net.HttpResponseHeader;
import com.badlogic.gdx.net.HttpStatus;
import com.badlogic.gdx.net.ServerSocket;
import com.badlogic.gdx.net.ServerSocketHints;
import com.badlogic.gdx.net.Socket;
import com.badlogic.gdx.net.SocketHints;
import com.badlogic.gdx.utils.GdxRuntimeException;
import com.badlogic.gdx.utils.Pool.Poolable;

/** Provides methods to perform networking operations, such as simple HTTP get and post requests, and TCP server/client socket
 * communication.</p>
 * 
 * To perform an HTTP request create a {@link HttpRequest} with the HTTP method (see {@link HttpMethods} for common methods) and
 * invoke {@link #sendHttpRequest(HttpRequest, HttpResponseListener)} with it and a {@link HttpResponseListener}. After the HTTP
 * request was processed, the {@link HttpResponseListener} is called with a {@link HttpResponse} with the HTTP response values and
 * an status code to determine if the request was successful or not.</p>
 * 
 * To create a TCP client socket to communicate with a remote TCP server, invoke the
 * {@link #newClientSocket(Protocol, String, int, SocketHints)} method. The returned {@link Socket} offers an {@link InputStream}
 * and {@link OutputStream} to communicate with the end point.</p>
 * 
 * To create a TCP server socket that waits for incoming connections, invoke the
 * {@link #newServerSocket(Protocol, int, ServerSocketHints)} method. The returned {@link ServerSocket} offers an
 * {@link ServerSocket#accept(SocketHints options)} method that waits for an incoming connection.
 * 
 * @author mzechner
 * @author noblemaster
 * @author arielsan */
public interface Net {

	/** HTTP response interface with methods to get the response data as a byte[], a {@link String} or an {@link InputStream}. */
	public static interface HttpResponse {
		/** Returns the data of the HTTP response as a byte[].
		 * <p>
		 * <b>Note</b>: This method may only be called once per response.
		 * </p>
		 * @return the result as a byte[] or null in case of a timeout or if the operation was canceled/terminated abnormally. The
		 *         timeout is specified when creating the HTTP request, with {@link HttpRequest#setTimeOut(int)} */
		byte[] getResult ();

		/** Returns the data of the HTTP response as a {@link String}.
		 * <p>
		 * <b>Note</b>: This method may only be called once per response.
		 * </p>
		 * @return the result as a string or null in case of a timeout or if the operation was canceled/terminated abnormally. The
		 *         timeout is specified when creating the HTTP request, with {@link HttpRequest#setTimeOut(int)} */
		String getResultAsString ();

		/** Returns the data of the HTTP response as an {@link InputStream}. <b><br>
		 * Warning:</b> Do not store a reference to this InputStream outside of
		 * {@link HttpResponseListener#handleHttpResponse(HttpResponse)}. The underlying HTTP connection will be closed after that
		 * callback finishes executing. Reading from the InputStream after it's connection has been closed will lead to exception.
		 * @return An {@link InputStream} with the {@link HttpResponse} data. */
		InputStream getResultAsStream ();

		/** Returns the {@link HttpStatus} containing the statusCode of the HTTP response. */
		HttpStatus getStatus ();

		/** Returns the value of the header with the given name as a {@link String}, or null if the header is not set. See
		 * {@link HttpResponseHeader}. */
		String getHeader (String name);

		/** Returns a Map of the headers. The keys are Strings that represent the header name. Each values is a List of Strings that
		 * represent the corresponding header values. See {@link HttpResponseHeader}. */
		Map<String, List<String>> getHeaders ();
	}

	/** Provides common HTTP methods to use when creating a {@link HttpRequest}.
	 * <ul>
	 * <li>GET</li>
	 * <li>POST</li>
	 * <li>PUT</li>
	 * <li>DELETE</li>
	 * </ul> */
	public static interface HttpMethods {

		public static final String GET = "GET";
		public static final String POST = "POST";
		public static final String PUT = "PUT";
		public static final String DELETE = "DELETE";

	}

	/** Contains getters and setters for the following parameters:
	 * <ul>
	 * <li><strong>httpMethod:</strong> GET or POST are most common, can use {@link Net.HttpMethods HttpMethods} for static
	 * references</li>
	 * <li><strong>url:</strong> the url</li>
	 * <li><strong>headers:</strong> a map of the headers, setter can be called multiple times</li>
	 * <li><strong>timeout:</strong> time spent trying to connect before giving up</li>
	 * <li><strong>content:</strong> A string containing the data to be used when processing the HTTP request.</li>
	 * </ul>
	 * 
	 * Abstracts the concept of a HTTP Request:
	 * 
	 * <pre>
	 * Map<String, String> parameters = new HashMap<String, String>();
	 * parameters.put("user", "myuser");
	 * 
	 * HttpRequest httpGet = new HttpRequest(HttpMethods.Get);
	 * httpGet.setUrl("http://somewhere.net");
	 * httpGet.setContent(HttpParametersUtils.convertHttpParameters(parameters));
	 * ...
	 * Gdx.net.sendHttpRequest (httpGet, new HttpResponseListener() {
	 * 	public void handleHttpResponse(HttpResponse httpResponse) {
	 * 		status = httpResponse.getResultAsString();
	 * 		//do stuff here based on response
	 * 	}
	 * 
	 * 	public void failed(Throwable t) {
	 * 		status = "failed";
	 * 		//do stuff here based on the failed attempt
	 * 	}
	 * });
	 * </pre> */
	public static class HttpRequest implements Poolable {

		private String httpMethod;
		private String url;
		private Map<String, String> headers;
		private int timeOut = 0;

		private String content;
		private InputStream contentStream;
		private long contentLength;

		private boolean followRedirects = true;

		private boolean includeCredentials = false;
		
		public HttpRequest () {
			this.headers = new HashMap<String, String>();
		}

		/** Creates a new HTTP request with the specified HTTP method, see {@link HttpMethods}.
		 * @param httpMethod This is the HTTP method for the request, see {@link HttpMethods} */
		public HttpRequest (String httpMethod) {
			this();
			this.httpMethod = httpMethod;
		}

		/** Sets the URL of the HTTP request.
		 * @param url The URL to set. */
		public void setUrl (String url) {
			this.url = url;
		}

		/** Sets a header to this HTTP request, see {@link HttpRequestHeader}.
		 * @param name the name of the header.
		 * @param value the value of the header. */
		public void setHeader (String name, String value) {
			headers.put(name, value);
		}

		/** Sets the content to be used in the HTTP request.
		 * @param content A string encoded in the corresponding Content-Encoding set in the headers, with the data to send with the
		 *           HTTP request. For example, in case of HTTP GET, the content is used as the query string of the GET while on a
		 *           HTTP POST it is used to send the POST data. */
		public void setContent (String content) {
			this.content = content;
		}

		/** Sets the content as a stream to be used for a POST for example, to transmit custom data.
		 * @param contentStream The stream with the content data. */
		public void setContent (InputStream contentStream, long contentLength) {
			this.contentStream = contentStream;
			this.contentLength = contentLength;
		}

		/** Sets the time to wait for the HTTP request to be processed, use 0 block until it is done. The timeout is used for both
		 * the timeout when establishing TCP connection, and the timeout until the first byte of data is received.
		 * @param timeOut the number of milliseconds to wait before giving up, 0 or negative to block until the operation is done */
		public void setTimeOut (int timeOut) {
			this.timeOut = timeOut;
		}

		/** Sets whether 301 and 302 redirects are followed. By default true. Can't be changed in the GWT backend because this uses
		 * XmlHttpRequests which always redirect.
		 * @param followRedirects whether to follow redirects.
		 * @exception IllegalArgumentException if redirection is disabled on the GWT backend. */
		public void setFollowRedirects (boolean followRedirects) throws IllegalArgumentException {
			if (followRedirects == true || Gdx.app.getType() != ApplicationType.WebGL) {
				this.followRedirects = followRedirects;
			} else {
				throw new IllegalArgumentException("Following redirects can't be disabled using the GWT/WebGL backend!");
			}
		}

		/** Sets whether a cross-origin request will include credentials. Only used on GWT backend to allow cross-origin requests
		 * to include credentials such as cookies, authorization headers, etc... */
		public void setIncludeCredentials (boolean includeCredentials) {
			this.includeCredentials = includeCredentials;
		}
		
		/** Sets the HTTP method of the HttpRequest. */
		public void setMethod (String httpMethod) {
			this.httpMethod = httpMethod;
		}

		/** Returns the timeOut of the HTTP request.
		 * @return the timeOut. */
		public int getTimeOut () {
			return timeOut;
		}

		/** Returns the HTTP method of the HttpRequest. */
		public String getMethod () {
			return httpMethod;
		}

		/** Returns the URL of the HTTP request. */
		public String getUrl () {
			return url;
		}

		/** Returns the content string to be used for the HTTP request. */
		public String getContent () {
			return content;
		}

		/** Returns the content stream. */
		public InputStream getContentStream () {
			return contentStream;
		}

		/** Returns the content length in case content is a stream. */
		public long getContentLength () {
			return contentLength;
		}

		/** Returns a Map<String, String> with the headers of the HTTP request. */
		public Map<String, String> getHeaders () {
			return headers;
		}

		/** Returns whether 301 and 302 redirects are followed. By default true. Whether to follow redirects. */
		public boolean getFollowRedirects () {
			return followRedirects;
		}
		
		/** Returns whether a cross-origin request will include credentials. By default false. */
		public boolean getIncludeCredentials () {
			return includeCredentials;
		}

		@Override
		public void reset () {
			httpMethod = null;
			url = null;
			headers.clear();
			timeOut = 0;

			content = null;
			contentStream = null;
			contentLength = 0;

			followRedirects = true;
		}

	}

	/** Listener to be able to do custom logic once the {@link HttpResponse} is ready to be processed, register it with
	 * {@link Net#sendHttpRequest(HttpRequest, HttpResponseListener)}. */
	public static interface HttpResponseListener {

		/** Called when the {@link HttpRequest} has been processed and there is a {@link HttpResponse} ready. Passing data to the
		 * rendering thread should be done using {@link Application#postRunnable(java.lang.Runnable runnable)} {@link HttpResponse}
		 * contains the {@link HttpStatus} and should be used to determine if the request was successful or not (see more info at
		 * {@link HttpStatus#getStatusCode()}). For example:
		 * 
		 * <pre>
		 *  HttpResponseListener listener = new HttpResponseListener() {
		 *  	public void handleHttpResponse (HttpResponse httpResponse) {
		 *  		HttpStatus status = httpResponse.getStatus();
		 *  		if (status.getStatusCode() >= 200 && status.getStatusCode() < 300) {
		 *  			// it was successful
		 *  		} else {
		 *  			// do something else
		 *  		}
		 *  	}
		 *  }
		 * </pre>
		 * 
		 * @param httpResponse The {@link HttpResponse} with the HTTP response values. */
		void handleHttpResponse (HttpResponse httpResponse);

		/** Called if the {@link HttpRequest} failed because an exception when processing the HTTP request, could be a timeout any
		 * other reason (not an HTTP error).
		 * @param t If the HTTP request failed because an Exception, t encapsulates it to give more information. */
		void failed (Throwable t);

		void cancelled ();
	}

	/** Process the specified {@link HttpRequest} and reports the {@link HttpResponse} to the specified {@link HttpResponseListener}
	 * .
	 * @param httpRequest The {@link HttpRequest} to be performed.
	 * @param httpResponseListener The {@link HttpResponseListener} to call once the HTTP response is ready to be processed. Could
	 *           be null, in that case no listener is called. */
	public void sendHttpRequest (HttpRequest httpRequest, HttpResponseListener httpResponseListener);

	public void cancelHttpRequest (HttpRequest httpRequest);

	/** Protocol used by {@link Net#newServerSocket(Protocol, int, ServerSocketHints)} and
	 * {@link Net#newClientSocket(Protocol, String, int, SocketHints)}.
	 * @author mzechner */
	public enum Protocol {
		TCP
	}
	
	/** Creates a new server socket on the given address and port, using the given {@link Protocol}, waiting for incoming connections.
	 * 
	 * @param hostname the hostname or ip address to bind the socket to
	 * @param port the port to listen on
	 * @param hints additional {@link ServerSocketHints} used to create the socket. Input null to use the default setting provided
	 *           by the system.
	 * @return the {@link ServerSocket}
	 * @throws GdxRuntimeException in case the socket couldn't be opened */
	public ServerSocket newServerSocket (Protocol protocol, String hostname, int port, ServerSocketHints hints);

	/** Creates a new server socket on the given port, using the given {@link Protocol}, waiting for incoming connections.
	 * 
	 * @param port the port to listen on
	 * @param hints additional {@link ServerSocketHints} used to create the socket. Input null to use the default setting provided
	 *           by the system.
	 * @return the {@link ServerSocket}
	 * @throws GdxRuntimeException in case the socket couldn't be opened */
	public ServerSocket newServerSocket (Protocol protocol, int port, ServerSocketHints hints);

	/** Creates a new TCP client socket that connects to the given host and port.
	 * 
	 * @param host the host address
	 * @param port the port
	 * @param hints additional {@link SocketHints} used to create the socket. Input null to use the default setting provided by the
	 *           system.
	 * @return GdxRuntimeException in case the socket couldn't be opened */
	public Socket newClientSocket (Protocol protocol, String host, int port, SocketHints hints);

	/** Launches the default browser to display a URI. If the default browser is not able to handle the specified URI, the
	 * application registered for handling URIs of the specified type is invoked. The application is determined from the protocol
	 * and path of the URI. A best effort is made to open the given URI; however, since external applications are involved, no guarantee
	 * can be made as to whether the URI was actually opened. If it is known that the URI was not opened, false will be returned; 
	 * otherwise, true will be returned.
	 * 
	 * @param URI the URI to be opened.
	 * @return false if it is known the uri was not opened, true otherwise. */
	public boolean openURI (String URI);
}