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