/* * 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. */ package java.net; import java.io.IOException; import java.io.InputStream; import java.io.OutputStream; import java.util.Collections; import java.util.Date; import java.util.Hashtable; import java.util.List; import java.util.Locale; import java.util.Map; /** * A connection to a URL for reading or writing. For HTTP connections, see * {@link HttpURLConnection} for documentation of HTTP-specific features. * *

For example, to retrieve {@code * ftp://mirror.csclub.uwaterloo.ca/index.html}:

   {@code
 *   URL url = new URL("ftp://mirror.csclub.uwaterloo.ca/index.html");
 *   URLConnection urlConnection = url.openConnection();
 *   InputStream in = new BufferedInputStream(urlConnection.getInputStream());
 *   try {
 *     readStream(in);
 *   } finally {
 *     in.close();
 *   }
 * }
* *

{@code URLConnection} must be configured before it has connected to the * remote resource. Instances of {@code URLConnection} are not reusable: you * must use a different instance for each connection to a resource. * *

Timeouts

* {@code URLConnection} supports two timeouts: a {@link #setConnectTimeout * connect timeout} and a {@link #setReadTimeout read timeout}. By default, * operations never time out. * *

Built-in Protocols

* * *

Registering Additional Protocols

* Use {@link URL#setURLStreamHandlerFactory} to register handlers for other * protocol types. */ public abstract class URLConnection { /** * The URL which represents the remote target of this {@code URLConnection}. */ protected URL url; private String contentType; private static boolean defaultAllowUserInteraction; private static boolean defaultUseCaches = true; ContentHandler defaultHandler = new DefaultContentHandler(); private long lastModified = -1; /** * The data must be modified more recently than this time in milliseconds * since January 1, 1970, GMT to be transmitted. */ protected long ifModifiedSince; /** * Specifies whether the using of caches is enabled or the data has to be * recent for every request. */ protected boolean useCaches = defaultUseCaches; /** * Specifies whether this {@code URLConnection} is already connected to the * remote resource. If this field is set to {@code true} the flags for * setting up the connection are not changeable anymore. */ protected boolean connected; /** * Specifies whether this {@code URLConnection} allows sending data. */ protected boolean doOutput; /** * Specifies whether this {@code URLConnection} allows receiving data. */ protected boolean doInput = true; /** * Unused by Android. This field can be accessed via {@link #getAllowUserInteraction} * and {@link #setAllowUserInteraction}. */ protected boolean allowUserInteraction = defaultAllowUserInteraction; private static ContentHandlerFactory contentHandlerFactory; private int readTimeout = 0; private int connectTimeout = 0; /** * Cache for storing content handler */ static Hashtable contentHandlers = new Hashtable(); /** * A hashtable that maps the filename extension (key) to a MIME-type * (element) */ private static FileNameMap fileNameMap; /** * Creates a new {@code URLConnection} instance pointing to the resource * specified by the given URL. * * @param url * the URL which represents the resource this {@code * URLConnection} will point to. */ protected URLConnection(URL url) { this.url = url; } /** * Opens a connection to the resource. This method will not * reconnect to a resource after the initial connection has been closed. * * @throws IOException * if an error occurs while connecting to the resource. */ public abstract void connect() throws IOException; /** * Returns {@code allowUserInteraction}. Unused by Android. */ public boolean getAllowUserInteraction() { return allowUserInteraction; } /** * Returns an object representing the content of the resource this {@code * URLConnection} is connected to. First, it attempts to get the content * type from the method {@code getContentType()} which looks at the response * header field "Content-Type". If none is found it will guess the content * type from the filename extension. If that fails the stream itself will be * used to guess the content type. * * @return the content representing object. * @throws IOException * if an error occurs obtaining the content. */ public Object getContent() throws java.io.IOException { if (!connected) { connect(); } if ((contentType = getContentType()) == null) { if ((contentType = guessContentTypeFromName(url.getFile())) == null) { contentType = guessContentTypeFromStream(getInputStream()); } } if (contentType != null) { return getContentHandler(contentType).getContent(this); } return null; } /** * Returns an object representing the content of the resource this {@code * URLConnection} is connected to. First, it attempts to get the content * type from the method {@code getContentType()} which looks at the response * header field "Content-Type". If none is found it will guess the content * type from the filename extension. If that fails the stream itself will be * used to guess the content type. The content type must match with one of * the list {@code types}. * * @param types * the list of acceptable content types. * @return the content representing object or {@code null} if the content * type does not match with one of the specified types. * @throws IOException * if an error occurs obtaining the content. */ // Param is not generic in spec @SuppressWarnings("unchecked") public Object getContent(Class[] types) throws IOException { if (!connected) { connect(); } if ((contentType = getContentType()) == null) { if ((contentType = guessContentTypeFromName(url.getFile())) == null) { contentType = guessContentTypeFromStream(getInputStream()); } } if (contentType != null) { return getContentHandler(contentType).getContent(this, types); } return null; } /** * Returns the content encoding type specified by the response header field * {@code content-encoding} or {@code null} if this field is not set. * * @return the value of the response header field {@code content-encoding}. */ public String getContentEncoding() { return getHeaderField("Content-Encoding"); } /** * Returns the specific ContentHandler that will handle the type {@code * contentType}. * * @param type * The type that needs to be handled * @return An instance of the Content Handler */ private ContentHandler getContentHandler(String type) throws IOException { // Replace all non-alphanumeric character by '_' final String typeString = parseTypeString(type.replace('/', '.')); // if there's a cached content handler, use it Object cHandler = contentHandlers.get(type); if (cHandler != null) { return (ContentHandler) cHandler; } if (contentHandlerFactory != null) { cHandler = contentHandlerFactory.createContentHandler(type); contentHandlers.put(type, cHandler); return (ContentHandler) cHandler; } // search through the package list for the right class for the Content Type String packageList = System.getProperty("java.content.handler.pkgs"); if (packageList != null) { for (String packageName : packageList.split("\\|")) { String className = packageName + "." + typeString; try { Class klass = Class.forName(className, true, ClassLoader.getSystemClassLoader()); cHandler = klass.newInstance(); } catch (ClassNotFoundException e) { } catch (IllegalAccessException e) { } catch (InstantiationException e) { } } } if (cHandler == null) { try { // Try looking up AWT image content handlers String className = "org.apache.harmony.awt.www.content." + typeString; cHandler = Class.forName(className).newInstance(); } catch (ClassNotFoundException e) { } catch (IllegalAccessException e) { } catch (InstantiationException e) { } } if (cHandler != null) { if (!(cHandler instanceof ContentHandler)) { throw new UnknownServiceException(); } contentHandlers.put(type, cHandler); // if we got the handler, // cache it for next time return (ContentHandler) cHandler; } return defaultHandler; } /** * Returns the content length in bytes specified by the response header field * {@code content-length} or {@code -1} if this field is not set. * * @return the value of the response header field {@code content-length}. */ public int getContentLength() { return getHeaderFieldInt("Content-Length", -1); } /** * Returns the MIME-type of the content specified by the response header field * {@code content-type} or {@code null} if type is unknown. * * @return the value of the response header field {@code content-type}. */ public String getContentType() { return getHeaderField("Content-Type"); } /** * Returns the timestamp when this response has been sent as a date in * milliseconds since January 1, 1970 GMT or {@code 0} if this timestamp is * unknown. * * @return the sending timestamp of the current response. */ public long getDate() { return getHeaderFieldDate("Date", 0); } /** * Returns the default value of {@code allowUserInteraction}. Unused by Android. */ public static boolean getDefaultAllowUserInteraction() { return defaultAllowUserInteraction; } /** * Returns null. * * @deprecated Use {@link #getRequestProperty} instead. */ @Deprecated public static String getDefaultRequestProperty(String field) { return null; } /** * Returns the default setting whether this connection allows using caches. * * @return the value of the default setting {@code defaultUseCaches}. * @see #useCaches */ public boolean getDefaultUseCaches() { return defaultUseCaches; } /** * Returns the value of the option {@code doInput} which specifies whether this * connection allows to receive data. * * @return {@code true} if this connection allows input, {@code false} * otherwise. * @see #doInput */ public boolean getDoInput() { return doInput; } /** * Returns the value of the option {@code doOutput} which specifies whether * this connection allows to send data. * * @return {@code true} if this connection allows output, {@code false} * otherwise. * @see #doOutput */ public boolean getDoOutput() { return doOutput; } /** * Returns the timestamp when this response will be expired in milliseconds * since January 1, 1970 GMT or {@code 0} if this timestamp is unknown. * * @return the value of the response header field {@code expires}. */ public long getExpiration() { return getHeaderFieldDate("Expires", 0); } /** * Returns the table which is used by all {@code URLConnection} instances to * determine the MIME-type according to a file extension. * * @return the file name map to determine the MIME-type. */ public static FileNameMap getFileNameMap() { synchronized (URLConnection.class) { if (fileNameMap == null) { fileNameMap = new DefaultFileNameMap(); } return fileNameMap; } } /** * Returns the header value at the field position {@code pos} or {@code null} * if the header has fewer than {@code pos} fields. The base * implementation of this method returns always {@code null}. * *

Some implementations (notably {@code HttpURLConnection}) include a mapping * for the null key; in HTTP's case, this maps to the HTTP status line and is * treated as being at position 0 when indexing into the header fields. * * @param pos * the field position of the response header. * @return the value of the field at position {@code pos}. */ public String getHeaderField(int pos) { return null; } /** * Returns an unmodifiable map of the response-header fields and values. The * response-header field names are the key values of the map. The map values * are lists of header field values associated with a particular key name. * *

Some implementations (notably {@code HttpURLConnection}) include a mapping * for the null key; in HTTP's case, this maps to the HTTP status line and is * treated as being at position 0 when indexing into the header fields. * * @return the response-header representing generic map. * @since 1.4 */ public Map> getHeaderFields() { return Collections.emptyMap(); } /** * Returns an unmodifiable map of general request properties used by this * connection. The request property names are the key values of the map. The * map values are lists of property values of the corresponding key name. * * @return the request-property representing generic map. * @since 1.4 */ public Map> getRequestProperties() { checkNotConnected(); return Collections.emptyMap(); } private void checkNotConnected() { if (connected) { throw new IllegalStateException("Already connected"); } } /** * Adds the given property to the request header. Existing properties with * the same name will not be overwritten by this method. * * @param field * the request property field name to add. * @param newValue * the value of the property which is to add. * @throws IllegalStateException * if the connection has been already established. * @throws NullPointerException * if the property name is {@code null}. * @since 1.4 */ public void addRequestProperty(String field, String newValue) { checkNotConnected(); if (field == null) { throw new NullPointerException("field == null"); } } /** * Returns the value of the header field specified by {@code key} or {@code * null} if there is no field with this name. The base implementation of * this method returns always {@code null}. * *

Some implementations (notably {@code HttpURLConnection}) include a mapping * for the null key; in HTTP's case, this maps to the HTTP status line and is * treated as being at position 0 when indexing into the header fields. * * @param key * the name of the header field. * @return the value of the header field. */ public String getHeaderField(String key) { return null; } /** * Returns the specified header value as a date in milliseconds since January * 1, 1970 GMT. Returns the {@code defaultValue} if no such header field * could be found. * * @param field * the header field name whose value is needed. * @param defaultValue * the default value if no field has been found. * @return the value of the specified header field as a date in * milliseconds. */ @SuppressWarnings("deprecation") public long getHeaderFieldDate(String field, long defaultValue) { String date = getHeaderField(field); if (date == null) { return defaultValue; } try { return Date.parse(date); // TODO: use HttpDate.parse() } catch (Exception e) { return defaultValue; } } /** * Returns the specified header value as a number. Returns the {@code * defaultValue} if no such header field could be found or the value could * not be parsed as an {@code Integer}. * * @param field * the header field name whose value is needed. * @param defaultValue * the default value if no field has been found. * @return the value of the specified header field as a number. */ public int getHeaderFieldInt(String field, int defaultValue) { try { return Integer.parseInt(getHeaderField(field)); } catch (NumberFormatException e) { return defaultValue; } } /** * Returns the name of the header field at the given position {@code posn} or * {@code null} if there are fewer than {@code posn} fields. The base * implementation of this method returns always {@code null}. * *

Some implementations (notably {@code HttpURLConnection}) include a mapping * for the null key; in HTTP's case, this maps to the HTTP status line and is * treated as being at position 0 when indexing into the header fields. * * @param posn * the position of the header field which has to be returned. * @return the header field name at the given position. */ public String getHeaderFieldKey(int posn) { return null; } /** * Returns the point of time since when the data must be modified to be * transmitted. Some protocols transmit data only if it has been modified * more recently than a particular time. * * @return the time in milliseconds since January 1, 1970 GMT. * @see #ifModifiedSince */ public long getIfModifiedSince() { return ifModifiedSince; } /** * Returns an {@code InputStream} for reading data from the resource pointed by * this {@code URLConnection}. It throws an UnknownServiceException by * default. This method must be overridden by its subclasses. * * @return the InputStream to read data from. * @throws IOException * if no InputStream could be created. */ public InputStream getInputStream() throws IOException { throw new UnknownServiceException("Does not support writing to the input stream"); } /** * Returns the value of the response header field {@code last-modified} or * {@code 0} if this value is not set. * * @return the value of the {@code last-modified} header field. */ public long getLastModified() { if (lastModified != -1) { return lastModified; } return lastModified = getHeaderFieldDate("Last-Modified", 0); } /** * Returns an {@code OutputStream} for writing data to this {@code * URLConnection}. It throws an {@code UnknownServiceException} by default. * This method must be overridden by its subclasses. * * @return the OutputStream to write data. * @throws IOException * if no OutputStream could be created. */ public OutputStream getOutputStream() throws IOException { throw new UnknownServiceException("Does not support writing to the output stream"); } /** * Returns a {@code Permission} object representing all needed permissions to * open this connection. The returned permission object depends on the state * of the connection and will be {@code null} if no permissions are * necessary. By default, this method returns {@code AllPermission}. * Subclasses should overwrite this method to return an appropriate * permission object. * * @return the permission object representing the needed permissions to open * this connection. * @throws IOException * if an I/O error occurs while creating the permission object. */ public java.security.Permission getPermission() throws IOException { return new java.security.AllPermission(); } /** * Returns the value of the request header property specified by {code field} * or {@code null} if there is no field with this name. The base * implementation of this method returns always {@code null}. * * @param field * the name of the request header property. * @return the value of the property. * @throws IllegalStateException * if the connection has been already established. */ public String getRequestProperty(String field) { checkNotConnected(); return null; } /** * Returns the URL represented by this {@code URLConnection}. * * @return the URL of this connection. */ public URL getURL() { return url; } /** * Returns the value of the flag which specifies whether this {@code * URLConnection} allows to use caches. * * @return {@code true} if using caches is allowed, {@code false} otherwise. */ public boolean getUseCaches() { return useCaches; } /** * Determines the MIME-type of the given resource {@code url} by resolving * the filename extension with the internal FileNameMap. Any fragment * identifier is removed before processing. * * @param url * the URL with the filename to get the MIME type. * @return the guessed content type or {@code null} if the type could not be * determined. */ public static String guessContentTypeFromName(String url) { return getFileNameMap().getContentTypeFor(url); } /** * Determines the MIME-type of the resource represented by the input stream * {@code is} by reading its first few characters. * * @param is * the resource representing input stream to determine the * content type. * @return the guessed content type or {@code null} if the type could not be * determined. * @throws IOException * if an I/O error occurs while reading from the input stream. */ public static String guessContentTypeFromStream(InputStream is) throws IOException { if (!is.markSupported()) { return null; } // Look ahead up to 64 bytes for the longest encoded header is.mark(64); byte[] bytes = new byte[64]; int length = is.read(bytes); is.reset(); // If there is no data from the input stream, we can't determine content type. if (length == -1) { return null; } // Check for Unicode BOM encoding indicators String encoding = "US-ASCII"; int start = 0; if (length > 1) { if ((bytes[0] == (byte) 0xFF) && (bytes[1] == (byte) 0xFE)) { encoding = "UTF-16LE"; start = 2; length -= length & 1; } if ((bytes[0] == (byte) 0xFE) && (bytes[1] == (byte) 0xFF)) { encoding = "UTF-16BE"; start = 2; length -= length & 1; } if (length > 2) { if ((bytes[0] == (byte) 0xEF) && (bytes[1] == (byte) 0xBB) && (bytes[2] == (byte) 0xBF)) { encoding = "UTF-8"; start = 3; } if (length > 3) { if ((bytes[0] == (byte) 0x00) && (bytes[1] == (byte) 0x00) && (bytes[2] == (byte) 0xFE) && (bytes[3] == (byte) 0xFF)) { encoding = "UTF-32BE"; start = 4; length -= length & 3; } if ((bytes[0] == (byte) 0xFF) && (bytes[1] == (byte) 0xFE) && (bytes[2] == (byte) 0x00) && (bytes[3] == (byte) 0x00)) { encoding = "UTF-32LE"; start = 4; length -= length & 3; } } } } String header = new String(bytes, start, length - start, encoding); // Check binary types if (header.startsWith("PK")) { return "application/zip"; } if (header.startsWith("GI")) { return "image/gif"; } // Check text types String textHeader = header.trim().toUpperCase(Locale.US); if (textHeader.startsWith("Warning: if the hostname resolves to multiple IP * addresses, this client will try each in RFC 3484 order. If * connecting to each of these addresses fails, multiple timeouts will * elapse before the connect attempt throws an exception. Host names that * support both IPv6 and IPv4 always have at least 2 IP addresses. * * @throws IllegalArgumentException if {@code timeoutMillis < 0}. */ public void setConnectTimeout(int timeoutMillis) { if (timeoutMillis < 0) { throw new IllegalArgumentException("timeoutMillis < 0"); } this.connectTimeout = timeoutMillis; } /** * Returns the connect timeout in milliseconds. (See {#setConnectTimeout}.) */ public int getConnectTimeout() { return connectTimeout; } /** * Sets the maximum time to wait for an input stream read to complete before * giving up. Reading will fail with a {@link SocketTimeoutException} if the * timeout elapses before data becomes available. The default value of * {@code 0} disables read timeouts; read attempts will block indefinitely. * * @param timeoutMillis the read timeout in milliseconds. Non-negative. */ public void setReadTimeout(int timeoutMillis) { if (timeoutMillis < 0) { throw new IllegalArgumentException("timeoutMillis < 0"); } this.readTimeout = timeoutMillis; } /** * Returns the read timeout in milliseconds, or {@code 0} if reads never * timeout. */ public int getReadTimeout() { return readTimeout; } /** * Returns the string representation containing the name of this class and * the URL. * * @return the string representation of this {@code URLConnection} instance. */ @Override public String toString() { return getClass().getName() + ":" + url.toString(); } static class DefaultContentHandler extends java.net.ContentHandler { @Override public Object getContent(URLConnection u) throws IOException { return u.getInputStream(); } } }