libjava/java/net/HttpURLConnection.java

   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 package java.net;
  40
  41 import java.io.IOException;
  42 import java.io.InputStream;
  43 import java.io.PushbackInputStream;
  44 import java.security.Permission;
  45
  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   /* 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 }