Source for java.net.URLStreamHandler

   1: /* URLStreamHandler.java -- Abstract superclass for all protocol handlers
   2:    Copyright (C) 1998, 1999, 2002, 2003, 2004 Free Software Foundation, Inc.
   3: 
   4: This file is part of GNU Classpath.
   5: 
   6: GNU Classpath is free software; you can redistribute it and/or modify
   7: it under the terms of the GNU General Public License as published by
   8: the Free Software Foundation; either version 2, or (at your option)
   9: any later version.
  10: 
  11: GNU Classpath is distributed in the hope that it will be useful, but
  12: WITHOUT ANY WARRANTY; without even the implied warranty of
  13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14: General Public License for more details.
  15: 
  16: You should have received a copy of the GNU General Public License
  17: along with GNU Classpath; see the file COPYING.  If not, write to the
  18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 USA.
  20: 
  21: Linking this library statically or dynamically with other modules is
  22: making a combined work based on this library.  Thus, the terms and
  23: conditions of the GNU General Public License cover the whole
  24: combination.
  25: 
  26: As a special exception, the copyright holders of this library give you
  27: permission to link this library with independent modules to produce an
  28: executable, regardless of the license terms of these independent
  29: modules, and to copy and distribute the resulting executable under
  30: terms of your choice, provided that you also meet, for each linked
  31: independent module, the terms and conditions of the license of that
  32: module.  An independent module is a module which is not derived from
  33: or based on this library.  If you modify this library, you may extend
  34: this exception to your version of the library, but you are not
  35: obligated to do so.  If you do not wish to do so, delete this
  36: exception statement from your version. */
  37: 
  38: package java.net;
  39: 
  40: import gnu.java.lang.CPStringBuilder;
  41: 
  42: import java.io.File;
  43: import java.io.IOException;
  44: 
  45: 
  46: /*
  47:  * Written using on-line Java Platform 1.2 API Specification, as well
  48:  * as "The Java Class Libraries", 2nd edition (Addison-Wesley, 1998).
  49:  * Status:  Believed complete and correct.
  50:  */
  51: 
  52: /**
  53:  * This class is the superclass of all URL protocol handlers.  The URL
  54:  * class loads the appropriate protocol handler to establish a connection
  55:  * to a (possibly) remote service (eg, "http", "ftp") and to do protocol
  56:  * specific parsing of URL's.  Refer to the URL class documentation for
  57:  * details on how that class locates and loads protocol handlers.
  58:  * <p>
  59:  * A protocol handler implementation should override the openConnection()
  60:  * method, and optionally override the parseURL() and toExternalForm()
  61:  * methods if necessary. (The default implementations will parse/write all
  62:  * URL's in the same form as http URL's).  A protocol  specific subclass
  63:  * of URLConnection will most likely need to be created as well.
  64:  * <p>
  65:  * Note that the instance methods in this class are called as if they
  66:  * were static methods.  That is, a URL object to act on is passed with
  67:  * every call rather than the caller assuming the URL is stored in an
  68:  * instance variable of the "this" object.
  69:  * <p>
  70:  * The methods in this class are protected and accessible only to subclasses.
  71:  * URLStreamConnection objects are intended for use by the URL class only,
  72:  * not by other classes (unless those classes are implementing protocols).
  73:  *
  74:  * @author Aaron M. Renn (arenn@urbanophile.com)
  75:  * @author Warren Levy (warrenl@cygnus.com)
  76:  *
  77:  * @see URL
  78:  */
  79: public abstract class URLStreamHandler
  80: {
  81:   /**
  82:    * Creates a URLStreamHander
  83:    */
  84:   public URLStreamHandler()
  85:   {
  86:   }
  87: 
  88:   /**
  89:    * Returns a URLConnection for the passed in URL.  Note that this should
  90:    * not actually create the connection to the (possibly) remote host, but
  91:    * rather simply return a URLConnection object.  The connect() method of
  92:    * URL connection is used to establish the actual connection, possibly
  93:    * after the caller sets up various connection options.
  94:    *
  95:    * @param url The URL to get a connection object for
  96:    *
  97:    * @return A URLConnection object for the given URL
  98:    *
  99:    * @exception IOException If an error occurs
 100:    */
 101:   protected abstract URLConnection openConnection(URL url)
 102:     throws IOException;
 103: 
 104:   /**
 105:    * This method parses the string passed in as a URL and set's the
 106:    * instance data fields in the URL object passed in to the various values
 107:    * parsed out of the string.  The start parameter is the position to start
 108:    * scanning the string.  This is usually the position after the ":" which
 109:    * terminates the protocol name.  The end parameter is the position to
 110:    * stop scanning.  This will be either the end of the String, or the
 111:    * position of the "#" character, which separates the "file" portion of
 112:    * the URL from the "anchor" portion.
 113:    * <p>
 114:    * This method assumes URL's are formatted like http protocol URL's, so
 115:    * subclasses that implement protocols with URL's the follow a different
 116:    * syntax should override this method.  The lone exception is that if
 117:    * the protocol name set in the URL is "file", this method will accept
 118:    * an empty hostname (i.e., "file:///"), which is legal for that protocol
 119:    *
 120:    * @param url The URL object in which to store the results
 121:    * @param spec The String-ized URL to parse
 122:    * @param start The position in the string to start scanning from
 123:    * @param end The position in the string to stop scanning
 124:    */
 125:   protected void parseURL(URL url, String spec, int start, int end)
 126:   {
 127:     String host = url.getHost();
 128:     int port = url.getPort();
 129:     String file = url.getFile();
 130:     String ref = url.getRef();
 131:     String userInfo = url.getUserInfo();
 132:     String authority = url.getAuthority();
 133:     String query = null;
 134: 
 135:     // On Windows we need to change \ to / for file URLs
 136:     char separator = File.separatorChar;
 137:     if (url.getProtocol().equals("file") && separator != '/')
 138:       {
 139:         file = file.replace(separator, '/');
 140:         spec = spec.replace(separator, '/');
 141:       }
 142: 
 143:     if (spec.regionMatches(start, "//", 0, 2))
 144:       {
 145:         String genuineHost;
 146:         int hostEnd;
 147:         int colon;
 148:         int at_host;
 149: 
 150:         start += 2;
 151:         int slash = spec.indexOf('/', start);
 152:         if (slash >= 0)
 153:           hostEnd = slash;
 154:         else
 155:           hostEnd = end;
 156: 
 157:         authority = host = spec.substring(start, hostEnd);
 158: 
 159:         // We first need a genuine host name (with userinfo).
 160:         // So we check for '@': if it's present check the port in the
 161:         // section after '@' in the other case check it in the full string.
 162:         // P.S.: We don't care having '@' at the beginning of the string.
 163:         if ((at_host = host.indexOf('@')) >= 0)
 164:           {
 165:             genuineHost = host.substring(at_host);
 166:             userInfo = host.substring(0, at_host);
 167:           }
 168:         else
 169:           genuineHost = host;
 170: 
 171:         // Look for optional port number.  It is valid for the non-port
 172:         // part of the host name to be null (e.g. a URL "http://:80").
 173:         // TBD: JDK 1.2 in this case sets host to null rather than "";
 174:         // this is undocumented and likely an unintended side effect in 1.2
 175:         // so we'll be simple here and stick with "". Note that
 176:         // "http://" or "http:///" produce a "" host in JDK 1.2.
 177:         if ((colon = genuineHost.indexOf(':')) >= 0)
 178:           {
 179:             try
 180:               {
 181:                 port = Integer.parseInt(genuineHost.substring(colon + 1));
 182:               }
 183:             catch (NumberFormatException e)
 184:               {
 185:                 // Ignore invalid port values; port is already set to u's
 186:                 // port.
 187:               }
 188: 
 189:             // Now we must cut the port number in the original string.
 190:             if (at_host >= 0)
 191:               host = host.substring(0, at_host + colon);
 192:             else
 193:               host = host.substring(0, colon);
 194:           }
 195:         file = null;
 196:         start = hostEnd;
 197:       }
 198:     else if (host == null)
 199:       host = "";
 200: 
 201:     if (file == null || file.length() == 0
 202:         || (start < end && spec.charAt(start) == '/'))
 203:       {
 204:         // No file context available; just spec for file.
 205:         // Or this is an absolute path name; ignore any file context.
 206:         file = spec.substring(start, end);
 207:         ref = null;
 208:       }
 209:     else if (start < end)
 210:       {
 211:         // Context is available, but only override it if there is a new file.
 212:         int lastSlash = file.lastIndexOf('/');
 213:         if (lastSlash < 0)
 214:           file = spec.substring(start, end);
 215:         else
 216:           file = (file.substring(0, lastSlash)
 217:                   + '/' + spec.substring(start, end));
 218: 
 219:         // For URLs constructed relative to a context, we
 220:         // need to canonicalise the file path.
 221:         file = canonicalizeFilename(file);
 222: 
 223:         ref = null;
 224:       }
 225: 
 226:     if (ref == null)
 227:       {
 228:         // Normally there should be no '#' in the file part,
 229:         // but we are nice.
 230:         int hash = file.indexOf('#');
 231:         if (hash != -1)
 232:           {
 233:             ref = file.substring(hash + 1, file.length());
 234:             file = file.substring(0, hash);
 235:           }
 236:       }
 237: 
 238:     // We care about the query tag only if there is no reference at all.
 239:     if (ref == null)
 240:       {
 241:           int queryTag = file.indexOf('?');
 242:           if (queryTag != -1)
 243:             {
 244:               query = file.substring(queryTag + 1);
 245:               file = file.substring(0, queryTag);
 246:             }
 247:       }
 248: 
 249:     // XXX - Classpath used to call PlatformHelper.toCanonicalForm() on
 250:     // the file part. It seems like overhead, but supposedly there is some
 251:     // benefit in windows based systems (it also lowercased the string).
 252:     setURL(url, url.getProtocol(), host, port, authority, userInfo, file, query, ref);
 253:   }
 254: 
 255:   /*
 256:    * Canonicalize a filename.
 257:    */
 258:   private static String canonicalizeFilename(String file)
 259:   {
 260:     // XXX - GNU Classpath has an implementation that might be more appropriate
 261:     // for Windows based systems (gnu.java.io.PlatformHelper.toCanonicalForm)
 262:     int index;
 263: 
 264:     // Replace "/./" with "/".  This probably isn't very efficient in
 265:     // the general case, but it's probably not bad most of the time.
 266:     while ((index = file.indexOf("/./")) >= 0)
 267:       file = file.substring(0, index) + file.substring(index + 2);
 268: 
 269:     // Process "/../" correctly.  This probably isn't very efficient in
 270:     // the general case, but it's probably not bad most of the time.
 271:     while ((index = file.indexOf("/../")) >= 0)
 272:       {
 273:         // Strip of the previous directory - if it exists.
 274:         int previous = file.lastIndexOf('/', index - 1);
 275:         if (previous >= 0)
 276:           file = file.substring(0, previous) + file.substring(index + 3);
 277:         else
 278:           break;
 279:       }
 280:     return file;
 281:   }
 282: 
 283:   /**
 284:    * Compares two URLs, excluding the fragment component
 285:    *
 286:    * @param url1 The first url
 287:    * @param url2 The second url to compare with the first
 288:    *
 289:    * @return True if both URLs point to the same file, false otherwise.
 290:    *
 291:    * @specnote Now protected
 292:    */
 293:   protected boolean sameFile(URL url1, URL url2)
 294:   {
 295:     if (url1 == url2)
 296:       return true;
 297: 
 298:     // This comparison is very conservative.  It assumes that any
 299:     // field can be null.
 300:     if (url1 == null || url2 == null)
 301:       return false;
 302:     int p1 = url1.getPort();
 303:     if (p1 == -1)
 304:       p1 = url1.ph.getDefaultPort();
 305:     int p2 = url2.getPort();
 306:     if (p2 == -1)
 307:       p2 = url2.ph.getDefaultPort();
 308:     if (p1 != p2)
 309:       return false;
 310:     String s1;
 311:     String s2;
 312:     s1 = url1.getProtocol();
 313:     s2 = url2.getProtocol();
 314:     if (s1 != s2 && (s1 == null || ! s1.equals(s2)))
 315:       return false;
 316:     s1 = url1.getHost();
 317:     s2 = url2.getHost();
 318:     if (s1 != s2 && (s1 == null || ! s1.equals(s2)))
 319:       return false;
 320:     s1 = canonicalizeFilename(url1.getFile());
 321:     s2 = canonicalizeFilename(url2.getFile());
 322:     if (s1 != s2 && (s1 == null || ! s1.equals(s2)))
 323:       return false;
 324:     return true;
 325:   }
 326: 
 327:   /**
 328:    * This methods sets the instance variables representing the various fields
 329:    * of the URL to the values passed in.
 330:    *
 331:    * @param u The URL to modify
 332:    * @param protocol The protocol to set
 333:    * @param host The host name to et
 334:    * @param port The port number to set
 335:    * @param file The filename to set
 336:    * @param ref The reference
 337:    *
 338:    * @exception SecurityException If the protocol handler of the URL is
 339:    * different from this one
 340:    *
 341:    * @deprecated 1.2 Please use
 342:    * #setURL(URL,String,String,int,String,String,String,String);
 343:    */
 344:   protected void setURL(URL u, String protocol, String host, int port,
 345:                         String file, String ref)
 346:   {
 347:     u.set(protocol, host, port, file, ref);
 348:   }
 349: 
 350:   /**
 351:    * Sets the fields of the URL argument to the indicated values
 352:    *
 353:    * @param u The URL to modify
 354:    * @param protocol The protocol to set
 355:    * @param host The host name to set
 356:    * @param port The port number to set
 357:    * @param authority The authority to set
 358:    * @param userInfo The user information to set
 359:    * @param path The path/filename to set
 360:    * @param query The query part to set
 361:    * @param ref The reference
 362:    *
 363:    * @exception SecurityException If the protocol handler of the URL is
 364:    * different from this one
 365:    */
 366:   protected void setURL(URL u, String protocol, String host, int port,
 367:                         String authority, String userInfo, String path,
 368:                         String query, String ref)
 369:   {
 370:     u.set(protocol, host, port, authority, userInfo, path, query, ref);
 371:   }
 372: 
 373:   /**
 374:    * This is the default method for computing whether two URLs are
 375:    * equivalent.  This method assumes that neither URL is null.
 376:    *
 377:    * @param url1 An URL object
 378:    * @param url2 Another URL object
 379:    *
 380:    * @return True if both given URLs are equal, false otherwise.
 381:    */
 382:   protected boolean equals(URL url1, URL url2)
 383:   {
 384:     // This comparison is very conservative.  It assumes that any
 385:     // field can be null.
 386:     int port1 = url1.getPort();
 387:     if (port1 == -1)
 388:       port1 = url1.getDefaultPort();
 389:     int port2 = url2.getPort();
 390:     if (port2 == -1)
 391:       port2 = url2.getDefaultPort();
 392:     // Note that we don't bother checking the 'authority'; it is
 393:     // redundant.
 394:     return (port1 == port2
 395:            && ((url1.getProtocol() == null && url2.getProtocol() == null)
 396:            || (url1.getProtocol() != null
 397:            && url1.getProtocol().equals(url2.getProtocol())))
 398:            && ((url1.getUserInfo() == null && url2.getUserInfo() == null)
 399:            || (url1.getUserInfo() != null
 400:            && url1.getUserInfo().equals(url2.getUserInfo())))
 401:            && ((url1.getHost() == null && url2.getHost() == null)
 402:            || (url1.getHost() != null && url1.getHost().equals(url2.getHost())))
 403:            && ((url1.getPath() == null && url2.getPath() == null)
 404:            || (url1.getPath() != null && url1.getPath().equals(url2.getPath())))
 405:            && ((url1.getQuery() == null && url2.getQuery() == null)
 406:            || (url1.getQuery() != null
 407:            && url1.getQuery().equals(url2.getQuery())))
 408:            && ((url1.getRef() == null && url2.getRef() == null)
 409:            || (url1.getRef() != null && url1.getRef().equals(url2.getRef()))));
 410:   }
 411: 
 412:   /**
 413:    * Compares the host components of two URLs.
 414:    *
 415:    * @param url1 The first URL.
 416:    * @param url2 The second URL.
 417:    *
 418:    * @return True if both URLs contain the same host.
 419:    */
 420:   protected boolean hostsEqual(URL url1, URL url2)
 421:   {
 422:     InetAddress addr1 = getHostAddress(url1);
 423:     InetAddress addr2 = getHostAddress(url2);
 424: 
 425:     if (addr1 != null && addr2 != null)
 426:       return addr1.equals(addr2);
 427: 
 428:     String host1 = url1.getHost();
 429:     String host2 = url2.getHost();
 430: 
 431:     if (host1 != null && host2 != null)
 432:       return host1.equalsIgnoreCase(host2);
 433: 
 434:     return host1 == null && host2 == null;
 435:   }
 436: 
 437:   /**
 438:    * Get the IP address of our host. An empty host field or a DNS failure will
 439:    * result in a null return.
 440:    *
 441:    * @param url The URL to return the host address for.
 442:    *
 443:    * @return The address of the hostname in url.
 444:    */
 445:   protected InetAddress getHostAddress(URL url)
 446:   {
 447:     String hostname = url.getHost();
 448: 
 449:     if (hostname.equals(""))
 450:       return null;
 451: 
 452:     try
 453:       {
 454:         return InetAddress.getByName(hostname);
 455:       }
 456:     catch (UnknownHostException e)
 457:       {
 458:         return null;
 459:       }
 460:   }
 461: 
 462:   /**
 463:    * Returns the default port for a URL parsed by this handler. This method is
 464:    * meant to be overidden by handlers with default port numbers.
 465:    *
 466:    * @return The default port number.
 467:    */
 468:   protected int getDefaultPort()
 469:   {
 470:     return -1;
 471:   }
 472: 
 473:   /**
 474:    * Provides the default hash calculation. May be overidden by handlers for
 475:    * other protocols that have different requirements for hashCode calculation.
 476:    *
 477:    * @param url The URL to calc the hashcode for.
 478:    *
 479:    * @return The hashcode for the given URL.
 480:    */
 481:   protected int hashCode(URL url)
 482:   {
 483:     return url.getProtocol().hashCode()
 484:            + ((url.getHost() == null) ? 0 : url.getHost().hashCode())
 485:            + url.getFile().hashCode() + url.getPort();
 486:   }
 487: 
 488:   /**
 489:    * This method converts a URL object into a String.  This method creates
 490:    * Strings in the mold of http URL's, so protocol handlers which use URL's
 491:    * that have a different syntax should override this method
 492:    *
 493:    * @param url The URL object to convert
 494:    *
 495:    * @return A string representation of the url
 496:    */
 497:   protected String toExternalForm(URL url)
 498:   {
 499:     String protocol;
 500:     String file;
 501:     String ref;
 502:     String authority;
 503: 
 504:     protocol = url.getProtocol();
 505:     authority = url.getAuthority();
 506:     if (authority == null)
 507:       authority = "";
 508: 
 509:     file = url.getFile();
 510:     ref = url.getRef();
 511: 
 512:     // Guess a reasonable size for the string buffer so we have to resize
 513:     // at most once.
 514:     int size = protocol.length() + authority.length() + file.length() + 24;
 515:     CPStringBuilder sb = new CPStringBuilder(size);
 516: 
 517:     if (protocol.length() > 0)
 518:       {
 519:         sb.append(protocol);
 520:         sb.append(":");
 521:       }
 522: 
 523:     // If we have superfluous leading slashes (that means, at least 2)
 524:     // we always add the authority component ("//" + host) to
 525:     // avoid ambiguity. Otherwise we would generate an URL like
 526:     // proto://home/foo
 527:     // where we meant:
 528:     // host: <empty> - file: //home/foo
 529:     // but URL spec says it is:
 530:     // host: home - file: /foo
 531:     if (authority.length() != 0 || file.startsWith("//") )
 532:       sb.append("//").append(authority).append(file);
 533:     else
 534:       sb.append(file);
 535: 
 536:     if (ref != null)
 537:       sb.append('#').append(ref);
 538: 
 539:     return sb.toString();
 540:   }
 541: }