home *** CD-ROM | disk | FTP | other *** search
/ DOS/V Power Report 1998 February / VPR9802A.ISO / APP_DEMO / VC / MAIN.BIN / URL.java < prev    next >
Text File  |  1997-10-27  |  26KB  |  718 lines
  1. /*
  2.  * @(#)URL.java    1.42 97/02/21
  3.  * 
  4.  * Copyright (c) 1995, 1996 Sun Microsystems, Inc. All Rights Reserved.
  5.  * 
  6.  * This software is the confidential and proprietary information of Sun
  7.  * Microsystems, Inc. ("Confidential Information").  You shall not
  8.  * disclose such Confidential Information and shall use it only in
  9.  * accordance with the terms of the license agreement you entered into
  10.  * with Sun.
  11.  * 
  12.  * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE
  13.  * SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  14.  * IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  15.  * PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES
  16.  * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING
  17.  * THIS SOFTWARE OR ITS DERIVATIVES.
  18.  * 
  19.  * CopyrightVersion 1.1_beta
  20.  * 
  21.  */
  22.  
  23. package java.net;
  24.  
  25. import java.io.IOException;
  26. import java.io.InputStream;
  27. import java.io.OutputStream;
  28. import java.util.Hashtable;
  29. import java.util.StringTokenizer;
  30.  
  31. /**
  32.  * Class <code>URL</code> represents a Uniform Resource 
  33.  * Locator, a pointer to a "resource" on the World 
  34.  * Wide Web. A resource can be something as simple as a file or a 
  35.  * directory, or it can be a reference to a more complicated object, 
  36.  * such as a query to a database or to a search engine. More 
  37.  * information on the types of URLs and their formats can be found at:
  38.  * <ul><code>
  39.  *     http://www.ncsa.uiuc.edu/demoweb/url-primer.html
  40.  * </code></ul>
  41.  * <p>
  42.  * In general, a URL can be broken into several parts. The previous 
  43.  * example of a URL indicates that the protocol to use is 
  44.  * <code>http</code> (HyperText Transport Protocol) and that the 
  45.  * information resides on a host machine named 
  46.  * <code>www.ncsa.uiuc.edu</code>. The information on that host 
  47.  * machine is named <code>demoweb/url-primer.html</code>. The exact 
  48.  * meaning of this name on the host machine is both protocol 
  49.  * dependent and host dependent. The information normally resides in 
  50.  * a file, but it could be generated on the fly. This component of 
  51.  * the URL is called the <i>file</i> component, even though the 
  52.  * information is not necessarily in a file. 
  53.  * <p>
  54.  * A URL can optionally specify a "port", which is the 
  55.  * port number to which the TCP connection is made on the remote host 
  56.  * machine. If the port is not specified, the default port for 
  57.  * the protocol is used instead. For example, the default port for 
  58.  * <code>http</code> is <code>80</code>. An alternative port could be 
  59.  * specified as: 
  60.  * <ul><code>
  61.  *     http://www.ncsa.uiuc.edu:8080/demoweb/url-primer.html
  62.  * </code></ul>
  63.  * <p>
  64.  * A URL may have appended to it an "anchor", also known 
  65.  * as a "ref" or a "reference". The anchor is 
  66.  * indicated by the sharp sign character "#" followed by 
  67.  * more characters. For example, 
  68.  * <ul><code>
  69.  *     http://java.sun.com/index.html#chapter1
  70.  * </code></ul>
  71.  * <p>
  72.  * This anchor is not technically part of the URL. Rather, it 
  73.  * indicates that after the specified resource is retrieved, the 
  74.  * application is specifically interested in that part of the 
  75.  * document that has the tag <code>chapter1</code> attached to it. The 
  76.  * meaning of a tag is resource specific. 
  77.  * <p>
  78.  * An application can also specify a "relative URL", 
  79.  * which contains only enough information to reach the resource 
  80.  * relative to another URL. Relative URLs are frequently used within 
  81.  * HTML pages. For example, if the contents of the URL:
  82.  * <ul><code>
  83.  *     http://java.sun.com/index.html
  84.  * </code></ul>
  85.  * contained within it the relative URL:
  86.  * <ul><code>
  87.  *     FAQ.html
  88.  * </code></ul>
  89.  * it would be a shorthand for:
  90.  * <ul><code>
  91.  *     http://java.sun.com/FAQ.html
  92.  * </code></ul>
  93.  * <p>
  94.  * The relative URL need not specify all the components of a URL. If 
  95.  * the protocol, host name, or port number is missing, the value is 
  96.  * inherited from the fully specified URL. The file component must be 
  97.  * specified. The optional anchor is not inherited. 
  98.  *
  99.  * @author  James Gosling
  100.  * @version 1.42, 02/21/97
  101.  * @since   JDK1.0
  102.  */
  103. public final class URL implements java.io.Serializable {
  104.     /**
  105.      * The property which specifies the package prefix list to be scanned
  106.      * for protocol handlers.  The value of this property (if any) should
  107.      * be a vertical bar delimited list of package names to search through
  108.      * for a protocol handler to load.  The policy of this class is that
  109.      * all protocol handlers will be in a class called <protocolname>.Handler,
  110.      * and each package in the list is examined in turn for a matching
  111.      * handler.  If none are found (or the property is not specified), the
  112.      * default package prefix, sun.net.www.protocol, is used.  The search
  113.      * proceeds from the first package in the last to the last and stops
  114.      * when a match is found.
  115.      */
  116.     private static final String protocolPathProp = "java.protocol.handler.pkgs";
  117.  
  118.     /** 
  119.      * The protocol to use (ftp, http, nntp, ... etc.) . 
  120.      */
  121.     private String protocol;
  122.  
  123.     /** 
  124.      * The host name in which to connect to. 
  125.      */
  126.     private String host;
  127.  
  128.     /** 
  129.      * The protocol port to connect to. 
  130.      */
  131.     private int port = -1;
  132.  
  133.     /** 
  134.      * The specified file name on that host. 
  135.      */
  136.     private String file;
  137.  
  138.     /** 
  139.      * # reference. 
  140.      */
  141.     private String ref;
  142.  
  143.     /**
  144.      * The URLStreamHandler for this URL.
  145.      */
  146.     transient URLStreamHandler handler;
  147.  
  148.     /* Our hash code */
  149.     private int hashCode = -1;
  150.  
  151.     /** 
  152.      * Creates a <code>URL</code> object from the specified 
  153.      * <code>protocol</code>, <code>host</code>, <code>port</code> 
  154.      * number, and <code>file</code>. Specifying a <code>port</code> 
  155.      * number of <code>-1</code> indicates that the URL should use 
  156.      * the default port for the protocol. 
  157.      * <p>
  158.      * If this is the first URL object being created with the specified 
  159.      * protocol, a <i>stream protocol handler</i> object, an instance of 
  160.      * class <code>URLStreamHandler</code>, is created for that protocol:
  161.      * <ol>
  162.      * <li>If the application has previously set up an instance of
  163.      *     <code>URLStreamHandlerFactory</code> as the stream handler factory,
  164.      *     then the <code>createURLStreamHandler</code> method of that instance
  165.      *     is called with the protocol string as an argument to create the
  166.      *     stream protocol handler.
  167.      * <li>If no <code>URLStreamHandlerFactory</code> has yet been set up,
  168.      *     or if the factory's <code>createURLStreamHandler</code> method
  169.      *     returns <code>null</code>, then the constructor finds the 
  170.      *     value of the system property:
  171.      *     <ul><code>
  172.      *         java.handler.protol.pkgs
  173.      *     </code></ul>
  174.      *     If the value of that system property is not <code>null</code>,
  175.      *     it is interpreted as a list of packages separated by a vertical
  176.      *     slash character '<code>|</code>'. The constructor tries to load 
  177.      *     the class named:
  178.      *     <ul><code>
  179.      *         <<i>package</i>>.<<i>protocol</i>>.Handler
  180.      *     </code></ul>
  181.      *     where <<i>package</i>> is replaced by the name of the package
  182.      *     and <<i>protocol</i>> is replaced by the name of the protocol.
  183.      *     If this class does not exist, or if the class exists but it is not
  184.      *     a subclass of <code>URLStreamHandler</code>, then the next package
  185.      *     in the list is tried.
  186.      * <li>If the previous step fails to find a protocol handler, then the
  187.      *     constructor tries to load the class named:
  188.      *     <ul><code>
  189.      *         sun.net.www.protocol.<<i>protocol</i>>.Handler
  190.      *     </code></ul>
  191.      *     If this class does not exist, or if the class exists but it is not a
  192.      *     subclass of <code>URLStreamHandler</code>, then a
  193.      *     <code>MalformedURLException</code> is thrown.
  194.      * </ol>
  195.      *
  196.      * @param      protocol   the name of the protocol.
  197.      * @param      host       the name of the host.
  198.      * @param      port       the port number.
  199.      * @param      file       the host file.
  200.      * @exception  MalformedURLException  if an unknown protocol is specified.
  201.      * @see        java.lang.System#getProperty(java.lang.String)
  202.      * @see        java.net.URL#setURLStreamHandlerFactory(java.net.URLStreamHandlerFactory)
  203.      * @see        java.net.URLStreamHandler
  204.      * @see        java.net.URLStreamHandlerFactory#createURLStreamHandler(java.lang.String)
  205.      * @since      JDK1.0
  206.      */
  207.     public URL(String protocol, String host, int port, String file)
  208.     throws MalformedURLException {
  209.     this.protocol = protocol;
  210.     this.host = host;
  211.     this.port = port;
  212.     int ind = file.indexOf('#');
  213.     this.file = ind < 0 ? file: file.substring(0, ind);
  214.     this.ref = ind < 0 ? null: file.substring(ind + 1);
  215.     if ((handler = getURLStreamHandler(protocol)) == null) {
  216.         throw new MalformedURLException("unknown protocol: " + protocol);
  217.     }
  218.     }
  219.  
  220.     /** 
  221.      * Creates an absolute URL from the specified <code>protocol</code> 
  222.      * name, <code>host</code> name, and <code>file</code> name. The 
  223.      * default port for the specified protocol is used. 
  224.      * <p>
  225.      * This method is equivalent to calling the four-argument 
  226.      * constructor with the arguments being <code>protocol</code>, 
  227.      * <code>host</code>, <code>-1</code>, and <code>file</code>. 
  228.      *
  229.      * @param      protocol   the protocol to use.
  230.      * @param      host       the host to connect to.
  231.      * @param      file       the file on that host.
  232.      * @exception  MalformedURLException  if an unknown protocol is specified.
  233.      * @see        java.net.URL#URL(java.lang.String, java.lang.String, int, java.lang.String)
  234.      * @since      JDK1.0
  235.      */
  236.     public URL(String protocol, String host, String file) throws MalformedURLException {
  237.     this(protocol, host, -1, file);
  238.     }
  239.  
  240.     /**
  241.      * Creates a <code>URL</code> object from the <code>String</code> 
  242.      * representation. 
  243.      * <p>
  244.      * This constructor is equivalent to a call to the two-argument 
  245.      * constructor with a <code>null</code> first argument. 
  246.      *
  247.      * @param      spec   the <code>String</code> to parse as a URL.
  248.      * @exception  MalformedURLException  If the string specifies an
  249.      *               unknown protocol.
  250.      * @see        java.net.URL#URL(java.net.URL, java.lang.String)
  251.      * @since      JDK1.0
  252.      */
  253.     public URL(String spec) throws MalformedURLException {
  254.     this(null, spec);
  255.     }
  256.  
  257.     /** 
  258.      * Creates a URL by parsing the specification <code>spec</code> 
  259.      * within a specified context. If the <code>context</code> argument 
  260.      * is not <code>null</code> and the <code>spec</code> argument is a 
  261.      * partial URL specification, then any of the strings missing 
  262.      * components are inherited from the <code>context</code> argument. 
  263.      * <p>
  264.      * The specification given by the <code>String</code> argument is 
  265.      * parsed to determine if it specifies a protocol. If the 
  266.      * <code>String</code> contains an ASCII colon '<code>:</code>'
  267.      * character before the first occurrence of an ASCII slash character 
  268.      * '<code>/</code>', then the characters before the colon comprise 
  269.      * the protocol. 
  270.      * <ul>
  271.      * <li>If the <code>spec</code> argument does not specify a protocol:
  272.      *     <ul>
  273.      *     <li>If the context argument is not <code>null</code>, then the
  274.      *         protocol is copied from the context argument.
  275.      *     <li>If the context argument is <code>null</code>, then a
  276.      *         <code>MalformedURLException</code> is thrown.
  277.      *     </ul>
  278.      * <li>If the <code>spec</code> argument does specify a protocol:
  279.      *     <ul>
  280.      *     <li>If the context argument is <code>null</code>, or specifies a
  281.      *         different protocol than the specification argument, the context
  282.      *         argument is ignored.
  283.      *     <li>If the context argument is not <code>null</code> and specifies
  284.      *         the same protocol as the specification, the <code>host</code>,
  285.      *         <code>port</code> number, and <code>file</code> are copied from
  286.      *         the context argument into the newly created <code>URL</code>.
  287.      *     </ul>
  288.      * </ul>
  289.      * <p>
  290.      * The constructor then searches for an appropriate stream protocol 
  291.      * handler of type <code>URLStreamHandler</code> as outlined for:
  292.      * <ul><code>
  293.      *     java.net.URL#URL(java.lang.String, java.lang.String, int,
  294.      *                      java.lang.String)
  295.      * </code></ul>
  296.      * The stream protocol handler's 
  297.      * <code>parseURL</code> method is called to parse the remaining 
  298.      * fields of the specification that override any defaults set by the 
  299.      * context argument. 
  300.  
  301.      * @param      context   the context in which to parse the specification.
  302.      * @param      spec      a <code>String</code> representation of a URL.
  303.      * @exception  MalformedURLException  if no protocol is specified, or an
  304.      *               unknown protocol is found.
  305.      * @see        java.net.URL#URL(java.lang.String, java.lang.String, int, java.lang.String)
  306.      * @see        java.net.URLStreamHandler
  307.      * @see        java.net.URLStreamHandler#parseURL(java.net.URL, java.lang.String, int, int)
  308.      * @since   JDK1.0
  309.      */
  310.     public URL(URL context, String spec) throws MalformedURLException {
  311.     String original = spec;
  312.     int i, limit, c;
  313.     int start = 0;
  314.     String newProtocol = null;
  315.     boolean aRef=false;
  316.  
  317.     try {
  318.         limit = spec.length();
  319.         while ((limit > 0) && (spec.charAt(limit - 1) <= ' ')) {
  320.         limit--;    //eliminate trailing whitespace
  321.         }
  322.         while ((start < limit) && (spec.charAt(start) <= ' ')) {
  323.         start++;    // eliminate leading whitespace
  324.         }
  325.  
  326.         if (spec.regionMatches(true, start, "url:", 0, 4)) {
  327.         start += 4;
  328.         }
  329.         if (start < spec.length() && spec.charAt(start) == '#') {
  330.         /* we're assuming this is a ref relative to the context URL.
  331.          * This means protocols cannot start w/ '#', but we must parse
  332.          * ref URL's like: "hello:there" w/ a ':' in them.
  333.          */
  334.         aRef=true;
  335.         }
  336.         for (i = start ; !aRef && (i < limit) && ((c = spec.charAt(i)) != '/') ; i++) {
  337.         if (c == ':') {
  338.             newProtocol = spec.substring(start, i).toLowerCase();
  339.             start = i + 1;
  340.             break;
  341.         }
  342.         }
  343.         // Only use our context if the protocols match.
  344.         if ((context != null) && ((newProtocol == null) ||
  345.                     newProtocol.equals(context.protocol))) {
  346.         protocol = context.protocol;
  347.         host = context.host;
  348.         port = context.port;
  349.         file = context.file;
  350.         } else {
  351.         protocol = newProtocol;
  352.         }
  353.  
  354.         if (protocol == null) {
  355.         throw new MalformedURLException("no protocol: "+original);
  356.         }
  357.  
  358.         if ((handler = getURLStreamHandler(protocol)) == null) {
  359.         throw new MalformedURLException("unknown protocol: "+protocol);
  360.         }
  361.  
  362.         i = spec.indexOf('#', start);
  363.         if (i >= 0) {
  364.         ref = spec.substring(i + 1, limit);
  365.         limit = i;
  366.         }
  367.         handler.parseURL(this, spec, start, limit);
  368.  
  369.     } catch(MalformedURLException e) {
  370.         throw e;
  371.     } catch(Exception e) {
  372.         throw new MalformedURLException(original + ": " + e);
  373.     }
  374.     }
  375.  
  376.     /**
  377.      * Sets the fields of the URL. This is not a public method so that 
  378.      * only URLStreamHandlers can modify URL fields. URLs are 
  379.      * otherwise constant.
  380.      *
  381.      * REMIND: this method will be moved to URLStreamHandler
  382.      *
  383.      * @param protocol the protocol to use
  384.      * @param host the host name to connecto to
  385.      * @param port the protocol port to connect to
  386.      * @param file the specified file name on that host
  387.      * @param ref the reference
  388.      */
  389.     protected void set(String protocol, String host, int port, String file, String ref) {
  390.     this.protocol = protocol;
  391.     this.host = host;
  392.     this.port = port;
  393.     this.file = file;
  394.     this.ref = ref;
  395.     }
  396.  
  397.     /**
  398.      * Returns the port number of this <code>URL</code>.
  399.      * Returns -1 if the port is not set.
  400.      *
  401.      * @return  the port number
  402.      * @since   JDK1.0
  403.      */
  404.     public int getPort() {
  405.     return port;
  406.     }
  407.  
  408.     /**
  409.      * Returns the protocol name this <code>URL</code>.
  410.      *
  411.      * @return  the protocol of this <code>URL</code>.
  412.      * @since   JDK1.0
  413.      */
  414.     public String getProtocol() {
  415.     return protocol;
  416.     }
  417.  
  418.     /**
  419.      * Returns the host name of this <code>URL</code>, if applicable.
  420.      * For "<code>file</code>" protocol, this is an empty string.
  421.      *
  422.      * @return  the host name of this <code>URL</code>.
  423.      * @since   JDK1.0
  424.      */
  425.     public String getHost() {
  426.     return host;
  427.     }
  428.  
  429.     /**
  430.      * Returns the file name of this <code>URL</code>.
  431.      *
  432.      * @return  the file name of this <code>URL</code>.
  433.      * @since   JDK1.0
  434.      */
  435.     public String getFile() {
  436.     return file;
  437.     }
  438.  
  439.     /**
  440.      * Returns the anchor (also known as the "reference") of this
  441.      * <code>URL</code>.
  442.      *
  443.      * @return  the anchor (also known as the "reference") of this
  444.      *          <code>URL</code>.
  445.      * @since   JDK1.0
  446.      */
  447.     public String getRef() {
  448.     return ref;
  449.     }
  450.  
  451.     /**
  452.      * Compares two URLs.
  453.      * The result is <code>true</code> if and only if the argument is 
  454.      * not <code>null</code> and is a <code>URL</code> object that 
  455.      * represents the same <code>URL</code> as this object. Two URL 
  456.      * objects are equal if they have the same protocol and reference the 
  457.      * same host, the same port number on the host, and the same file on 
  458.      * the host. The anchors of the URL objects are not compared. 
  459.      * <p>
  460.      * This method is equivalent to:
  461.      * <ul><code>
  462.      *     (obj instanceof URL) && sameFile((URL)obj)
  463.      * </code></ul>
  464.      *
  465.      * @param   obj   the URL to compare against.
  466.      * @return  <code>true</code> if the objects are the same;
  467.      *          <code>false</code> otherwise.
  468.      * @since   JDK1.0
  469.      */
  470.     public boolean equals(Object obj) {
  471.     return (ref == null) ? (obj instanceof URL) && sameFile((URL)obj):
  472.         (obj instanceof URL) && sameFile((URL)obj) && ref.equals(((URL)obj).ref);
  473.     }
  474.  
  475.     /** 
  476.      * Creates an integer suitable for hash table indexing. 
  477.      *
  478.      * @return  a hash code for this <code>URL</code>.
  479.      * @since   JDK1.0
  480.      */
  481.     public int hashCode() {
  482.  
  483.     if (hashCode == -1) {
  484.         hashCode = host.toLowerCase().hashCode() ^ file.hashCode() ^
  485.         protocol.hashCode();
  486.     }
  487.  
  488.     return hashCode;
  489.     }
  490.     
  491.     /**
  492.      * Compares the host components of two URLs.
  493.      * @param h1 the URL of the first host to compare 
  494.      * @param h2 the URL of the second host to compare 
  495.      * @return    true if and only if they are equal, false otherwise.
  496.      * @exception UnknownHostException If an unknown host is found.
  497.      */
  498.     boolean hostsEqual(String h1, String h2) {
  499.     if (h1.equals(h2)) {
  500.         return true;
  501.     }
  502.     // Have to resolve addresses before comparing, otherwise
  503.     // names like tachyon and tachyon.eng would compare different
  504.     try {
  505.         InetAddress a1 = InetAddress.getByName(h1);
  506.         InetAddress a2 = InetAddress.getByName(h2);
  507.         return a1.equals(a2);
  508.     } catch(UnknownHostException e) {
  509.     } catch(SecurityException e) {
  510.     }
  511.     return false;
  512.     }
  513.  
  514.     /**
  515.      * Compares two URLs, excluding the "ref" fields.
  516.      * Returns <code>true</code> if this <code>URL</code> and the 
  517.      * <code>other</code> argument both refer to the same resource.
  518.      * The two <code>URL</code>s might not both contain the same anchor. 
  519.      *
  520.      * @param   other   the <code>URL</code> to compare against.
  521.      * @return  <code>true</code> if they reference the same remote object;
  522.      *          <code>false</code> otherwise.
  523.      * @since   JDK1.0
  524.      */
  525.     public boolean sameFile(URL other) {
  526.     // AVH: should we not user getPort to compare ports?
  527.     return protocol.equals(other.protocol) &&
  528.            hostsEqual(host, other.host) &&
  529.            (port == other.port) &&
  530.            file.equals(other.file);
  531.     }
  532.  
  533.     /**
  534.      * Constructs a string representation of this <code>URL</code>. The 
  535.      * string is created by calling the <code>toExternalForm</code> 
  536.      * method of the stream protocol handler for this object. 
  537.      *
  538.      * @return  a string representation of this object.
  539.      * @see     java.net.URL#URL(java.lang.String, java.lang.String, int, java.lang.String)
  540.      * @see     java.net.URLStreamHandler#toExternalForm(java.net.URL)
  541.      * @since   JDK1.0
  542.      */
  543.     public String toString() {
  544.     return toExternalForm();
  545.     }
  546.  
  547.     /**
  548.      * Constructs a string representation of this <code>URL</code>. The 
  549.      * string is created by calling the <code>toExternalForm</code> 
  550.      * method of the stream protocol handler for this object. 
  551.      *
  552.      * @return  a string representation of this object.
  553.      * @see     java.net.URL#URL(java.lang.String, java.lang.String, int, java.lang.String)
  554.      * @see     java.net.URLStreamHandler#toExternalForm(java.net.URL)
  555.      * @since   JDK1.0
  556.      */
  557.     public String toExternalForm() {
  558.     return handler.toExternalForm(this);
  559.     }
  560.  
  561.     /** 
  562.      * Returns a <code>URLConnection</code> object that represents a 
  563.      * connection to the remote object referred to by the <code>URL</code>.
  564.      * <p>
  565.      * If there is not already an open connection, the connection is 
  566.      * opened by calling the <code>openConnection</code> method of the 
  567.      * protocol handler for this URL. 
  568.      *
  569.      * @return     a <code>URLConnection</code> to the URL.
  570.      * @exception  IOException  if an I/O exception occurs.
  571.      * @see        java.net.URL#URL(java.lang.String, java.lang.String, int, java.lang.String)
  572.      * @see        java.net.URLConnection
  573.      * @see        java.net.URLStreamHandler#openConnection(java.net.URL)
  574.      * @since      JDK1.0
  575.      */
  576.     public URLConnection openConnection()
  577.     throws java.io.IOException
  578.     {
  579.     return handler.openConnection(this);
  580.     }
  581.  
  582.     /**
  583.      * Opens a connection to this <code>URL</code> and returns an 
  584.      * <code>InputStream</code> for reading from that connection. This 
  585.      * method is a shorthand for:
  586.      * <ul><code>
  587.      *     openConnection().getInputStream()
  588.      * </code></ul>
  589.      *
  590.      * @return     an input stream for reading from the URL connection.
  591.      * @exception  IOException  if an I/O exception occurs.
  592.      * @since      JDK1.0
  593.      */
  594.     public final InputStream openStream()             // REMIND: drop final
  595.     throws java.io.IOException
  596.     {
  597.     return openConnection().getInputStream();
  598.     }
  599.  
  600.     /**
  601.      * Returns the contents of this URL. This method is a shorthand for:
  602.      * <ul><code>
  603.      *     openConnection().getContent()
  604.      * </code></ul>
  605.      *
  606.      * @return     the contents of this URL.
  607.      * @exception  IOException  if an I/O exception occurs.
  608.      * @see        java.net.URLConnection#getContent()
  609.      * @since      JDK1.0
  610.      */
  611.     public final Object getContent()                 // REMIND: drop final
  612.     throws java.io.IOException
  613.     {
  614.     return openConnection().getContent();
  615.     }
  616.  
  617.     /**
  618.      * The URLStreamHandler factory.
  619.      */
  620.     static URLStreamHandlerFactory factory;
  621.  
  622.     /**
  623.      * Sets an application's <code>URLStreamHandlerFactory</code>.
  624.      * This method can be called at most once by an application. 
  625.      * <p>
  626.      * The <code>URLStreamHandlerFactory</code> instance is used to 
  627.      * construct a stream protocol handler from a protocol name. 
  628.      *
  629.      * @param      fac   the desired factory.
  630.      * @exception  Error  if the application has already set a factory.
  631.      * @see        java.net.URL#URL(java.lang.String, java.lang.String, int, java.lang.String)
  632.      * @see        java.net.URLStreamHandlerFactory
  633.      * @since      JDK1.0
  634.      */
  635.     public static synchronized void setURLStreamHandlerFactory(URLStreamHandlerFactory fac) {
  636.     if (factory != null) {
  637.         throw new Error("factory already defined");
  638.     }
  639.     SecurityManager security = System.getSecurityManager();
  640.     if (security != null) {
  641.         security.checkSetFactory();
  642.     }
  643.     factory = fac;
  644.     }
  645.  
  646.     /**
  647.      * A table of protocol handlers.
  648.      */
  649.     static Hashtable handlers = new Hashtable();
  650.  
  651.     /**
  652.      * Returns the Stream Handler.
  653.      * @param protocol the protocol to use
  654.      */
  655.     static synchronized URLStreamHandler getURLStreamHandler(String protocol) {
  656.     URLStreamHandler handler = (URLStreamHandler)handlers.get(protocol);
  657.     if (handler == null) {
  658.         // Use the factory (if any)
  659.         if (factory != null) {
  660.         handler = factory.createURLStreamHandler(protocol);
  661.         }
  662.  
  663.         // Try java protocol handler
  664.         if (handler == null) {
  665.         String packagePrefixList =
  666.             System.getProperty(protocolPathProp, "");
  667.         if (packagePrefixList != "") {
  668.             packagePrefixList += "|";
  669.         }
  670.  
  671.         // REMIND: decide whether to allow the "null" class prefix
  672.         // or not.
  673.         packagePrefixList += "sun.net.www.protocol";
  674.  
  675.         StringTokenizer packagePrefixIter =
  676.             new StringTokenizer(packagePrefixList, "|");
  677.  
  678.         while (handler == null && packagePrefixIter.hasMoreTokens()) {
  679.             String packagePrefix = packagePrefixIter.nextToken().trim();
  680.             try {
  681.             String clname = packagePrefix + "." + protocol
  682.                 + ".Handler";
  683.             handler = (URLStreamHandler)Class.forName(clname).newInstance();
  684.             } catch (Exception e) {
  685.             }
  686.         }
  687.         }
  688.         if (handler != null) {
  689.         handlers.put(protocol, handler);
  690.         }
  691.     }
  692.     return handler;
  693.     }
  694.  
  695.     /**
  696.      * WriteObject is called to save the state of the URL to an ObjectOutputStream
  697.      * The handler is not saved since it is specific to this system.
  698.      */
  699.     private synchronized void writeObject(java.io.ObjectOutputStream s)
  700.         throws IOException
  701.     {
  702.     s.defaultWriteObject();    // write the fields
  703.     }
  704.  
  705.     /**
  706.      * readObject is called to restore the state of the URL from the stream.
  707.      * It reads the compoents of the URL and finds the local stream handler.
  708.      */
  709.     private synchronized void readObject(java.io.ObjectInputStream s)
  710.          throws IOException, ClassNotFoundException
  711.     {
  712.     s.defaultReadObject();    // read the fields
  713.     if ((handler = getURLStreamHandler(protocol)) == null) {
  714.         throw new IOException("unknown protocol: " + protocol);
  715.     }
  716.     }
  717. }
  718.