001 /* HttpURLConnection.java -- Subclass of communications links using 002 Hypertext Transfer Protocol. 003 Copyright (C) 1998, 1999, 2000, 2002, 2003 Free Software Foundation 004 005 This file is part of GNU Classpath. 006 007 GNU Classpath is free software; you can redistribute it and/or modify 008 it under the terms of the GNU General Public License as published by 009 the Free Software Foundation; either version 2, or (at your option) 010 any later version. 011 012 GNU Classpath is distributed in the hope that it will be useful, but 013 WITHOUT ANY WARRANTY; without even the implied warranty of 014 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 015 General Public License for more details. 016 017 You should have received a copy of the GNU General Public License 018 along with GNU Classpath; see the file COPYING. If not, write to the 019 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 020 02110-1301 USA. 021 022 Linking this library statically or dynamically with other modules is 023 making a combined work based on this library. Thus, the terms and 024 conditions of the GNU General Public License cover the whole 025 combination. 026 027 As a special exception, the copyright holders of this library give you 028 permission to link this library with independent modules to produce an 029 executable, regardless of the license terms of these independent 030 modules, and to copy and distribute the resulting executable under 031 terms of your choice, provided that you also meet, for each linked 032 independent module, the terms and conditions of the license of that 033 module. An independent module is a module which is not derived from 034 or based on this library. If you modify this library, you may extend 035 this exception to your version of the library, but you are not 036 obligated to do so. If you do not wish to do so, delete this 037 exception statement from your version. */ 038 039 package java.net; 040 041 import java.io.IOException; 042 import java.io.InputStream; 043 import java.io.PushbackInputStream; 044 import java.security.Permission; 045 046 047 /* 048 * Written using on-line Java Platform 1.2 API Specification, as well 049 * as "The Java Class Libraries", 2nd edition (Addison-Wesley, 1998). 050 * Status: Believed complete and correct. 051 */ 052 053 /** 054 * This class provides a common abstract implementation for those 055 * URL connection classes that will connect using the HTTP protocol. 056 * In addition to the functionality provided by the URLConnection 057 * class, it defines constants for HTTP return code values and 058 * methods for setting the HTTP request method and determining whether 059 * or not to follow redirects. 060 * 061 * @since 1.1 062 * 063 * @author Warren Levy (warrenl@cygnus.com) 064 * @author Aaron M. Renn (arenn@urbanophile.com) 065 */ 066 public abstract class HttpURLConnection extends URLConnection 067 { 068 /* HTTP Success Response Codes */ 069 070 /** 071 * Indicates that the client may continue with its request. This value 072 * is specified as part of RFC 2068 but was not included in Sun's JDK, so 073 * beware of using this value 074 */ 075 static final int HTTP_CONTINUE = 100; 076 077 /** 078 * Indicates the request succeeded. 079 */ 080 public static final int HTTP_OK = 200; 081 082 /** 083 * The requested resource has been created. 084 */ 085 public static final int HTTP_CREATED = 201; 086 087 /** 088 * The request has been accepted for processing but has not completed. 089 * There is no guarantee that the requested action will actually ever 090 * be completed succesfully, but everything is ok so far. 091 */ 092 public static final int HTTP_ACCEPTED = 202; 093 094 /** 095 * The meta-information returned in the header is not the actual data 096 * from the original server, but may be from a local or other copy. 097 * Normally this still indicates a successful completion. 098 */ 099 public static final int HTTP_NOT_AUTHORITATIVE = 203; 100 101 /** 102 * The server performed the request, but there is no data to send 103 * back. This indicates that the user's display should not be changed. 104 */ 105 public static final int HTTP_NO_CONTENT = 204; 106 107 /** 108 * The server performed the request, but there is no data to sent back, 109 * however, the user's display should be "reset" to clear out any form 110 * fields entered. 111 */ 112 public static final int HTTP_RESET = 205; 113 114 /** 115 * The server completed the partial GET request for the resource. 116 */ 117 public static final int HTTP_PARTIAL = 206; 118 119 /* HTTP Redirection Response Codes */ 120 121 /** 122 * There is a list of choices available for the requested resource. 123 */ 124 public static final int HTTP_MULT_CHOICE = 300; 125 126 /** 127 * The resource has been permanently moved to a new location. 128 */ 129 public static final int HTTP_MOVED_PERM = 301; 130 131 /** 132 * The resource requested has been temporarily moved to a new location. 133 */ 134 public static final int HTTP_MOVED_TEMP = 302; 135 136 /** 137 * The response to the request issued is available at another location. 138 */ 139 public static final int HTTP_SEE_OTHER = 303; 140 141 /** 142 * The document has not been modified since the criteria specified in 143 * a conditional GET. 144 */ 145 public static final int HTTP_NOT_MODIFIED = 304; 146 147 /** 148 * The requested resource needs to be accessed through a proxy. 149 */ 150 public static final int HTTP_USE_PROXY = 305; 151 152 /* HTTP Client Error Response Codes */ 153 154 /** 155 * The request was misformed or could not be understood. 156 */ 157 public static final int HTTP_BAD_REQUEST = 400; 158 159 /** 160 * The request made requires user authorization. Try again with 161 * a correct authentication header. 162 */ 163 public static final int HTTP_UNAUTHORIZED = 401; 164 165 /** 166 * Code reserved for future use - I hope way in the future. 167 */ 168 public static final int HTTP_PAYMENT_REQUIRED = 402; 169 170 /** 171 * There is no permission to access the requested resource. 172 */ 173 public static final int HTTP_FORBIDDEN = 403; 174 175 /** 176 * The requested resource was not found. 177 */ 178 public static final int HTTP_NOT_FOUND = 404; 179 180 /** 181 * The specified request method is not allowed for this resource. 182 */ 183 public static final int HTTP_BAD_METHOD = 405; 184 185 /** 186 * Based on the input headers sent, the resource returned in response 187 * to the request would not be acceptable to the client. 188 */ 189 public static final int HTTP_NOT_ACCEPTABLE = 406; 190 191 /** 192 * The client must authenticate with a proxy prior to attempting this 193 * request. 194 */ 195 public static final int HTTP_PROXY_AUTH = 407; 196 197 /** 198 * The request timed out. 199 */ 200 public static final int HTTP_CLIENT_TIMEOUT = 408; 201 202 /** 203 * There is a conflict between the current state of the resource and the 204 * requested action. 205 */ 206 public static final int HTTP_CONFLICT = 409; 207 208 /** 209 * The requested resource is no longer available. This ususally indicates 210 * a permanent condition. 211 */ 212 public static final int HTTP_GONE = 410; 213 214 /** 215 * A Content-Length header is required for this request, but was not 216 * supplied. 217 */ 218 public static final int HTTP_LENGTH_REQUIRED = 411; 219 220 /** 221 * A client specified pre-condition was not met on the server. 222 */ 223 public static final int HTTP_PRECON_FAILED = 412; 224 225 /** 226 * The request sent was too large for the server to handle. 227 */ 228 public static final int HTTP_ENTITY_TOO_LARGE = 413; 229 230 /** 231 * The name of the resource specified was too long. 232 */ 233 public static final int HTTP_REQ_TOO_LONG = 414; 234 235 /** 236 * The request is in a format not supported by the requested resource. 237 */ 238 public static final int HTTP_UNSUPPORTED_TYPE = 415; 239 240 /* HTTP Server Error Response Codes */ 241 242 /** 243 * This error code indicates that some sort of server error occurred. 244 * 245 * @deprecated 246 */ 247 public static final int HTTP_SERVER_ERROR = 500; 248 249 /** 250 * The server encountered an unexpected error (such as a CGI script crash) 251 * that prevents the request from being fulfilled. 252 */ 253 public static final int HTTP_INTERNAL_ERROR = 500; 254 255 /** 256 * The server does not support the requested functionality. 257 * @since 1.3 258 */ 259 public static final int HTTP_NOT_IMPLEMENTED = 501; 260 261 /** 262 * The proxy encountered a bad response from the server it was proxy-ing for 263 */ 264 public static final int HTTP_BAD_GATEWAY = 502; 265 266 /** 267 * The HTTP service is not availalble, such as because it is overloaded 268 * and does not want additional requests. 269 */ 270 public static final int HTTP_UNAVAILABLE = 503; 271 272 /** 273 * The proxy timed out getting a reply from the remote server it was 274 * proxy-ing for. 275 */ 276 public static final int HTTP_GATEWAY_TIMEOUT = 504; 277 278 /** 279 * This server does not support the protocol version requested. 280 */ 281 public static final int HTTP_VERSION = 505; 282 283 // Non-HTTP response static variables 284 285 /** 286 * Flag to indicate whether or not redirects should be automatically 287 * followed by default. 288 */ 289 private static boolean followRedirects = true; 290 291 /** 292 * This is a list of valid request methods, separated by "|" characters. 293 */ 294 private static final String valid_methods = 295 "|GET|POST|HEAD|OPTIONS|PUT|DELETE|TRACE|"; 296 297 // Instance Variables 298 299 /** 300 * The requested method in use for this connection. Default is GET. 301 */ 302 protected String method = "GET"; 303 304 /** 305 * The response code received from the server 306 */ 307 protected int responseCode = -1; 308 309 /** 310 * The response message string received from the server. 311 */ 312 protected String responseMessage; 313 314 /** 315 * If this instance should follow redirect requests. 316 */ 317 protected boolean instanceFollowRedirects = followRedirects; 318 319 /** 320 * Whether we already got a valid response code for this connection. 321 * Used by <code>getResponseCode()</code> and 322 * <code>getResponseMessage()</code>. 323 */ 324 private boolean gotResponseVals; 325 326 /** 327 * Create an HttpURLConnection for the specified URL 328 * 329 * @param url The URL to create this connection for. 330 */ 331 protected HttpURLConnection(URL url) 332 { 333 super(url); 334 } 335 336 /** 337 * Closes the connection to the server. 338 */ 339 public abstract void disconnect(); 340 341 /** 342 * Returns a boolean indicating whether or not this connection is going 343 * through a proxy 344 * 345 * @return true if through a proxy, false otherwise 346 */ 347 public abstract boolean usingProxy(); 348 349 /** 350 * Sets whether HTTP redirects (requests with response code 3xx) should be 351 * automatically followed by this class. True by default 352 * 353 * @param set true if redirects should be followed, false otherwis. 354 * 355 * @exception SecurityException If a security manager exists and its 356 * checkSetFactory method doesn't allow the operation 357 */ 358 public static void setFollowRedirects(boolean set) 359 { 360 // Throw an exception if an extant security mgr precludes 361 // setting the factory. 362 SecurityManager s = System.getSecurityManager(); 363 if (s != null) 364 s.checkSetFactory(); 365 366 followRedirects = set; 367 } 368 369 /** 370 * Returns a boolean indicating whether or not HTTP redirects will 371 * automatically be followed or not. 372 * 373 * @return true if redirects will be followed, false otherwise 374 */ 375 public static boolean getFollowRedirects() 376 { 377 return followRedirects; 378 } 379 380 /** 381 * Returns the value of this HttpURLConnection's instanceFollowRedirects 382 * field 383 * 384 * @return true if following redirects is enabled, false otherwise 385 */ 386 public boolean getInstanceFollowRedirects() 387 { 388 return instanceFollowRedirects; 389 } 390 391 /** 392 * Sets the value of this HttpURLConnection's instanceFollowRedirects field 393 * 394 * @param follow true to enable following redirects, false otherwise 395 */ 396 public void setInstanceFollowRedirects(boolean follow) 397 { 398 instanceFollowRedirects = follow; 399 } 400 401 /** 402 * Set the method for the URL request, one of: 403 * GET POST HEAD OPTIONS PUT DELETE TRACE are legal 404 * 405 * @param method the method to use 406 * 407 * @exception ProtocolException If the method cannot be reset or if the 408 * requested method isn't valid for HTTP 409 */ 410 public void setRequestMethod(String method) throws ProtocolException 411 { 412 if (connected) 413 throw new ProtocolException("Already connected"); 414 415 method = method.toUpperCase(); 416 if (valid_methods.indexOf("|" + method + "|") != -1) 417 this.method = method; 418 else 419 throw new ProtocolException("Invalid HTTP request method: " + method); 420 } 421 422 /** 423 * The request method currently in use for this connection. 424 * 425 * @return The request method 426 */ 427 public String getRequestMethod() 428 { 429 return method; 430 } 431 432 /** 433 * Gets the status code from an HTTP response message, or -1 if 434 * the response code could not be determined. 435 * Note that all valid response codes have class variables 436 * defined for them in this class. 437 * 438 * @return The response code 439 * 440 * @exception IOException If an error occurs 441 */ 442 public int getResponseCode() throws IOException 443 { 444 if (! gotResponseVals) 445 getResponseVals(); 446 return responseCode; 447 } 448 449 /** 450 * Gets the HTTP response message, if any, returned along with the 451 * response code from a server. Null if no response message was set 452 * or an error occured while connecting. 453 * 454 * @return The response message 455 * 456 * @exception IOException If an error occurs 457 */ 458 public String getResponseMessage() throws IOException 459 { 460 if (! gotResponseVals) 461 getResponseVals(); 462 return responseMessage; 463 } 464 465 private void getResponseVals() throws IOException 466 { 467 // getHeaderField() will connect for us, but do it here first in 468 // order to pick up IOExceptions. 469 if (! connected) 470 connect(); 471 472 gotResponseVals = true; 473 474 // If responseCode not yet explicitly set by subclass 475 if (responseCode == -1) 476 { 477 // Response is the first header received from the connection. 478 String respField = getHeaderField(0); 479 480 if (respField == null || ! respField.startsWith("HTTP/")) 481 { 482 // Set to default values on failure. 483 responseCode = -1; 484 responseMessage = null; 485 return; 486 } 487 488 int firstSpc; 489 int nextSpc; 490 firstSpc = respField.indexOf(' '); 491 nextSpc = respField.indexOf(' ', firstSpc + 1); 492 responseMessage = respField.substring(nextSpc + 1); 493 String codeStr = respField.substring(firstSpc + 1, nextSpc); 494 try 495 { 496 responseCode = Integer.parseInt(codeStr); 497 } 498 catch (NumberFormatException e) 499 { 500 // Set to default values on failure. 501 responseCode = -1; 502 responseMessage = null; 503 } 504 } 505 } 506 507 /** 508 * Returns a permission object representing the permission necessary to make 509 * the connection represented by this object 510 * 511 * @return the permission necessary for this connection 512 * 513 * @exception IOException If an error occurs 514 */ 515 public Permission getPermission() throws IOException 516 { 517 URL url = getURL(); 518 String host = url.getHost(); 519 int port = url.getPort(); 520 if (port == -1) 521 port = 80; 522 523 host = host + ":" + port; 524 525 return new SocketPermission(host, "connect"); 526 } 527 528 /** 529 * This method allows the caller to retrieve any data that might have 530 * been sent despite the fact that an error occurred. For example, the 531 * HTML page sent along with a 404 File Not Found error. If the socket 532 * is not connected, or if no error occurred or no data was returned, 533 * this method returns <code>null</code>. 534 * 535 * @return An <code>InputStream</code> for reading error data. 536 */ 537 public InputStream getErrorStream() 538 { 539 if (! connected) 540 return null; 541 542 int code; 543 try 544 { 545 code = getResponseCode(); 546 } 547 catch (IOException e) 548 { 549 code = -1; 550 } 551 552 if (code == -1) 553 return null; 554 555 if (((code / 100) != 4) || ((code / 100) != 5)) 556 return null; 557 558 try 559 { 560 PushbackInputStream pbis = new PushbackInputStream(getInputStream()); 561 562 int i = pbis.read(); 563 if (i == -1) 564 return null; 565 566 pbis.unread(i); 567 return pbis; 568 } 569 catch (IOException e) 570 { 571 return null; 572 } 573 } 574 575 /** 576 * Returns the value of the named field parsed as date 577 * 578 * @param key the key of the header field 579 * @param value the default value if the header field is not present 580 * 581 * @return the value of the header field 582 */ 583 public long getHeaderFieldDate(String key, long value) 584 { 585 // FIXME: implement this correctly 586 // http://www.w3.org/Protocols/HTTP-NG/ng-notes.txt 587 return super.getHeaderFieldDate(key, value); 588 } 589 }