001/* HttpURLConnection.java -- Subclass of communications links using
002   Hypertext Transfer Protocol.
003   Copyright (C) 1998, 1999, 2000, 2002, 2003  Free Software Foundation
004
005This file is part of GNU Classpath.
006
007GNU Classpath is free software; you can redistribute it and/or modify
008it under the terms of the GNU General Public License as published by
009the Free Software Foundation; either version 2, or (at your option)
010any later version.
011
012GNU Classpath is distributed in the hope that it will be useful, but
013WITHOUT ANY WARRANTY; without even the implied warranty of
014MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
015General Public License for more details.
016
017You should have received a copy of the GNU General Public License
018along with GNU Classpath; see the file COPYING.  If not, write to the
019Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02002110-1301 USA.
021
022Linking this library statically or dynamically with other modules is
023making a combined work based on this library.  Thus, the terms and
024conditions of the GNU General Public License cover the whole
025combination.
026
027As a special exception, the copyright holders of this library give you
028permission to link this library with independent modules to produce an
029executable, regardless of the license terms of these independent
030modules, and to copy and distribute the resulting executable under
031terms of your choice, provided that you also meet, for each linked
032independent module, the terms and conditions of the license of that
033module.  An independent module is a module which is not derived from
034or based on this library.  If you modify this library, you may extend
035this exception to your version of the library, but you are not
036obligated to do so.  If you do not wish to do so, delete this
037exception statement from your version. */
038
039package java.net;
040
041import java.io.IOException;
042import java.io.InputStream;
043import java.io.PushbackInputStream;
044import 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 */
066public 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}