001 /* URLConnection.java -- Abstract superclass for reading from URL's 002 Copyright (C) 1998, 2002, 2003, 2004, 2006 Free Software Foundation, Inc. 003 004 This file is part of GNU Classpath. 005 006 GNU Classpath is free software; you can redistribute it and/or modify 007 it under the terms of the GNU General Public License as published by 008 the Free Software Foundation; either version 2, or (at your option) 009 any later version. 010 011 GNU Classpath is distributed in the hope that it will be useful, but 012 WITHOUT ANY WARRANTY; without even the implied warranty of 013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 014 General Public License for more details. 015 016 You should have received a copy of the GNU General Public License 017 along with GNU Classpath; see the file COPYING. If not, write to the 018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 019 02110-1301 USA. 020 021 Linking this library statically or dynamically with other modules is 022 making a combined work based on this library. Thus, the terms and 023 conditions of the GNU General Public License cover the whole 024 combination. 025 026 As a special exception, the copyright holders of this library give you 027 permission to link this library with independent modules to produce an 028 executable, regardless of the license terms of these independent 029 modules, and to copy and distribute the resulting executable under 030 terms of your choice, provided that you also meet, for each linked 031 independent module, the terms and conditions of the license of that 032 module. An independent module is a module which is not derived from 033 or based on this library. If you modify this library, you may extend 034 this exception to your version of the library, but you are not 035 obligated to do so. If you do not wish to do so, delete this 036 exception statement from your version. */ 037 038 039 package java.net; 040 041 import gnu.classpath.SystemProperties; 042 043 import java.io.IOException; 044 import java.io.InputStream; 045 import java.io.OutputStream; 046 import java.security.AllPermission; 047 import java.security.Permission; 048 import java.text.ParsePosition; 049 import java.text.SimpleDateFormat; 050 import java.util.Collections; 051 import java.util.Date; 052 import java.util.List; 053 import java.util.Locale; 054 import java.util.Map; 055 import java.util.StringTokenizer; 056 057 /** 058 * Written using on-line Java Platform 1.2 API Specification, as well 059 * as "The Java Class Libraries", 2nd edition (Addison-Wesley, 1998). 060 * Status: One guessContentTypeFrom... methods not implemented. 061 * getContent method assumes content type from response; see comment there. 062 */ 063 /** 064 * This class models a connection that retrieves the information pointed 065 * to by a URL object. This is typically a connection to a remote node 066 * on the network, but could be a simple disk read. 067 * <p> 068 * A URLConnection object is normally created by calling the openConnection() 069 * method of a URL object. This method is somewhat misnamed because it does 070 * not actually open the connection. Instead, it return an unconnected 071 * instance of this object. The caller then has the opportunity to set 072 * various connection options prior to calling the actual connect() method. 073 * <p> 074 * After the connection has been opened, there are a number of methods in 075 * this class that access various attributes of the data, typically 076 * represented by headers sent in advance of the actual data itself. 077 * <p> 078 * Also of note are the getInputStream and getContent() methods which allow 079 * the caller to retrieve the actual data from the connection. Note that 080 * for some types of connections, writing is also allowed. The setDoOutput() 081 * method must be called prior to connecing in order to enable this, then 082 * the getOutputStream method called after the connection in order to 083 * obtain a stream to write the output to. 084 * <p> 085 * The getContent() method is of particular note. This method returns an 086 * Object that encapsulates the data returned. There is no way do determine 087 * the type of object that will be returned in advance. This is determined 088 * by the actual content handlers as described in the description of that 089 * method. 090 * 091 * @author Aaron M. Renn (arenn@urbanophile.com) 092 * @author Warren Levy (warrenl@cygnus.com) 093 */ 094 public abstract class URLConnection 095 { 096 /** 097 * This is an object that maps filenames to MIME types. The interface 098 * to do this is implemented by this class, so just create an empty 099 * instance and store it here. 100 */ 101 private static FileNameMap fileNameMap; 102 103 /** 104 * This is the ContentHandlerFactory set by the caller, if any 105 */ 106 private static ContentHandlerFactory factory; 107 108 /** 109 * This is the default value that will be used to determine whether or 110 * not user interaction should be allowed. 111 */ 112 private static boolean defaultAllowUserInteraction; 113 114 /** 115 * This is the default flag indicating whether or not to use caches to 116 * store the data returned from a server 117 */ 118 private static boolean defaultUseCaches = true; 119 120 /** 121 * Default internal content handler factory. 122 */ 123 private static ContentHandlerFactory defaultFactory 124 = new gnu.java.net.DefaultContentHandlerFactory(); 125 126 /** 127 * This variable determines whether or not interaction is allowed with 128 * the user. For example, to prompt for a username and password. 129 */ 130 protected boolean allowUserInteraction; 131 132 /** 133 * Indicates whether or not a connection has been established to the 134 * destination specified in the URL 135 */ 136 protected boolean connected; 137 138 /** 139 * Indicates whether or not input can be read from this URL 140 */ 141 protected boolean doInput = true; 142 143 /** 144 * Indicates whether or not output can be sent to this URL 145 */ 146 protected boolean doOutput; 147 148 /** 149 * If this flag is set, the protocol is allowed to cache data whenever 150 * it can (caching is not guaranteed). If it is not set, the protocol 151 * must a get a fresh copy of the data. 152 * <p> 153 * This field is set by the setUseCaches method and returned by the 154 * getUseCaches method. 155 * 156 * Its default value is that determined by the last invocation of 157 * setDefaultUseCaches 158 */ 159 protected boolean useCaches; 160 161 /** 162 * If this value is non-zero, then the connection will only attempt to 163 * fetch the document pointed to by the URL if the document has been 164 * modified more recently than the date set in this variable. That date 165 * should be specified as the number of seconds since 1/1/1970 GMT. 166 */ 167 protected long ifModifiedSince; 168 169 /** 170 * This is the URL associated with this connection 171 */ 172 protected URL url; 173 174 private static SimpleDateFormat[] dateFormats; 175 private static boolean dateformats_initialized; 176 177 /** 178 * The connection timeout period. 179 */ 180 private int connectTimeout; 181 182 /** 183 * The read timeout period. 184 */ 185 private int readTimeout; 186 187 /* Cached ParsePosition, used when parsing dates. */ 188 private ParsePosition position; 189 190 /** 191 * Creates a URL connection to a given URL. A real connection is not made. 192 * Use <code>connect()</code> to do this. 193 * 194 * @param url The Object to create the URL connection to 195 * 196 * @see URLConnection#connect() 197 */ 198 protected URLConnection(URL url) 199 { 200 // Set up all our instance variables 201 this.url = url; 202 allowUserInteraction = defaultAllowUserInteraction; 203 useCaches = defaultUseCaches; 204 } 205 206 /** 207 * Establishes the actual connection to the URL associated with this 208 * connection object 209 * 210 * @exception IOException if an error occurs 211 */ 212 public abstract void connect() throws IOException; 213 214 /** 215 * Returns the URL object associated with this connection 216 * 217 * @return The URL for this connection. 218 */ 219 public URL getURL() 220 { 221 return url; 222 } 223 224 /** 225 * Returns the connection timeout speed, in milliseconds, or zero if 226 * the timeout is infinite or not set. 227 * 228 * @return The timeout. 229 * 230 * @since 1.5 231 */ 232 public int getConnectTimeout() 233 { 234 return connectTimeout; 235 } 236 237 /** 238 * Set the connection timeout speed, in milliseconds, or zero if the timeout 239 * is to be considered infinite. Note that in certain socket 240 * implementations/platforms this method may not have any effect. 241 * 242 * Throws an <code>IllegalArgumentException</code> if timeout < 0. 243 * 244 * @param timeout the timeout, in milliseconds. 245 * 246 * @since 1.5 247 */ 248 public void setConnectTimeout(int timeout) 249 throws IllegalArgumentException 250 { 251 if( timeout < 0 ) 252 throw new IllegalArgumentException("Timeout must be 0 or positive."); 253 connectTimeout = timeout; 254 } 255 256 /** 257 * Returns the read timeout, in milliseconds, or zero if the timeout 258 * is infinite or not set. 259 * 260 * @return The timeout. 261 * 262 * @see #setReadTimeout 263 * 264 * @since 1.5 265 */ 266 public int getReadTimeout() 267 { 268 return readTimeout; 269 } 270 271 /** 272 * Set the read timeout, in milliseconds, or zero if the timeout 273 * is to be considered infinite. Note that in certain socket 274 * implementations/platforms this method may not have any effect. 275 * 276 * Throws an <code>IllegalArgumentException</code> if timeout < 0. 277 * 278 * @param timeout - The timeout, in milliseconds. 279 * 280 * @throws IllegalArgumentException if timeout is negative. 281 * 282 * @see #getReadTimeout 283 * 284 * @since 1.5 285 */ 286 public void setReadTimeout(int timeout) 287 throws IllegalArgumentException 288 { 289 if( timeout < 0 ) 290 throw new IllegalArgumentException("Timeout must be 0 or positive."); 291 readTimeout = timeout; 292 } 293 294 /** 295 * Returns the value of the content-length header field or -1 if the value 296 * is not known or not present. 297 * 298 * @return The content-length field 299 */ 300 public int getContentLength() 301 { 302 return getHeaderFieldInt("content-length", -1); 303 } 304 305 /** 306 * Returns the the content-type of the data pointed to by the URL. This 307 * method first tries looking for a content-type header. If that is not 308 * present, it attempts to use the file name to determine the content's 309 * MIME type. If that is unsuccessful, the method returns null. The caller 310 * may then still attempt to determine the MIME type by a call to 311 * guessContentTypeFromStream() 312 * 313 * @return The content MIME type 314 */ 315 public String getContentType() 316 { 317 return getHeaderField("content-type"); 318 } 319 320 /** 321 * Returns the value of the content-encoding field or null if it is not 322 * known or not present. 323 * 324 * @return The content-encoding field 325 */ 326 public String getContentEncoding() 327 { 328 return getHeaderField("content-encoding"); 329 } 330 331 /** 332 * Returns the value of the expires header or 0 if not known or present. 333 * If populated, the return value is number of seconds since midnight 334 * on 1/1/1970 GMT. 335 * 336 * @return The expiration time. 337 */ 338 public long getExpiration() 339 { 340 return getHeaderFieldDate("expires", 0L); 341 } 342 343 /** 344 * Returns the date of the document pointed to by the URL as reported in 345 * the date field of the header or 0 if the value is not present or not 346 * known. If populated, the return value is number of seconds since 347 * midnight on 1/1/1970 GMT. 348 * 349 * @return The document date 350 */ 351 public long getDate() 352 { 353 return getHeaderFieldDate("date", 0L); 354 } 355 356 /** 357 * Returns the value of the last-modified header field or 0 if not known known 358 * or not present. If populated, the return value is the number of seconds 359 * since midnight on 1/1/1970. 360 * 361 * @return The last modified time 362 */ 363 public long getLastModified() 364 { 365 return getHeaderFieldDate("last-modified", 0L); 366 } 367 368 /** 369 * Return a String representing the header value at the specified index. 370 * This allows the caller to walk the list of header fields. The analogous 371 * {@link #getHeaderField(int)} method allows access to the corresponding 372 * key for this header field 373 * 374 * @param index The index into the header field list to retrieve the value for 375 * 376 * @return The header value or null if index is past the end of the headers 377 */ 378 public String getHeaderField(int index) 379 { 380 // Subclasses for specific protocols override this. 381 return null; 382 } 383 384 /** 385 * Returns a String representing the value of the header field having 386 * the named key. Returns null if the header field does not exist. 387 * 388 * @param name The key of the header field 389 * 390 * @return The value of the header field as a String 391 */ 392 public String getHeaderField(String name) 393 { 394 // Subclasses for specific protocols override this. 395 return null; 396 } 397 398 /** 399 * Returns an unmodifiable Map containing all sent header fields. 400 * 401 * @return The map of header fields. The map consists of String keys with 402 * an unmodifiable List of String objects as value. 403 * 404 * @since 1.4 405 */ 406 public Map<String,List<String>> getHeaderFields() 407 { 408 // Subclasses for specific protocols override this. 409 return Collections.emptyMap(); 410 } 411 412 /** 413 * Returns the value of the named header field as an int. If the field 414 * is not present or cannot be parsed as an integer, the default value 415 * will be returned. 416 * 417 * @param name The header field key to lookup 418 * @param defaultValue The defaule value if the header field is not found 419 * or can't be parsed. 420 * 421 * @return The value of the header field or the default value if the field 422 * is missing or malformed 423 */ 424 public int getHeaderFieldInt(String name, int defaultValue) 425 { 426 String value = getHeaderField(name); 427 428 if (value == null) 429 return defaultValue; 430 431 try 432 { 433 return Integer.parseInt(value); 434 } 435 catch (NumberFormatException e) 436 { 437 return defaultValue; 438 } 439 } 440 441 /** 442 * Returns the value of the named header field as a date. This date will 443 * be the number of seconds since midnight 1/1/1970 GMT or the default 444 * value if the field is not present or cannot be converted to a date. 445 * 446 * @param name The name of the header field 447 * @param defaultValue The default date if the header field is not found 448 * or can't be converted. 449 * 450 * @return The date value of the header filed or the default value 451 * if the field is missing or malformed 452 */ 453 public long getHeaderFieldDate(String name, long defaultValue) 454 { 455 if (! dateformats_initialized) 456 initializeDateFormats(); 457 458 if (position == null) 459 position = new ParsePosition(0); 460 461 long result = defaultValue; 462 String str = getHeaderField(name); 463 464 if (str != null) 465 { 466 for (int i = 0; i < dateFormats.length; i++) 467 { 468 SimpleDateFormat df = dateFormats[i]; 469 position.setIndex(0); 470 position.setErrorIndex(0); 471 Date date = df.parse(str, position); 472 if (date != null) 473 return date.getTime(); 474 } 475 } 476 477 return result; 478 } 479 480 /** 481 * Returns a String representing the header key at the specified index. 482 * This allows the caller to walk the list of header fields. The analogous 483 * {@link #getHeaderField(int)} method allows access to the corresponding 484 * value for this tag. 485 * 486 * @param index The index into the header field list to retrieve the key for. 487 * 488 * @return The header field key or null if index is past the end 489 * of the headers. 490 */ 491 public String getHeaderFieldKey(int index) 492 { 493 // Subclasses for specific protocols override this. 494 return null; 495 } 496 497 /** 498 * This method returns the content of the document pointed to by the 499 * URL as an Object. The type of object depends on the MIME type of 500 * the object and particular content hander loaded. Most text type 501 * content handlers will return a subclass of 502 * <code>InputStream</code>. Images usually return a class that 503 * implements <code>ImageProducer</code>. There is not guarantee 504 * what type of object will be returned, however. 505 * 506 * <p>This class first determines the MIME type of the content, then 507 * creates a ContentHandler object to process the input. If the 508 * <code>ContentHandlerFactory</code> is set, then that object is 509 * called to load a content handler, otherwise a class called 510 * gnu.java.net.content.<content_type> is tried. If this 511 * handler does not exist, the method will simple return the 512 * <code>InputStream</code> returned by 513 * <code>getInputStream()</code>. Note that the default 514 * implementation of <code>getInputStream()</code> throws a 515 * <code>UnknownServiceException</code> so subclasses are encouraged 516 * to override this method.</p> 517 * 518 * @return the content 519 * 520 * @exception IOException If an error with the connection occurs. 521 * @exception UnknownServiceException If the protocol does not support the 522 * content type at all. 523 */ 524 public Object getContent() throws IOException 525 { 526 if (!connected) 527 connect(); 528 529 // FIXME: Doc indicates that other criteria should be applied as 530 // heuristics to determine the true content type, e.g. see 531 // guessContentTypeFromName() and guessContentTypeFromStream methods 532 // as well as FileNameMap class & fileNameMap field & get/set methods. 533 String type = getContentType(); 534 ContentHandler ch = getContentHandler(type); 535 536 if (ch != null) 537 return ch.getContent(this); 538 539 return getInputStream(); 540 } 541 542 /** 543 * Retrieves the content of this URLConnection 544 * 545 * @param classes The allowed classes for the content 546 * 547 * @return the content 548 * 549 * @exception IOException If an error occurs 550 * @exception UnknownServiceException If the protocol does not support the 551 * content type 552 */ 553 public Object getContent(Class[] classes) 554 throws IOException 555 { 556 if (! connected) 557 connect(); 558 String type = getContentType(); 559 ContentHandler ch = getContentHandler(type); 560 if (ch != null) 561 return ch.getContent(this, classes); 562 throw new UnknownServiceException("protocol does not support the content type"); 563 } 564 565 /** 566 * This method returns a <code>Permission</code> object representing the 567 * permissions required to access this URL. This method returns 568 * <code>java.security.AllPermission</code> by default. Subclasses should 569 * override it to return a more specific permission. For example, an 570 * HTTP URL should return an instance of <code>SocketPermission</code> 571 * for the appropriate host and port. 572 * <p> 573 * Note that because of items such as HTTP redirects, the permission 574 * object returned might be different before and after connecting. 575 * 576 * @return A Permission object 577 * 578 * @exception IOException If the computation of the permission requires 579 * network or file I/O and an exception occurs while computing it 580 */ 581 public Permission getPermission() throws IOException 582 { 583 // Subclasses may override this. 584 return new AllPermission(); 585 } 586 587 /** 588 * Returns an InputStream for this connection. As this default 589 * implementation returns null, subclasses should override this method 590 * 591 * @return An InputStream for this connection 592 * 593 * @exception IOException If an error occurs 594 * @exception UnknownServiceException If the protocol does not support input 595 */ 596 public InputStream getInputStream() throws IOException 597 { 598 // Subclasses for specific protocols override this. 599 throw new UnknownServiceException("Protocol " + url.getProtocol() 600 + " does not support input."); 601 } 602 603 /** 604 * Returns an OutputStream for this connection. As this default 605 * implementation returns null, subclasses should override this method 606 * 607 * @return An OutputStream for this connection 608 * 609 * @exception IOException If an error occurs 610 * @exception UnknownServiceException If the protocol does not support output 611 */ 612 public OutputStream getOutputStream() throws IOException 613 { 614 // Subclasses for specific protocols override this. 615 throw new UnknownServiceException("Protocol " + url.getProtocol() 616 + " does not support output."); 617 } 618 619 /** 620 * The methods prints the value of this object as a String by calling the 621 * toString() method of its associated URL. Overrides Object.toString() 622 * 623 * @return A String representation of this object 624 */ 625 public String toString() 626 { 627 return this.getClass().getName() + ":" + url.toString(); 628 } 629 630 /** 631 * Sets the value of a flag indicating whether or not input is going 632 * to be done for this connection. This default to true unless the 633 * doOutput flag is set to false, in which case this defaults to false. 634 * 635 * @param input <code>true</code> if input is to be done, 636 * <code>false</code> otherwise 637 * 638 * @exception IllegalStateException If already connected 639 */ 640 public void setDoInput(boolean input) 641 { 642 if (connected) 643 throw new IllegalStateException("Already connected"); 644 645 doInput = input; 646 } 647 648 /** 649 * Returns the value of a flag indicating whether or not input is going 650 * to be done for this connection. This default to true unless the 651 * doOutput flag is set to false, in which case this defaults to false. 652 * 653 * @return true if input is to be done, false otherwise 654 */ 655 public boolean getDoInput() 656 { 657 return doInput; 658 } 659 660 /** 661 * Sets a boolean flag indicating whether or not output will be done 662 * on this connection. The default value is false, so this method can 663 * be used to override the default 664 * 665 * @param output ture if output is to be done, false otherwise 666 * 667 * @exception IllegalStateException If already connected 668 */ 669 public void setDoOutput(boolean output) 670 { 671 if (connected) 672 throw new IllegalStateException("Already connected"); 673 674 doOutput = output; 675 } 676 677 /** 678 * Returns a boolean flag indicating whether or not output will be done 679 * on this connection. This defaults to false. 680 * 681 * @return true if output is to be done, false otherwise 682 */ 683 public boolean getDoOutput() 684 { 685 return doOutput; 686 } 687 688 /** 689 * Sets a boolean flag indicating whether or not user interaction is 690 * allowed for this connection. (For example, in order to prompt for 691 * username and password info. 692 * 693 * @param allow true if user interaction should be allowed, false otherwise. 694 * 695 * @exception IllegalStateException If already connected 696 */ 697 public void setAllowUserInteraction(boolean allow) 698 { 699 if (connected) 700 throw new IllegalStateException("Already connected"); 701 702 allowUserInteraction = allow; 703 } 704 705 /** 706 * Returns a boolean flag indicating whether or not user interaction is 707 * allowed for this connection. (For example, in order to prompt for 708 * username and password info. 709 * 710 * @return true if user interaction is allowed, false otherwise 711 */ 712 public boolean getAllowUserInteraction() 713 { 714 return allowUserInteraction; 715 } 716 717 /** 718 * Sets the default flag for whether or not interaction with a user 719 * is allowed. This will be used for all connections unless overridden 720 * 721 * @param allow true to allow user interaction, false otherwise 722 */ 723 public static void setDefaultAllowUserInteraction(boolean allow) 724 { 725 defaultAllowUserInteraction = allow; 726 } 727 728 /** 729 * Returns the default flag for whether or not interaction with a user 730 * is allowed. This will be used for all connections unless overridden 731 * 732 * @return true if user interaction is allowed, false otherwise 733 */ 734 public static boolean getDefaultAllowUserInteraction() 735 { 736 return defaultAllowUserInteraction; 737 } 738 739 /** 740 * Sets a boolean flag indicating whether or not caching will be used 741 * (if possible) to store data downloaded via the connection. 742 * 743 * @param usecaches The new value 744 * 745 * @exception IllegalStateException If already connected 746 */ 747 public void setUseCaches(boolean usecaches) 748 { 749 if (connected) 750 throw new IllegalStateException("Already connected"); 751 752 useCaches = usecaches; 753 } 754 755 /** 756 * Returns a boolean flag indicating whether or not caching will be used 757 * (if possible) to store data downloaded via the connection. 758 * 759 * @return true if caching should be used if possible, false otherwise 760 */ 761 public boolean getUseCaches() 762 { 763 return useCaches; 764 } 765 766 /** 767 * Sets the ifModified since instance variable. If this value is non 768 * zero and the underlying protocol supports it, the actual document will 769 * not be fetched unless it has been modified since this time. The value 770 * passed should be 0 if this feature is to be disabled or the time expressed 771 * as the number of seconds since midnight 1/1/1970 GMT otherwise. 772 * 773 * @param ifmodifiedsince The new value in milliseconds 774 * since January 1, 1970 GMT 775 * 776 * @exception IllegalStateException If already connected 777 */ 778 public void setIfModifiedSince(long ifmodifiedsince) 779 { 780 if (connected) 781 throw new IllegalStateException("Already connected"); 782 783 ifModifiedSince = ifmodifiedsince; 784 } 785 786 /** 787 * Returns the ifModified since instance variable. If this value is non 788 * zero and the underlying protocol supports it, the actual document will 789 * not be fetched unless it has been modified since this time. The value 790 * returned will be 0 if this feature is disabled or the time expressed 791 * as the number of seconds since midnight 1/1/1970 GMT otherwise 792 * 793 * @return The ifModifiedSince value 794 */ 795 public long getIfModifiedSince() 796 { 797 return ifModifiedSince; 798 } 799 800 /** 801 * Returns the default value used to determine whether or not caching 802 * of documents will be done when possible. 803 * 804 * @return true if caches will be used, false otherwise 805 */ 806 public boolean getDefaultUseCaches() 807 { 808 return defaultUseCaches; 809 } 810 811 /** 812 * Sets the default value used to determine whether or not caching 813 * of documents will be done when possible. 814 * 815 * @param use true to use caches if possible by default, false otherwise 816 */ 817 public void setDefaultUseCaches(boolean use) 818 { 819 defaultUseCaches = use; 820 } 821 822 /** 823 * Sets the value of the named request property. 824 * This method does overwrite the value of existing properties with 825 * the new value. 826 * 827 * @param key The name of the property 828 * @param value The value of the property 829 * 830 * @exception IllegalStateException If already connected 831 * @exception NullPointerException If key is null 832 * 833 * @see URLConnection#getRequestProperty(String key) 834 * @see URLConnection#addRequestProperty(String key, String value) 835 * 836 * @since 1.4 837 */ 838 public void setRequestProperty(String key, String value) 839 { 840 if (connected) 841 throw new IllegalStateException("Already connected"); 842 843 if (key == null) 844 throw new NullPointerException("key is null"); 845 846 // Do nothing unless overridden by subclasses that support setting 847 // header fields in the request. 848 } 849 850 /** 851 * Adds a new request property by a key/value pair. 852 * This method does not overwrite existing properties with the same key. 853 * 854 * @param key Key of the property to add 855 * @param value Value of the Property to add 856 * 857 * @exception IllegalStateException If already connected 858 * @exception NullPointerException If key is null 859 * 860 * @see URLConnection#getRequestProperty(String) 861 * @see URLConnection#setRequestProperty(String, String) 862 * 863 * @since 1.4 864 */ 865 public void addRequestProperty(String key, String value) 866 { 867 if (connected) 868 throw new IllegalStateException("Already connected"); 869 870 if (key == null) 871 throw new NullPointerException("key is null"); 872 873 // Do nothing unless overridden by subclasses that support adding 874 // header fields in the request. 875 } 876 877 /** 878 * Returns the value of the named request property. 879 * 880 * @param key The name of the property 881 * 882 * @return Value of the property, or <code>null</code> if key is null. 883 * 884 * @exception IllegalStateException If already connected 885 * 886 * @see URLConnection#setRequestProperty(String, String) 887 * @see URLConnection#addRequestProperty(String, String) 888 */ 889 public String getRequestProperty(String key) 890 { 891 if (connected) 892 throw new IllegalStateException("Already connected"); 893 894 // Overridden by subclasses that support reading header fields from the 895 // request. 896 return null; 897 } 898 899 /** 900 * Returns an unmodifiable Map containing the request properties. 901 * 902 * @return The map of properties. The map consists of String keys with an 903 * unmodifiable List of String objects as value. 904 * 905 * @exception IllegalStateException If already connected 906 * 907 * @since 1.4 908 */ 909 public Map<String,List<String>> getRequestProperties() 910 { 911 if (connected) 912 throw new IllegalStateException("Already connected"); 913 914 // Overridden by subclasses that support reading header fields from the 915 // request. 916 return Collections.emptyMap(); 917 } 918 919 /** 920 * Sets the default value of a request property. This will be used 921 * for all connections unless the value of the property is manually 922 * overridden. 923 * 924 * @param key The request property name the default is being set for 925 * @param value The value to set the default to 926 * 927 * @deprecated 1.3 The method setRequestProperty should be used instead. 928 * This method does nothing now. 929 * 930 * @see URLConnection#setRequestProperty(String, String) 931 */ 932 public static void setDefaultRequestProperty(String key, String value) 933 { 934 // This method does nothing since JDK 1.3. 935 } 936 937 /** 938 * Returns the default value of a request property. This will be used 939 * for all connections unless the value of the property is manually 940 * overridden. 941 * 942 * @param key The request property to return the default value of 943 * 944 * @return The value of the default property or null if not available 945 * 946 * @deprecated 1.3 The method getRequestProperty should be used instead. 947 * This method does nothing now. 948 * 949 * @see URLConnection#getRequestProperty(String) 950 */ 951 public static String getDefaultRequestProperty(String key) 952 { 953 // This method does nothing since JDK 1.3. 954 return null; 955 } 956 957 /** 958 * Sets the ContentHandlerFactory for an application. This can be called 959 * once and only once. If it is called again, then an Error is thrown. 960 * Unlike for other set factory methods, this one does not do a security 961 * check prior to setting the factory. 962 * 963 * @param factory The ContentHandlerFactory for this application 964 * 965 * @exception Error If the factory has already been defined 966 * @exception SecurityException If a security manager exists and its 967 * checkSetFactory method doesn't allow the operation 968 */ 969 public static synchronized void setContentHandlerFactory(ContentHandlerFactory factory) 970 { 971 if (URLConnection.factory != null) 972 throw new Error("ContentHandlerFactory already set"); 973 974 // Throw an exception if an extant security mgr precludes 975 // setting the factory. 976 SecurityManager s = System.getSecurityManager(); 977 if (s != null) 978 s.checkSetFactory(); 979 980 URLConnection.factory = factory; 981 } 982 983 /** 984 * Returns the MIME type of a file based on the name of the file. This 985 * works by searching for the file's extension in a list of file extensions 986 * and returning the MIME type associated with it. If no type is found, 987 * then a MIME type of "application/octet-stream" will be returned. 988 * 989 * @param filename The filename to determine the MIME type for 990 * 991 * @return The MIME type String 992 * 993 * @specnote public since JDK 1.4 994 */ 995 public static String guessContentTypeFromName(String filename) 996 { 997 return getFileNameMap().getContentTypeFor(filename.toLowerCase()); 998 } 999 1000 /** 1001 * Returns the MIME type of a stream based on the first few characters 1002 * at the beginning of the stream. This routine can be used to determine 1003 * the MIME type if a server is believed to be returning an incorrect 1004 * MIME type. This method returns "application/octet-stream" if it 1005 * cannot determine the MIME type. 1006 * <p> 1007 * NOTE: Overriding MIME types sent from the server can be obnoxious 1008 * to user's. See Internet Exploder 4 if you don't believe me. 1009 * 1010 * @param is The InputStream to determine the MIME type from 1011 * 1012 * @return The MIME type 1013 * 1014 * @exception IOException If an error occurs 1015 */ 1016 public static String guessContentTypeFromStream(InputStream is) 1017 throws IOException 1018 { 1019 String result = VMURLConnection.guessContentTypeFromStream(is); 1020 if (result == null) 1021 return "application/octet-stream"; 1022 return result; 1023 } 1024 1025 /** 1026 * This method returns the <code>FileNameMap</code> object being used 1027 * to decode MIME types by file extension. 1028 * 1029 * @return The <code>FileNameMap</code>. 1030 * 1031 * @since 1.2 1032 */ 1033 public static synchronized FileNameMap getFileNameMap() 1034 { 1035 // Delayed initialization. 1036 if (fileNameMap == null) 1037 fileNameMap = new MimeTypeMapper(); 1038 1039 return fileNameMap; 1040 } 1041 1042 /** 1043 * This method sets the <code>FileNameMap</code> object being used 1044 * to decode MIME types by file extension. 1045 * 1046 * @param map The <code>FileNameMap</code>. 1047 * 1048 * @exception SecurityException If a security manager exists and its 1049 * checkSetFactory method doesn't allow the operation 1050 * 1051 * @since 1.2 1052 */ 1053 public static synchronized void setFileNameMap(FileNameMap map) 1054 { 1055 // Throw an exception if an extant security manager precludes 1056 // setting the factory. 1057 SecurityManager s = System.getSecurityManager(); 1058 if (s != null) 1059 s.checkSetFactory(); 1060 1061 fileNameMap = map; 1062 } 1063 1064 private ContentHandler getContentHandler(String contentType) 1065 { 1066 // No content type so just handle it as the default. 1067 if (contentType == null || contentType.equals("")) 1068 return null; 1069 1070 ContentHandler handler = null; 1071 1072 // If a non-default factory has been set, use it. 1073 if (factory != null) 1074 handler = factory.createContentHandler(contentType); 1075 1076 // Now try default factory. Using this factory to instantiate built-in 1077 // content handlers is preferable 1078 if (handler == null) 1079 handler = defaultFactory.createContentHandler(contentType); 1080 1081 // User-set factory has not returned a handler. Use the default search 1082 // algorithm. 1083 if (handler == null) 1084 { 1085 // Get the list of packages to check and append our default handler 1086 // to it, along with the JDK specified default as a last resort. 1087 // Except in very unusual environments the JDK specified one shouldn't 1088 // ever be needed (or available). 1089 String propVal = SystemProperties.getProperty("java.content.handler.pkgs"); 1090 propVal = (((propVal == null) ? "" : (propVal + "|")) 1091 + "gnu.java.net.content|sun.net.www.content"); 1092 1093 // Deal with "Content-Type: text/html; charset=ISO-8859-1". 1094 int parameterBegin = contentType.indexOf(';'); 1095 if (parameterBegin >= 1) 1096 contentType = contentType.substring(0, parameterBegin); 1097 contentType = contentType.trim(); 1098 1099 // Replace the '/' character in the content type with '.' and 1100 // all other non-alphabetic, non-numeric characters with '_'. 1101 char[] cArray = contentType.toCharArray(); 1102 for (int i = 0; i < cArray.length; i++) 1103 { 1104 if (cArray[i] == '/') 1105 cArray[i] = '.'; 1106 else if (! ((cArray[i] >= 'A' && cArray[i] <= 'Z') || 1107 (cArray[i] >= 'a' && cArray[i] <= 'z') || 1108 (cArray[i] >= '0' && cArray[i] <= '9'))) 1109 cArray[i] = '_'; 1110 } 1111 String contentClass = new String(cArray); 1112 1113 // See if a class of this content type exists in any of the packages. 1114 StringTokenizer pkgPrefix = new StringTokenizer(propVal, "|"); 1115 do 1116 { 1117 String facName = pkgPrefix.nextToken() + "." + contentClass; 1118 try 1119 { 1120 handler = 1121 (ContentHandler) Class.forName(facName).newInstance(); 1122 } 1123 catch (Exception e) 1124 { 1125 // Can't instantiate; handler still null, go on to next element. 1126 } 1127 } while (handler == null && pkgPrefix.hasMoreTokens()); 1128 } 1129 1130 return handler; 1131 } 1132 1133 // We don't put these in a static initializer, because it creates problems 1134 // with initializer co-dependency: SimpleDateFormat's constructors 1135 // eventually depend on URLConnection (via the java.text.*Symbols classes). 1136 private static synchronized void initializeDateFormats() 1137 { 1138 if (dateformats_initialized) 1139 return; 1140 1141 Locale locale = new Locale("En", "Us", "Unix"); 1142 dateFormats = new SimpleDateFormat[3]; 1143 dateFormats[0] = 1144 new SimpleDateFormat("EEE, dd MMM yyyy hh:mm:ss 'GMT'", locale); 1145 dateFormats[1] = 1146 new SimpleDateFormat("EEEE, dd-MMM-yy hh:mm:ss 'GMT'", locale); 1147 dateFormats[2] = new SimpleDateFormat("EEE MMM d hh:mm:ss yyyy", locale); 1148 dateformats_initialized = true; 1149 } 1150 }