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    }