| /* |
| * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/message/BasicTokenIterator.java $ |
| * $Revision: 602520 $ |
| * $Date: 2007-12-08 09:42:26 -0800 (Sat, 08 Dec 2007) $ |
| * |
| * ==================================================================== |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you 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. |
| * ==================================================================== |
| * |
| * This software consists of voluntary contributions made by many |
| * individuals on behalf of the Apache Software Foundation. For more |
| * information on the Apache Software Foundation, please see |
| * <http://www.apache.org/>. |
| * |
| */ |
| |
| package org.apache.http.message; |
| |
| import java.util.NoSuchElementException; |
| |
| import org.apache.http.HeaderIterator; |
| import org.apache.http.ParseException; |
| import org.apache.http.TokenIterator; |
| |
| /** |
| * Basic implementation of a {@link TokenIterator}. |
| * This implementation parses <tt>#token<tt> sequences as |
| * defined by RFC 2616, section 2. |
| * It extends that definition somewhat beyond US-ASCII. |
| * |
| * @version $Revision: 602520 $ |
| * |
| * @deprecated Please use {@link java.net.URL#openConnection} instead. |
| * Please visit <a href="http://android-developers.blogspot.com/2011/09/androids-http-clients.html">this webpage</a> |
| * for further details. |
| */ |
| @Deprecated |
| public class BasicTokenIterator implements TokenIterator { |
| |
| /** The HTTP separator characters. Defined in RFC 2616, section 2.2. */ |
| // the order of the characters here is adjusted to put the |
| // most likely candidates at the beginning of the collection |
| public final static String HTTP_SEPARATORS = " ,;=()<>@:\\\"/[]?{}\t"; |
| |
| |
| /** The iterator from which to obtain the next header. */ |
| protected final HeaderIterator headerIt; |
| |
| /** |
| * The value of the current header. |
| * This is the header value that includes {@link #currentToken}. |
| * Undefined if the iteration is over. |
| */ |
| protected String currentHeader; |
| |
| /** |
| * The token to be returned by the next call to {@link #currentToken}. |
| * <code>null</code> if the iteration is over. |
| */ |
| protected String currentToken; |
| |
| /** |
| * The position after {@link #currentToken} in {@link #currentHeader}. |
| * Undefined if the iteration is over. |
| */ |
| protected int searchPos; |
| |
| |
| /** |
| * Creates a new instance of {@link BasicTokenIterator}. |
| * |
| * @param headerIterator the iterator for the headers to tokenize |
| */ |
| public BasicTokenIterator(final HeaderIterator headerIterator) { |
| if (headerIterator == null) { |
| throw new IllegalArgumentException |
| ("Header iterator must not be null."); |
| } |
| |
| this.headerIt = headerIterator; |
| this.searchPos = findNext(-1); |
| } |
| |
| |
| // non-javadoc, see interface TokenIterator |
| public boolean hasNext() { |
| return (this.currentToken != null); |
| } |
| |
| |
| /** |
| * Obtains the next token from this iteration. |
| * |
| * @return the next token in this iteration |
| * |
| * @throws NoSuchElementException if the iteration is already over |
| * @throws ParseException if an invalid header value is encountered |
| */ |
| public String nextToken() |
| throws NoSuchElementException, ParseException { |
| |
| if (this.currentToken == null) { |
| throw new NoSuchElementException("Iteration already finished."); |
| } |
| |
| final String result = this.currentToken; |
| // updates currentToken, may trigger ParseException: |
| this.searchPos = findNext(this.searchPos); |
| |
| return result; |
| } |
| |
| |
| /** |
| * Returns the next token. |
| * Same as {@link #nextToken}, but with generic return type. |
| * |
| * @return the next token in this iteration |
| * |
| * @throws NoSuchElementException if there are no more tokens |
| * @throws ParseException if an invalid header value is encountered |
| */ |
| public final Object next() |
| throws NoSuchElementException, ParseException { |
| return nextToken(); |
| } |
| |
| |
| /** |
| * Removing tokens is not supported. |
| * |
| * @throws UnsupportedOperationException always |
| */ |
| public final void remove() |
| throws UnsupportedOperationException { |
| |
| throw new UnsupportedOperationException |
| ("Removing tokens is not supported."); |
| } |
| |
| |
| /** |
| * Determines the next token. |
| * If found, the token is stored in {@link #currentToken}. |
| * The return value indicates the position after the token |
| * in {@link #currentHeader}. If necessary, the next header |
| * will be obtained from {@link #headerIt}. |
| * If not found, {@link #currentToken} is set to <code>null</code>. |
| * |
| * @param from the position in the current header at which to |
| * start the search, -1 to search in the first header |
| * |
| * @return the position after the found token in the current header, or |
| * negative if there was no next token |
| * |
| * @throws ParseException if an invalid header value is encountered |
| */ |
| protected int findNext(int from) |
| throws ParseException { |
| |
| if (from < 0) { |
| // called from the constructor, initialize the first header |
| if (!this.headerIt.hasNext()) { |
| return -1; |
| } |
| this.currentHeader = this.headerIt.nextHeader().getValue(); |
| from = 0; |
| } else { |
| // called after a token, make sure there is a separator |
| from = findTokenSeparator(from); |
| } |
| |
| int start = findTokenStart(from); |
| if (start < 0) { |
| this.currentToken = null; |
| return -1; // nothing found |
| } |
| |
| int end = findTokenEnd(start); |
| this.currentToken = createToken(this.currentHeader, start, end); |
| return end; |
| } |
| |
| |
| /** |
| * Creates a new token to be returned. |
| * Called from {@link #findNext findNext} after the token is identified. |
| * The default implementation simply calls |
| * {@link java.lang.String#substring String.substring}. |
| * <br/> |
| * If header values are significantly longer than tokens, and some |
| * tokens are permanently referenced by the application, there can |
| * be problems with garbage collection. A substring will hold a |
| * reference to the full characters of the original string and |
| * therefore occupies more memory than might be expected. |
| * To avoid this, override this method and create a new string |
| * instead of a substring. |
| * |
| * @param value the full header value from which to create a token |
| * @param start the index of the first token character |
| * @param end the index after the last token character |
| * |
| * @return a string representing the token identified by the arguments |
| */ |
| protected String createToken(String value, int start, int end) { |
| return value.substring(start, end); |
| } |
| |
| |
| /** |
| * Determines the starting position of the next token. |
| * This method will iterate over headers if necessary. |
| * |
| * @param from the position in the current header at which to |
| * start the search |
| * |
| * @return the position of the token start in the current header, |
| * negative if no token start could be found |
| */ |
| protected int findTokenStart(int from) { |
| if (from < 0) { |
| throw new IllegalArgumentException |
| ("Search position must not be negative: " + from); |
| } |
| |
| boolean found = false; |
| while (!found && (this.currentHeader != null)) { |
| |
| final int to = this.currentHeader.length(); |
| while (!found && (from < to)) { |
| |
| final char ch = this.currentHeader.charAt(from); |
| if (isTokenSeparator(ch) || isWhitespace(ch)) { |
| // whitspace and token separators are skipped |
| from++; |
| } else if (isTokenChar(this.currentHeader.charAt(from))) { |
| // found the start of a token |
| found = true; |
| } else { |
| throw new ParseException |
| ("Invalid character before token (pos " + from + |
| "): " + this.currentHeader); |
| } |
| } |
| if (!found) { |
| if (this.headerIt.hasNext()) { |
| this.currentHeader = this.headerIt.nextHeader().getValue(); |
| from = 0; |
| } else { |
| this.currentHeader = null; |
| } |
| } |
| } // while headers |
| |
| return found ? from : -1; |
| } |
| |
| |
| /** |
| * Determines the position of the next token separator. |
| * Because of multi-header joining rules, the end of a |
| * header value is a token separator. This method does |
| * therefore not need to iterate over headers. |
| * |
| * @param from the position in the current header at which to |
| * start the search |
| * |
| * @return the position of a token separator in the current header, |
| * or at the end |
| * |
| * @throws ParseException |
| * if a new token is found before a token separator. |
| * RFC 2616, section 2.1 explicitly requires a comma between |
| * tokens for <tt>#</tt>. |
| */ |
| protected int findTokenSeparator(int from) { |
| if (from < 0) { |
| throw new IllegalArgumentException |
| ("Search position must not be negative: " + from); |
| } |
| |
| boolean found = false; |
| final int to = this.currentHeader.length(); |
| while (!found && (from < to)) { |
| final char ch = this.currentHeader.charAt(from); |
| if (isTokenSeparator(ch)) { |
| found = true; |
| } else if (isWhitespace(ch)) { |
| from++; |
| } else if (isTokenChar(ch)) { |
| throw new ParseException |
| ("Tokens without separator (pos " + from + |
| "): " + this.currentHeader); |
| } else { |
| throw new ParseException |
| ("Invalid character after token (pos " + from + |
| "): " + this.currentHeader); |
| } |
| } |
| |
| return from; |
| } |
| |
| |
| /** |
| * Determines the ending position of the current token. |
| * This method will not leave the current header value, |
| * since the end of the header value is a token boundary. |
| * |
| * @param from the position of the first character of the token |
| * |
| * @return the position after the last character of the token. |
| * The behavior is undefined if <code>from</code> does not |
| * point to a token character in the current header value. |
| */ |
| protected int findTokenEnd(int from) { |
| if (from < 0) { |
| throw new IllegalArgumentException |
| ("Token start position must not be negative: " + from); |
| } |
| |
| final int to = this.currentHeader.length(); |
| int end = from+1; |
| while ((end < to) && isTokenChar(this.currentHeader.charAt(end))) { |
| end++; |
| } |
| |
| return end; |
| } |
| |
| |
| /** |
| * Checks whether a character is a token separator. |
| * RFC 2616, section 2.1 defines comma as the separator for |
| * <tt>#token</tt> sequences. The end of a header value will |
| * also separate tokens, but that is not a character check. |
| * |
| * @param ch the character to check |
| * |
| * @return <code>true</code> if the character is a token separator, |
| * <code>false</code> otherwise |
| */ |
| protected boolean isTokenSeparator(char ch) { |
| return (ch == ','); |
| } |
| |
| |
| /** |
| * Checks whether a character is a whitespace character. |
| * RFC 2616, section 2.2 defines space and horizontal tab as whitespace. |
| * The optional preceeding line break is irrelevant, since header |
| * continuation is handled transparently when parsing messages. |
| * |
| * @param ch the character to check |
| * |
| * @return <code>true</code> if the character is whitespace, |
| * <code>false</code> otherwise |
| */ |
| protected boolean isWhitespace(char ch) { |
| |
| // we do not use Character.isWhitspace(ch) here, since that allows |
| // many control characters which are not whitespace as per RFC 2616 |
| return ((ch == '\t') || Character.isSpaceChar(ch)); |
| } |
| |
| |
| /** |
| * Checks whether a character is a valid token character. |
| * Whitespace, control characters, and HTTP separators are not |
| * valid token characters. The HTTP specification (RFC 2616, section 2.2) |
| * defines tokens only for the US-ASCII character set, this |
| * method extends the definition to other character sets. |
| * |
| * @param ch the character to check |
| * |
| * @return <code>true</code> if the character is a valid token start, |
| * <code>false</code> otherwise |
| */ |
| protected boolean isTokenChar(char ch) { |
| |
| // common sense extension of ALPHA + DIGIT |
| if (Character.isLetterOrDigit(ch)) |
| return true; |
| |
| // common sense extension of CTL |
| if (Character.isISOControl(ch)) |
| return false; |
| |
| // no common sense extension for this |
| if (isHttpSeparator(ch)) |
| return false; |
| |
| // RFC 2616, section 2.2 defines a token character as |
| // "any CHAR except CTLs or separators". The controls |
| // and separators are included in the checks above. |
| // This will yield unexpected results for Unicode format characters. |
| // If that is a problem, overwrite isHttpSeparator(char) to filter |
| // out the false positives. |
| return true; |
| } |
| |
| |
| /** |
| * Checks whether a character is an HTTP separator. |
| * The implementation in this class checks only for the HTTP separators |
| * defined in RFC 2616, section 2.2. If you need to detect other |
| * separators beyond the US-ASCII character set, override this method. |
| * |
| * @param ch the character to check |
| * |
| * @return <code>true</code> if the character is an HTTP separator |
| */ |
| protected boolean isHttpSeparator(char ch) { |
| return (HTTP_SEPARATORS.indexOf(ch) >= 0); |
| } |
| |
| |
| } // class BasicTokenIterator |
| |
