urlconnection.java

来自「《移动Agent技术》一书的所有章节源代码。」· Java 代码 · 共 1,104 行 · 第 1/3 页

/*
 * @(#)URLConnection.java	1.33 98/08/17
 *
 * Copyright 1995-1998 by Sun Microsystems, Inc.,
 * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
 * All rights reserved.
 *
 * This software is the confidential and proprietary information
 * of Sun Microsystems, Inc. ("Confidential Information").  You
 * shall not disclose such Confidential Information and shall use
 * it only in accordance with the terms of the license agreement
 * you entered into with Sun.
 */

package java.net;

import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.util.Hashtable;
import java.util.Date;
import java.util.StringTokenizer;

/**
 * The abstract class <code>URLConnection</code> is the superclass
 * of all classes that represent a communications link between the
 * application and a URL. Instances of this class can be used both to
 * read from and to write to the resource referenced by the URL. In
 * general, creating a connection to a URL is a multistep process:
 * <p>
 * <center><table border>
 * <tr><th><code>openConnection()</code></th>
 *     <th><code>connect()</code></th></tr>
 * <tr><td>Manipulate parameters that affect the connection to the remote
 *         resource.</td>
 *     <td>Interact with the resource; query header fields and
 *         contents.</td></tr>
 * </table>
 * ----------------------------&gt;
 * <br>time</center>
 *
 * <ol>
 * <li>The connection object is created by invoking the
 *     <code>openConnection</code> method on a URL.
 * <li>The setup parameters and general request properties are manipulated.
 * <li>The actual connection to the remote object is made, using the
 *    <code>connect</code> method.
 * <li>The remote object becomes available. The header fields and the contents
 *     of the remote object can be accessed.
 * </ol>
 * <p>
 * The setup parameters are modified using the following methods:
 * <ul><code>
 *   <li>setAllowUserInteraction
 *   <li>setDoInput
 *   <li>setDoOutput
 *   <li>setIfModifiedSince
 *   <li>setUseCaches
 * </code></ul>
 * <p>
 * and the general request properties are modified using the method:
 * <ul><code>
 *   <li>setRequestProperty
 * </code></ul>
 * <p>
 * Default values for the <code>AllowUserInteraction</code> and
 * <code>UseCaches</code> parameters can be set using the methods
 * <code>setDefaultAllowUserInteraction</code> and
 * <code>setDefaultUseCaches</code>. Default values for general
 * request properties can be set using the
 * <code>setDefaultRequestProperty</code> method.
 * <p>
 * Each of the above <code>set</code> methods has a corresponding
 * <code>get</code> method to retrieve the value of the parameter or
 * general request property. The specific parameters and general
 * request properties that are applicable are protocol specific.
 * <p>
 * The following methods are used to access the header fields and
 * the contents after the connection is made to the remote object:
 * <ul><code>
 *   <li>getContent
 *   <li>getHeaderField
 *   <li>getInputStream
 *   <li>getOutputStream
 * </code></ul>
 * <p>
 * Certain header fields are accessed frequently. The methods:
 * <ul><code>
 *   <li>getContentEncoding
 *   <li>getContentLength
 *   <li>getContentType
 *   <li>getDate
 *   <li>getExpiration
 *   <li>getLastModified
 * </code></ul>
 * <p>
 * provide convenient access to these fields. The
 * <code>getContentType</code> method is used by the
 * <code>getContent</code> method to determine the type of the remote
 * object; subclasses may find it convenient to override the
 * <code>getContentType</code> method.
 * <p>
 * In the common case, all of the pre-connection parameters and
 * general request properties can be ignored: the pre-connection
 * parameters and request properties default to sensible values. For
 * most clients of this interface, there are only two interesting
 * methods: <code>getInputStream</code> and <code>getObject</code>,
 * which are mirrored in the <code>URL</code> class by convenience methods.
 * <p>
 * More information on the request properties and header fields of
 * an <code>http</code> connection can be found at:
 * <ul><code>
 *   http://www.w3.org/hypertext/WWW/Protocols/HTTP1.0/draft-ietf-http-spec.html
 * </code></ul>
 * <p>
 * Note about <code>fileNameMap</code>: In versions prior to JDK 1.1.6,
 * field <code>fileNameMap</code> of <code>URLConnection</code> was public.
 * In JDK 1.1.6 and later, <code>fileNameMap</code> is private; accessor
 * method <code>getFileNameMap()</code> and mutator method
 * <code>setFileNameMap(FileNameMap)</code> are added to access it.
 * This change is also described on the
 * <a href="http://java.sun.com/products/jdk/1.1/compatibility.html">
 * JDK 1.1.x Compatibility</a> page.
 *
 * @author  James Gosling
 * @version 1.33, 08/17/98
 * @see     java.net.URL#openConnection()
 * @see     java.net.URLConnection#connect()
 * @see     java.net.URLConnection#getContent()
 * @see     java.net.URLConnection#getContentEncoding()
 * @see     java.net.URLConnection#getContentLength()
 * @see     java.net.URLConnection#getContentType()
 * @see     java.net.URLConnection#getDate()
 * @see     java.net.URLConnection#getExpiration()
 * @see     java.net.URLConnection#getHeaderField(int)
 * @see     java.net.URLConnection#getHeaderField(java.lang.String)
 * @see     java.net.URLConnection#getInputStream()
 * @see     java.net.URLConnection#getLastModified()
 * @see     java.net.URLConnection#getOutputStream()
 * @see     java.net.URLConnection#setAllowUserInteraction(boolean)
 * @see     java.net.URLConnection#setDefaultRequestProperty(java.lang.String, java.lang.String)
 * @see     java.net.URLConnection#setDefaultUseCaches(boolean)
 * @see     java.net.URLConnection#setDoInput(boolean)
 * @see     java.net.URLConnection#setDoOutput(boolean)
 * @see     java.net.URLConnection#setIfModifiedSince(long)
 * @see     java.net.URLConnection#setRequestProperty(java.lang.String, java.lang.String)
 * @see     java.net.URLConnection#setUseCaches(boolean)
 * @since   JDK1.0
 */
abstract public class URLConnection {
   /**
     * The URL represents the remote object on the World Wide Web to
     * which this connection is opened.
     * <p>
     * The value of this field can be accessed by the
     * <code>getURL</code> method.
     * <p>
     * The default value of this variable is the value of the URL
     * argument in the <code>URLConnection</code> constructor.
     *
     * @see     java.net.URLConnection#getURL()
     * @see     java.net.URLConnection#url
     * @since   JDK1.0
     */
    protected URL url;

   /**
     * This variable is set by the <code>setDoInput</code> method. Its
     * value is returned by the <code>getDoInput</code> method.
     * <p>
     * A URL connection can be used for input and/or output. Setting the
     * <code>doInput</code> flag to <code>true</code> indicates that
     * the application intends to read data from the URL connection.
     * <p>
     * The default value of this field is <code>true</code>.
     *
     * @see     java.net.URLConnection#getDoInput()
     * @see     java.net.URLConnection#setDoInput(boolean)
     * @since   JDK1.0
     */
    protected boolean doInput = true;

   /**
     * This variable is set by the <code>setDoOutput</code> method. Its
     * value is returned by the <code>getDoInput</code> method.
     * <p>
     * A URL connection can be used for input and/or output. Setting the
     * <code>doOutput</code> flag to <code>true</code> indicates
     * that the application intends to write data to the URL connection.
     * <p>
     * The default value of this field is <code>false</code>.
     *
     * @see     java.net.URLConnection#getDoOutput()
     * @see     java.net.URLConnection#setDoOutput(boolean)
     * @since   JDK1.0
     */
    protected boolean doOutput = false;

    private static boolean defaultAllowUserInteraction = false;

   /**
     * If <code>true</code>, this <code>URL</code> is being examined in
     * a context in which it makes sense to allow user interactions such
     * as popping up an authentication dialog. If <code>false</code>,
     * then no user interaction is allowed.
     * <p>
     * The value of this field can be set by the
     * <code>setAllowUserInteraction</code> method.
     * Its value is returned by the
     * <code>getAllowUserInteraction</code> method.
     * Its default value is the value of the argument in the last invocation
     * of the <code>setDefaultAllowUserInteraction</code> method.
     *
     * @see     java.net.URLConnection#getAllowUserInteraction()
     * @see     java.net.URLConnection#setAllowUserInteraction(boolean)
     * @see     java.net.URLConnection#setDefaultAllowUserInteraction(boolean)
     * @since   JDK1.0
     */
    protected boolean allowUserInteraction = defaultAllowUserInteraction;

    private static boolean defaultUseCaches = true;

   /**
     * If <code>true</code>, the protocol is allowed to use caching
     * whenever it can. If <code>false</code>, the protocol must always
     * try to get a fresh copy of the object.
     * <p>
     * This field is set by the <code>setUseCaches</code> method. Its
     * value is returned by the <code>getUseCaches</code> method.
     * <p>
     * Its default value is the value given in the last invocation of the
     * <code>setDefaultUseCaches</code> method.
     *
     * @see     java.net.URLConnection#setUseCaches(boolean)
     * @see     java.net.URLConnection#getUseCaches()
     * @see     java.net.URLConnection#setDefaultUseCaches(boolean)
     * @since   JDK1.0
     */
    protected boolean useCaches = defaultUseCaches;

   /**
     * Some protocols support skipping the fetching of the object unless
     * the object has been modified more recently than a certain time.
     * <p>
     * A nonzero value gives a time as the number of seconds since
     * January 1, 1970, GMT. The object is fetched only if it has been
     * modified more recently than that time.
     * <p>
     * This variable is set by the <code>setIfModifiedSince</code>
     * method. Its value is returned by the
     * <code>getIfModifiedSince</code> method.
     * <p>
     * The default value of this field is <code>0</code>, indicating
     * that the fetching must always occur.
     *
     * @see     java.net.URLConnection#getIfModifiedSince()
     * @see     java.net.URLConnection#setIfModifiedSince(long)
     * @since   JDK1.0
     */
    protected long ifModifiedSince = 0;

   /**
     * If <code>false</code>, this connection object has not created a
     * communications link to the specified URL. If <code>true</code>,
     * the communications link has been established.
     *
     * @since   JDK1.0
     */
    protected boolean connected = false;

   /**
    * @since   JDK1.1
    */
    private static FileNameMap fileNameMap;

    /**
     * Returns the FileNameMap.
     *
     * @returns	the FileNameMap
     * @since   JDK1.1
     */
    public static FileNameMap getFileNameMap() {
	return fileNameMap;
    }

    /**
     * Sets the FileNameMap.
     *
     * @param map the FileNameMap to be set
     * @since   JDK1.1
     */
    public static void setFileNameMap(FileNameMap map) {
	SecurityManager sm = System.getSecurityManager();
	if (sm != null) sm.checkSetFactory();
	fileNameMap = map;
    }

    /**
     * Opens a communications link to the resource referenced by this
     * URL, if such a connection has not already been established.
     * <p>
     * If the <code>connect</code> method is called when the connection
     * has already been opened (indicated by the <code>connected</code>
     * field having the value <code>true</code>), the call is ignored.
     * <p>
     * URLConnection objects go through two phases: first they are
     * created, then they are connected.  After being created, and
     * before being connected, various options can be specified
     * (e.g., doInput and UseCaches).  After connecting, it is an
     * error to try to set them.  Operations that depend on being
     * connected, like getContentLength, will implicitly perform the
     * connection, if necessary.
     *
     * @exception  IOException  if an I/O error occurs while opening the
     *               connection.
     * @see        java.net.URLConnection#connected
     * @since      JDK1.0
     */
    abstract public void connect() throws IOException;

    /**
     * Constructs a URL connection to the specified URL. A connection to
     * the object referenced by the URL is not created.
     *
     * @param   url   the specified URL.
     * @since   JDK1.0
     */
    protected URLConnection(URL url) {
	this.url = url;
    }

    /**
     * Returns the value of this <code>URLConnection</code>'s <code>URL</code>
     * field.
     *
     * @return  the value of this <code>URLConnection</code>'s <code>URL</code>
     *          field.
     * @see     java.net.URLConnection#url
     * @since   JDK1.0
     */
    public URL getURL() {
	return url;
    }

    /**
     * Returns the value of the <code>content-length</code> header field.
     *
     * @return  the content length of the resource that this connection's URL
     *          references, or <code>-1</code> if the content length is
     *          not known.
     * @since   JDK1.0
     */
    public int getContentLength() {
	return getHeaderFieldInt("content-length", -1);
    }

    /**
     * Returns the value of the <code>content-type</code> header field.
     *
     * @return  the content type of the resource that the URL references,
     *          or <code>null</code> if not known.
     * @see     java.net.URLConnection#getHeaderField(java.lang.String)
     * @since   JDK1.0
     */
    public String getContentType() {
	return getHeaderField("content-type");
    }