Network Android

 * To get a new Connection, use {@link org.jsoup.Jsoup#connect(String)}.
 * Connections contain {@link Connection.Request} and
 * {@link Connection.Response} objects. The request objects are reusable as
 * prototype requests.
 * 

 * Request configuration can be made using either the shortcut methods in
 * Connection (e.g. {@link #userAgent(String)}), or by methods in the
 * Connection.Request object directly. All request configuration must be made
 * before the request is executed.
 * 

 * The Connection interface is currently in beta and subject to change.
 * Comments, suggestions, and bug reports are welcome.
 */
interface Connection {
  /**
   * GET and POST http methods.
   */
  public enum Method {
    GET, POST
  }
  /**
   * Set the request URL to fetch. The protocol must be HTTP or HTTPS.
   * 
   * @param url
   *            URL to connect to
   * @return this Connection, for chaining
   */
  public Connection url(URL url);
  /**
   * Set the request URL to fetch. The protocol must be HTTP or HTTPS.
   * 
   * @param url
   *            URL to connect to
   * @return this Connection, for chaining
   */
  public Connection url(String url);
  /**
   * Set the request user-agent header.
   * 
   * @param userAgent
   *            user-agent to use
   * @return this Connection, for chaining
   */
  public Connection userAgent(String userAgent);
  /**
   * Set the request timeouts (connect and read). If a timeout occurs, an
   * IOException will be thrown. The default timeout is 3 seconds (3000
   * millis). A timeout of zero is treated as an infinite timeout.
   * 
   * @param millis
   *            number of milliseconds (thousandths of a second) before timing
   *            out connects or reads.
   * @return this Connection, for chaining
   */
  public Connection timeout(int millis);
  /**
   * Set the request referrer (aka "referer") header.
   * 
   * @param referrer
   *            referrer to use
   * @return this Connection, for chaining
   */
  public Connection referrer(String referrer);
  /**
   * Configures the connection to (not) follow server redirects. By default
   * this is true.
   * 
   * @param followRedirects
   *            true if server redirects should be followed.
   * @return this Connection, for chaining
   */
  public Connection followRedirects(boolean followRedirects);
  /**
   * Set the request method to use, GET or POST. Default is GET.
   * 
   * @param method
   *            HTTP request method
   * @return this Connection, for chaining
   */
  public Connection method(Method method);
  /**
   * Add a request data parameter. Request parameters are sent in the request
   * query string for GETs, and in the request body for POSTs. A request may
   * have multiple values of the same name.
   * 
   * @param key
   *            data key
   * @param value
   *            data value
   * @return this Connection, for chaining
   */
  public Connection data(String key, String value);
  /**
   * Adds all of the supplied data to the request data parameters
   * 
   * @param data
   *            map of data parameters
   * @return this Connection, for chaining
   */
  public Connection data(Map data);
  /**
   * Add a number of request data parameters. Multiple parameters may be set
   * at once, e.g.:
   * .data("name", "jsoup", "language", "Java", "language", "English");
   * creates a query string like:
   * ?name=jsoup&language=Java&language=English
   * 
   * @param keyvals
   *            a set of key value pairs.
   * @return this Connection, for chaining
   */
  public Connection data(String... keyvals);
  /**
   * Set a request header.
   * 
   * @param name
   *            header name
   * @param value
   *            header value
   * @return this Connection, for chaining
   * @see org.jsoup.Connection.Request#headers()
   */
  public Connection header(String name, String value);
  /**
   * Set a cookie to be sent in the request
   * 
   * @param name
   *            name of cookie
   * @param value
   *            value of cookie
   * @return this Connection, for chaining
   */
  public Connection cookie(String name, String value);
  /**
   * Execute the request.
   * 
   * @return a response object
   * @throws IOException
   *             on error
   */
  public Response execute() throws IOException;
  /**
   * Get the request object associatated with this connection
   * 
   * @return request
   */
  public Request request();
  /**
   * Set the connection's request
   * 
   * @param request
   *            new request object
   * @return this Connection, for chaining
   */
  public Connection request(Request request);
  /**
   * Get the response, once the request has been executed
   * 
   * @return response
   */
  public Response response();
  /**
   * Set the conenction's response
   * 
   * @param response
   *            new response
   * @return this Connection, for chaining
   */
  public Connection response(Response response);
  /**
   * Common methods for Requests and Responses
   * 
   * @param 
   *            Type of Base, either Request or Response
   */
  interface Base {
    /**
     * Get the URL
     * 
     * @return URL
     */
    public URL url();
    /**
     * Set the URL
     * 
     * @param url
     *            new URL
     * @return this, for chaining
     */
    public T url(URL url);
    /**
     * Get the request method
     * 
     * @return method
     */
    public Method method();
    /**
     * Set the request method
     * 
     * @param method
     *            new method
     * @return this, for chaining
     */
    public T method(Method method);
    /**
     * Get the value of a header. This is a simplified header model, where a
     * header may only have one value.
     * 

     * Header names are case insensitive.
     * 
     * @param name
     *            name of header (case insensitive)
     * @return value of header, or null if not set.
     * @see #hasHeader(String)
     * @see #cookie(String)
     */
    public String header(String name);
    /**
     * Set a header. This method will overwrite any existing header with the
     * same case insensitive name.
     * 
     * @param name
     *            Name of header
     * @param value
     *            Value of header
     * @return this, for chaining
     */
    public T header(String name, String value);
    /**
     * Check if a header is present
     * 
     * @param name
     *            name of header (case insensitive)
     * @return if the header is present in this request/response
     */
    public boolean hasHeader(String name);
    /**
     * Remove a header by name
     * 
     * @param name
     *            name of header to remove (case insensitive)
     * @return this, for chianing
     */
    public T removeHeader(String name);
    /**
     * Retrieve all of the request/response headers as a map
     * 
     * @return headers
     */
    public Map headers();
    /**
     * Get a cookie value by name from this request/response.
     * 

     * Response objects have a simplified cookie model. Each cookie set in
     * the response is added to the response object's cookie key=value map.
     * The cookie's path, domain, and expiry date are ignored.
     * 
     * @param name
     *            name of cookie to retrieve.
     * @return value of cookie, or null if not set
     */
    public String cookie(String name);
    /**
     * Set a cookie in this request/response.
     * 
     * @param name
     *            name of cookie
     * @param value
     *            value of cookie
     * @return this, for chianing
     */
    public T cookie(String name, String value);
    /**
     * Check if a cookie is present
     * 
     * @param name
     *            name of cookie
     * @return if the cookie is present in this request/response
     */
    public boolean hasCookie(String name);
    /**
     * Remove a cookie by name
     * 
     * @param name
     *            name of cookie to remove
     * @return this, for chianing
     */
    public T removeCookie(String name);
    /**
     * Retrieve all of the request/response cookies as a map
     * 
     * @return cookies
     */
    public Map cookies();
  }
  /**
   * Represents a HTTP request.
   */
  public interface Request extends Base {
    /**
     * Get the request timeout, in milliseconds.
     * 
     * @return the timeout in milliseconds.
     */
    public int timeout();
    /**
     * Update the request timeout.
     * 
     * @param millis
     *            timeout, in milliseconds
     * @return this Request, for chaining
     */
    public Request timeout(int millis);
    /**
     * Get the current followRedirects configuration.
     * 
     * @return true if followRedirects is enabled.
     */
    public boolean followRedirects();
    /**
     * Configures the request to (not) follow server redirects. By default
     * this is true.
     * 
     * @param followRedirects
     *            true if server redirects should be followed.
     * @return this Connection, for chaining
     */
    public Request followRedirects(boolean followRedirects);
    /**
     * Add a data parameter to the request
     * 
     * @param keyval
     *            data to add.
     * @return this Request, for chaining
     */
    public Request data(KeyVal keyval);
    /**
     * Get all of the request's data parameters
     * 
     * @return collection of keyvals
     */
    public Collection data();
  }
  /**
   * Represents a HTTP response.
   */
  public interface Response extends Base {
    /**
     * Get the status code of the response.
     * 
     * @return status code
     */
    public int statusCode();
    /**
     * Get the status message of the response.
     * 
     * @return status message
     */
    public String statusMessage();
    /**
     * Get the character set name of the response.
     * 
     * @return character set name
     */
    public String charset();
    /**
     * Get the response content type (e.g. "text/html");
     * 
     * @return the response content type
     */
    public String contentType();
    /**
     * Get the body of the response as a plain string.
     * 
     * @return body
     */
    public String body();
    /**
     * Get the body of the response as an array of bytes.
     * 
     * @return body bytes
     */
    public byte[] bodyAsBytes();
  }
  /**
   * A Key Value tuple.
   */
  public interface KeyVal {
    /**
     * Update the key of a keyval
     * 
     * @param key
     *            new key
     * @return this KeyVal, for chaining
     */
    public KeyVal key(String key);
    /**
     * Get the key of a keyval
     * 
     * @return the key
     */
    public String key();
    /**
     * Update the value of a keyval
     * 
     * @param value
     *            the new value
     * @return this KeyVal, for chaining
     */
    public KeyVal value(String value);
    /**
     * Get the value of a keyval
     * 
     * @return the value
     */
    public String value();
  }
}
final class Validate {
  private Validate() {
  }
  /**
   * Validates that the obect is not null
   * 
   * @param obj
   *            object to test
   */
  public static void notNull(Object obj) {
    if (obj == null)
      throw new IllegalArgumentException("Object must not be null");
  }
  /**
   * Validates that the object is not null
   * 
   * @param obj
   *            object to test
   * @param msg
   *            message to output if validation fails
   */
  public static void notNull(Object obj, String msg) {
    if (obj == null)
      throw new IllegalArgumentException(msg);
  }
  /**
   * Validates that the value is true
   * 
   * @param val
   *            object to test
   */
  public static void isTrue(boolean val) {
    if (!val)
      throw new IllegalArgumentException("Must be true");
  }
  /**
   * Validates that the value is true
   * 
   * @param val
   *            object to test
   * @param msg
   *            message to output if validation fails
   */
  public static void isTrue(boolean val, String msg) {
    if (!val)
      throw new IllegalArgumentException(msg);
  }
  /**
   * Validates that the array contains no null elements
   * 
   * @param objects
   *            the array to test
   */
  public static void noNullElements(Object[] objects) {
    noNullElements(objects, "Array must not contain any null objects");
  }
  /**
   * Validates that the array contains no null elements
   * 
   * @param objects
   *            the array to test
   * @param msg
   *            message to output if validation fails
   */
  public static void noNullElements(Object[] objects, String msg) {
    for (Object obj : objects)
      if (obj == null)
        throw new IllegalArgumentException(msg);
  }
  /**
   * Validates that the string is not empty
   * 
   * @param string
   *            the string to test
   */
  public static void notEmpty(String string) {
    if (string == null || string.length() == 0)
      throw new IllegalArgumentException("String must not be empty");
  }
  /**
   * Validates that the string is not empty
   * 
   * @param string
   *            the string to test
   * @param msg
   *            message to output if validation fails
   */
  public static void notEmpty(String string, String msg) {
    if (string == null || string.length() == 0)
      throw new IllegalArgumentException(msg);
  }
}
/**
 * Internal static utilities for handling data.
 * 
 */
class DataUtil {
  private static final Pattern charsetPattern = Pattern
      .compile("(?i)\\bcharset=\\s*\"?([^\\s;\"]*)");
  static final String defaultCharset = "UTF-8"; // used if not found in header
                          // or meta charset
  private static final int bufferSize = 0x20000; // ~130K.
  private DataUtil() {
  }
  /**
   * Loads a file to a Document.
   * 
   * @param in
   *            file to load
   * @param charsetName
   *            character set of input
   * @param baseUri
   *            base URI of document, to resolve relative links against
   * @return Document
   * @throws IOException
   *             on IO error
   */
  static ByteBuffer readToByteBuffer(InputStream inStream) throws IOException {
    byte[] buffer = new byte[bufferSize];
    ByteArrayOutputStream outStream = new ByteArrayOutputStream(bufferSize);
    int read;
    while (true) {
      read = inStream.read(buffer);
      if (read == -1)
        break;
      outStream.write(buffer, 0, read);
    }
    ByteBuffer byteData = ByteBuffer.wrap(outStream.toByteArray());
    return byteData;
  }
  /**
   * Parse out a charset from a content type header.
   * 
   * @param contentType
   *            e.g. "text/html; charset=EUC-JP"
   * @return "EUC-JP", or null if not found. Charset is trimmed and
   *         uppercased.
   */
  static String getCharsetFromContentType(String contentType) {
    if (contentType == null)
      return null;
    Matcher m = charsetPattern.matcher(contentType);
    if (m.find()) {
      return m.group(1).trim().toUpperCase();
    }
    return null;
  }
}
/**
 * A character queue with parsing helpers.
 *
 * @author Jonathan Hedley
 */
class TokenQueue {
    private String queue;
    private int pos = 0;
    
    private static final char ESC = '\\'; // escape char for chomp balanced.
    /**
     Create a new TokenQueue.
     @param data string of data to back queue.
     */
    public TokenQueue(String data) {
        Validate.notNull(data);
        queue = data;
    }
    /**
     * Is the queue empty?
     * @return true if no data left in queue.
     */
    public boolean isEmpty() {
        return remainingLength() == 0;
    }
    
    private int remainingLength() {
        return queue.length() - pos;
    }
    /**
     * Retrieves but does not remove the first character from the queue.
     * @return First character, or 0 if empty.
     */
    public char peek() {
        return isEmpty() ? 0 : queue.charAt(pos);
    }
    /**
     Add a character to the start of the queue (will be the next character retrieved).
     @param c character to add
     */
    public void addFirst(Character c) {
        addFirst(c.toString());
    }
    /**
     Add a string to the start of the queue.
     @param seq string to add.
     */
    public void addFirst(String seq) {
        // not very performant, but an edge case
        queue = seq + queue.substring(pos);
        pos = 0;
    }
    /**
     * Tests if the next characters on the queue match the sequence. Case insensitive.
     * @param seq String to check queue for.
     * @return true if the next characters match.
     */
    public boolean matches(String seq) {
        return queue.regionMatches(true, pos, seq, 0, seq.length());
    }
    /**
     * Case sensitive match test.
     * @param seq
     * @return
     */
    public boolean matchesCS(String seq) {
        return queue.startsWith(seq, pos);
    }
    
    /**
     Tests if the next characters match any of the sequences. Case insensitive.
     @param seq
     @return
     */
    public boolean matchesAny(String... seq) {
        for (String s : seq) {
            if (matches(s))
                return true;
        }
        return false;
    }
    public boolean matchesAny(char... seq) {
        if (isEmpty())
            return false;
        for (char c: seq) {
            if (queue.charAt(pos) == c)
                return true;
        }
        return false;
    }
    public boolean matchesStartTag() {
        // micro opt for matching "        return (remainingLength() >= 2 && queue.charAt(pos) == '<' && Character.isLetter(queue.charAt(pos+1)));
    }
    /**
     * Tests if the queue matches the sequence (as with match), and if they do, removes the matched string from the
     * queue.
     * @param seq String to search for, and if found, remove from queue.
     * @return true if found and removed, false if not found.
     */
    public boolean matchChomp(String seq) {
        if (matches(seq)) {
            pos += seq.length();
            return true;
        } else {
            return false;
        }
    }
    /**
     Tests if queue starts with a whitespace character.
     @return if starts with whitespace
     */
    public boolean matchesWhitespace() {
        return !isEmpty() && Character.isWhitespace(queue.charAt(pos));
    }
    /**
     Test if the queue matches a word character (letter or digit).
     @return if matches a word character
     */
    public boolean matchesWord() {
        return !isEmpty() && Character.isLetterOrDigit(queue.charAt(pos));
    }
    /**
     * Drops the next character off the queue.
     */
    public void advance() {
        if (!isEmpty()) pos++;
    }
    /**
     * Consume one character off queue.
     * @return first character on queue.
     */
    public char consume() {
        return queue.charAt(pos++);
    }
    /**
     * Consumes the supplied sequence of the queue. If the queue does not start with the supplied sequence, will
     * throw an illegal state exception -- but you should be running match() against that condition.
     

     Case insensitive.
     * @param seq sequence to remove from head of queue.
     */
    public void consume(String seq) {
        if (!matches(seq))
            throw new IllegalStateException("Queue did not match expected sequence");
        int len = seq.length();
        if (len > remainingLength())
            throw new IllegalStateException("Queue not long enough to consume sequence");
        
        pos += len;
    }
    /**
     * Pulls a string off the queue, up to but exclusive of the match sequence, or to the queue running out.
     * @param seq String to end on (and not include in return, but leave on queue). Case sensitive.
     * @return The matched data consumed from queue.
     */
    public String consumeTo(String seq) {
        int offset = queue.indexOf(seq, pos);
        if (offset != -1) {
            String consumed = queue.substring(pos, offset);
            pos += consumed.length();
            return consumed;
        } else {
            return remainder();
        }
    }
    
    public String consumeToIgnoreCase(String seq) {
        int start = pos;
        String first = seq.substring(0, 1);
        boolean canScan = first.toLowerCase().equals(first.toUpperCase()); // if first is not cased, use index of
        while (!isEmpty()) {
            if (matches(seq))
                break;
            
            if (canScan) {
                int skip = queue.indexOf(first, pos) - pos;
                if (skip == 0) // this char is the skip char, but not match, so force advance of pos
                    pos++;
                else if (skip < 0) // no chance of finding, grab to end
                    pos = queue.length();
                else
                    pos += skip;
            }
            else
                pos++;
        }
        String data = queue.substring(start, pos); 
        return data; 
    }
    /**
     Consumes to the first sequence provided, or to the end of the queue. Leaves the terminator on the queue.
     @param seq any number of terminators to consume to. Case insensitive.
     @return consumed string   
     */
    // todo: method name. not good that consumeTo cares for case, and consume to any doesn't. And the only use for this
    // is is a case sensitive time...
    public String consumeToAny(String... seq) {
        int start = pos;
        while (!isEmpty() && !matchesAny(seq)) {
            pos++;
        }
        String data = queue.substring(start, pos); 
        return data; 
    }
    /**
     * Pulls a string off the queue (like consumeTo), and then pulls off the matched string (but does not return it).
     *