java.net

Class HttpURLConnection

Known Direct Subclasses:
HttpsURLConnection

public abstract class HttpURLConnection
extends URLConnection

This class provides a common abstract implementation for those URL connection classes that will connect using the HTTP protocol. In addition to the functionality provided by the URLConnection class, it defines constants for HTTP return code values and methods for setting the HTTP request method and determining whether or not to follow redirects.
Since:
1.1

Field Summary

static int
HTTP_ACCEPTED
The request has been accepted for processing but has not completed.
static int
HTTP_BAD_GATEWAY
The proxy encountered a bad response from the server it was proxy-ing for
static int
HTTP_BAD_METHOD
The specified request method is not allowed for this resource.
static int
HTTP_BAD_REQUEST
The request was misformed or could not be understood.
static int
HTTP_CLIENT_TIMEOUT
The request timed out.
static int
HTTP_CONFLICT
There is a conflict between the current state of the resource and the requested action.
static int
HTTP_CREATED
The requested resource has been created.
static int
HTTP_ENTITY_TOO_LARGE
The request sent was too large for the server to handle.
static int
HTTP_FORBIDDEN
There is no permission to access the requested resource.
static int
HTTP_GATEWAY_TIMEOUT
The proxy timed out getting a reply from the remote server it was proxy-ing for.
static int
HTTP_GONE
The requested resource is no longer available.
static int
HTTP_INTERNAL_ERROR
The server encountered an unexpected error (such as a CGI script crash) that prevents the request from being fulfilled.
static int
HTTP_LENGTH_REQUIRED
A Content-Length header is required for this request, but was not supplied.
static int
HTTP_MOVED_PERM
The resource has been permanently moved to a new location.
static int
HTTP_MOVED_TEMP
The resource requested has been temporarily moved to a new location.
static int
HTTP_MULT_CHOICE
There is a list of choices available for the requested resource.
static int
HTTP_NOT_ACCEPTABLE
Based on the input headers sent, the resource returned in response to the request would not be acceptable to the client.
static int
HTTP_NOT_AUTHORITATIVE
The meta-information returned in the header is not the actual data from the original server, but may be from a local or other copy.
static int
HTTP_NOT_FOUND
The requested resource was not found.
static int
HTTP_NOT_IMPLEMENTED
The server does not support the requested functionality.
static int
HTTP_NOT_MODIFIED
The document has not been modified since the criteria specified in a conditional GET.
static int
HTTP_NO_CONTENT
The server performed the request, but there is no data to send back.
static int
HTTP_OK
Indicates the request succeeded.
static int
HTTP_PARTIAL
The server completed the partial GET request for the resource.
static int
HTTP_PAYMENT_REQUIRED
Code reserved for future use - I hope way in the future.
static int
HTTP_PRECON_FAILED
A client specified pre-condition was not met on the server.
static int
HTTP_PROXY_AUTH
The client must authenticate with a proxy prior to attempting this request.
static int
HTTP_REQ_TOO_LONG
The name of the resource specified was too long.
static int
HTTP_RESET
The server performed the request, but there is no data to sent back, however, the user's display should be "reset" to clear out any form fields entered.
static int
HTTP_SEE_OTHER
The response to the request issued is available at another location.
static int
HTTP_SERVER_ERROR
Deprecated.
static int
HTTP_UNAUTHORIZED
The request made requires user authorization.
static int
HTTP_UNAVAILABLE
The HTTP service is not availalble, such as because it is overloaded and does not want additional requests.
static int
HTTP_UNSUPPORTED_TYPE
The request is in a format not supported by the requested resource.
static int
HTTP_USE_PROXY
The requested resource needs to be accessed through a proxy.
static int
HTTP_VERSION
This server does not support the protocol version requested.
protected boolean
instanceFollowRedirects
If this instance should follow redirect requests.
protected String
method
The requested method in use for this connection.
protected int
responseCode
The response code received from the server
protected String
responseMessage
The response message string received from the server.

Fields inherited from class java.net.URLConnection

allowUserInteraction, connected, doInput, doOutput, ifModifiedSince, url, useCaches

Constructor Summary

HttpURLConnection(URL url)
Create an HttpURLConnection for the specified URL

Method Summary

abstract void
disconnect()
Closes the connection to the server.
InputStream
getErrorStream()
This method allows the caller to retrieve any data that might have been sent despite the fact that an error occurred.
static boolean
getFollowRedirects()
Returns a boolean indicating whether or not HTTP redirects will automatically be followed or not.
long
getHeaderFieldDate(String key, long value)
Returns the value of the named field parsed as date
boolean
getInstanceFollowRedirects()
Returns the value of this HttpURLConnection's instanceFollowRedirects field
Permission
getPermission()
Returns a permission object representing the permission necessary to make the connection represented by this object
String
getRequestMethod()
The request method currently in use for this connection.
int
getResponseCode()
Gets the status code from an HTTP response message, or -1 if the response code could not be determined.
String
getResponseMessage()
Gets the HTTP response message, if any, returned along with the response code from a server.
static void
setFollowRedirects(boolean set)
Sets whether HTTP redirects (requests with response code 3xx) should be automatically followed by this class.
void
setInstanceFollowRedirects(boolean follow)
Sets the value of this HttpURLConnection's instanceFollowRedirects field
void
setRequestMethod(String method)
Set the method for the URL request, one of: GET POST HEAD OPTIONS PUT DELETE TRACE are legal
abstract boolean
usingProxy()
Returns a boolean indicating whether or not this connection is going through a proxy

Methods inherited from class java.net.URLConnection

addRequestProperty, connect, getAllowUserInteraction, getConnectTimeout, getContent, getContent, getContentEncoding, getContentLength, getContentType, getDate, getDefaultAllowUserInteraction, getDefaultRequestProperty, getDefaultUseCaches, getDoInput, getDoOutput, getExpiration, getFileNameMap, getHeaderField, getHeaderField, getHeaderFieldDate, getHeaderFieldInt, getHeaderFieldKey, getHeaderFields, getIfModifiedSince, getInputStream, getLastModified, getOutputStream, getPermission, getReadTimeout, getRequestProperties, getRequestProperty, getURL, getUseCaches, guessContentTypeFromName, guessContentTypeFromStream, setAllowUserInteraction, setConnectTimeout, setContentHandlerFactory, setDefaultAllowUserInteraction, setDefaultRequestProperty, setDefaultUseCaches, setDoInput, setDoOutput, setFileNameMap, setIfModifiedSince, setReadTimeout, setRequestProperty, setUseCaches, toString

Methods inherited from class java.lang.Object

clone, equals, extends Object> getClass, finalize, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

HTTP_ACCEPTED

public static final int HTTP_ACCEPTED
The request has been accepted for processing but has not completed. There is no guarantee that the requested action will actually ever be completed succesfully, but everything is ok so far.
Field Value:
202

HTTP_BAD_GATEWAY

public static final int HTTP_BAD_GATEWAY
The proxy encountered a bad response from the server it was proxy-ing for
Field Value:
502

HTTP_BAD_METHOD

public static final int HTTP_BAD_METHOD
The specified request method is not allowed for this resource.
Field Value:
405

HTTP_BAD_REQUEST

public static final int HTTP_BAD_REQUEST
The request was misformed or could not be understood.
Field Value:
400

HTTP_CLIENT_TIMEOUT

public static final int HTTP_CLIENT_TIMEOUT
The request timed out.
Field Value:
408

HTTP_CONFLICT

public static final int HTTP_CONFLICT
There is a conflict between the current state of the resource and the requested action.
Field Value:
409

HTTP_CREATED

public static final int HTTP_CREATED
The requested resource has been created.
Field Value:
201

HTTP_ENTITY_TOO_LARGE

public static final int HTTP_ENTITY_TOO_LARGE
The request sent was too large for the server to handle.
Field Value:
413

HTTP_FORBIDDEN

public static final int HTTP_FORBIDDEN
There is no permission to access the requested resource.
Field Value:
403

HTTP_GATEWAY_TIMEOUT

public static final int HTTP_GATEWAY_TIMEOUT
The proxy timed out getting a reply from the remote server it was proxy-ing for.
Field Value:
504

HTTP_GONE

public static final int HTTP_GONE
The requested resource is no longer available. This ususally indicates a permanent condition.
Field Value:
410

HTTP_INTERNAL_ERROR

public static final int HTTP_INTERNAL_ERROR
The server encountered an unexpected error (such as a CGI script crash) that prevents the request from being fulfilled.
Field Value:
500

HTTP_LENGTH_REQUIRED

public static final int HTTP_LENGTH_REQUIRED
A Content-Length header is required for this request, but was not supplied.
Field Value:
411

HTTP_MOVED_PERM

public static final int HTTP_MOVED_PERM
The resource has been permanently moved to a new location.
Field Value:
301

HTTP_MOVED_TEMP

public static final int HTTP_MOVED_TEMP
The resource requested has been temporarily moved to a new location.
Field Value:
302

HTTP_MULT_CHOICE

public static final int HTTP_MULT_CHOICE
There is a list of choices available for the requested resource.
Field Value:
300

HTTP_NOT_ACCEPTABLE

public static final int HTTP_NOT_ACCEPTABLE
Based on the input headers sent, the resource returned in response to the request would not be acceptable to the client.
Field Value:
406

HTTP_NOT_AUTHORITATIVE

public static final int HTTP_NOT_AUTHORITATIVE
The meta-information returned in the header is not the actual data from the original server, but may be from a local or other copy. Normally this still indicates a successful completion.
Field Value:
203

HTTP_NOT_FOUND

public static final int HTTP_NOT_FOUND
The requested resource was not found.
Field Value:
404

HTTP_NOT_IMPLEMENTED

public static final int HTTP_NOT_IMPLEMENTED
The server does not support the requested functionality.
Field Value:
501
Since:
1.3

HTTP_NOT_MODIFIED

public static final int HTTP_NOT_MODIFIED
The document has not been modified since the criteria specified in a conditional GET.
Field Value:
304

HTTP_NO_CONTENT

public static final int HTTP_NO_CONTENT
The server performed the request, but there is no data to send back. This indicates that the user's display should not be changed.
Field Value:
204

HTTP_OK

public static final int HTTP_OK
Indicates the request succeeded.
Field Value:
200

HTTP_PARTIAL

public static final int HTTP_PARTIAL
The server completed the partial GET request for the resource.
Field Value:
206

HTTP_PAYMENT_REQUIRED

public static final int HTTP_PAYMENT_REQUIRED
Code reserved for future use - I hope way in the future.
Field Value:
402

HTTP_PRECON_FAILED

public static final int HTTP_PRECON_FAILED
A client specified pre-condition was not met on the server.
Field Value:
412

HTTP_PROXY_AUTH

public static final int HTTP_PROXY_AUTH
The client must authenticate with a proxy prior to attempting this request.
Field Value:
407

HTTP_REQ_TOO_LONG

public static final int HTTP_REQ_TOO_LONG
The name of the resource specified was too long.
Field Value:
414

HTTP_RESET

public static final int HTTP_RESET
The server performed the request, but there is no data to sent back, however, the user's display should be "reset" to clear out any form fields entered.
Field Value:
205

HTTP_SEE_OTHER

public static final int HTTP_SEE_OTHER
The response to the request issued is available at another location.
Field Value:
303

HTTP_SERVER_ERROR

public static final int HTTP_SERVER_ERROR

Deprecated.

This error code indicates that some sort of server error occurred.
Field Value:
500

HTTP_UNAUTHORIZED

public static final int HTTP_UNAUTHORIZED
The request made requires user authorization. Try again with a correct authentication header.
Field Value:
401

HTTP_UNAVAILABLE

public static final int HTTP_UNAVAILABLE
The HTTP service is not availalble, such as because it is overloaded and does not want additional requests.
Field Value:
503

HTTP_UNSUPPORTED_TYPE

public static final int HTTP_UNSUPPORTED_TYPE
The request is in a format not supported by the requested resource.
Field Value:
415

HTTP_USE_PROXY

public static final int HTTP_USE_PROXY
The requested resource needs to be accessed through a proxy.
Field Value:
305

HTTP_VERSION

public static final int HTTP_VERSION
This server does not support the protocol version requested.
Field Value:
505

instanceFollowRedirects

protected boolean instanceFollowRedirects
If this instance should follow redirect requests.

method

protected String method
The requested method in use for this connection. Default is GET.

responseCode

protected int responseCode
The response code received from the server

responseMessage

protected String responseMessage
The response message string received from the server.

Constructor Details

HttpURLConnection

protected HttpURLConnection(URL url)
Create an HttpURLConnection for the specified URL
Parameters:
url - The URL to create this connection for.

Method Details

disconnect

public abstract void disconnect()
Closes the connection to the server.

getErrorStream

public InputStream getErrorStream()
This method allows the caller to retrieve any data that might have been sent despite the fact that an error occurred. For example, the HTML page sent along with a 404 File Not Found error. If the socket is not connected, or if no error occurred or no data was returned, this method returns null.
Returns:
An InputStream for reading error data.

getFollowRedirects

public static boolean getFollowRedirects()
Returns a boolean indicating whether or not HTTP redirects will automatically be followed or not.
Returns:
true if redirects will be followed, false otherwise

getHeaderFieldDate

public long getHeaderFieldDate(String key,
                               long value)
Returns the value of the named field parsed as date
Overrides:
getHeaderFieldDate in interface URLConnection
Parameters:
key - the key of the header field
value - the default value if the header field is not present
Returns:
the value of the header field

getInstanceFollowRedirects

public boolean getInstanceFollowRedirects()
Returns the value of this HttpURLConnection's instanceFollowRedirects field
Returns:
true if following redirects is enabled, false otherwise

getPermission

public Permission getPermission()
            throws IOException
Returns a permission object representing the permission necessary to make the connection represented by this object
Overrides:
getPermission in interface URLConnection
Returns:
the permission necessary for this connection
Throws:
IOException - If an error occurs

getRequestMethod

public String getRequestMethod()
The request method currently in use for this connection.
Returns:
The request method

getResponseCode

public int getResponseCode()
            throws IOException
Gets the status code from an HTTP response message, or -1 if the response code could not be determined. Note that all valid response codes have class variables defined for them in this class.
Returns:
The response code
Throws:
IOException - If an error occurs

getResponseMessage

public String getResponseMessage()
            throws IOException
Gets the HTTP response message, if any, returned along with the response code from a server. Null if no response message was set or an error occured while connecting.
Returns:
The response message
Throws:
IOException - If an error occurs

setFollowRedirects

public static void setFollowRedirects(boolean set)
Sets whether HTTP redirects (requests with response code 3xx) should be automatically followed by this class. True by default
Parameters:
set - true if redirects should be followed, false otherwis.
Throws:
SecurityException - If a security manager exists and its checkSetFactory method doesn't allow the operation

setInstanceFollowRedirects

public void setInstanceFollowRedirects(boolean follow)
Sets the value of this HttpURLConnection's instanceFollowRedirects field
Parameters:
follow - true to enable following redirects, false otherwise

setRequestMethod

public void setRequestMethod(String method)
            throws ProtocolException
Set the method for the URL request, one of: GET POST HEAD OPTIONS PUT DELETE TRACE are legal
Parameters:
method - the method to use
Throws:
ProtocolException - If the method cannot be reset or if the requested method isn't valid for HTTP

usingProxy

public abstract boolean usingProxy()
Returns a boolean indicating whether or not this connection is going through a proxy
Returns:
true if through a proxy, false otherwise

HttpURLConnection.java -- Subclass of communications links using Hypertext Transfer Protocol. Copyright (C) 1998, 1999, 2000, 2002, 2003 Free Software Foundation This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.