java.net
類別 HttpURLConnection

java.lang.Object
  java.net.URLConnection
      java.net.HttpURLConnection

直接已知子類別：

HttpsURLConnection

public abstract class HttpURLConnection
extends URLConnection

支持 HTTP 特定功能的 URLConnection。有關詳細資訊，請參閱 the spec 。

每個 HttpURLConnection 實例都可用於產生單個請求，但是其他實例可以透明地共享連接到 HTTP 伺服器的基礎網路。請求後在 HttpURLConnection 的 InputStream 或 OutputStream 上調用 close() 方法可以釋放與此實例關聯的網路資源，但對共享的持久連接沒有任何影響。如果在調用 disconnect() 時持久連接空閒，則可能關閉基礎Socket。

從以下版本開始：

JDK1.1

另請參見：

disconnect()

欄位摘要

protected int	chunkLength 使用存儲塊編碼串流網要進行輸出時的存儲塊長度。
protected int	fixedContentLength 使用固定長度串流網要時的固定內容長度。
static int	HTTP_ACCEPTED HTTP 狀態碼 202：Accepted。
static int	HTTP_BAD_GATEWAY HTTP 狀態碼 502：Bad Gateway。
static int	HTTP_BAD_METHOD HTTP 狀態碼 405：Method Not Allowed。
static int	HTTP_BAD_REQUEST HTTP 狀態碼 400：Bad Request。
static int	HTTP_CLIENT_TIMEOUT HTTP 狀態碼 408：Request Time-Out。
static int	HTTP_CONFLICT HTTP 狀態碼 409：Conflict。
static int	HTTP_CREATED HTTP 狀態碼 201：Created。
static int	HTTP_ENTITY_TOO_LARGE HTTP 狀態碼 413：Request Entity Too Large。
static int	HTTP_FORBIDDEN HTTP 狀態碼 403：Forbidden。
static int	HTTP_GATEWAY_TIMEOUT HTTP 狀態碼 504：Gateway Timeout。
static int	HTTP_GONE HTTP 狀態碼 410：Gone。
static int	HTTP_INTERNAL_ERROR HTTP 狀態碼 500：Internal Server Error。
static int	HTTP_LENGTH_REQUIRED HTTP 狀態碼 411：Length Required。
static int	HTTP_MOVED_PERM HTTP 狀態碼 301：Moved Permanently。
static int	HTTP_MOVED_TEMP HTTP 狀態碼 302：Temporary Redirect。
static int	HTTP_MULT_CHOICE HTTP 狀態碼 300：Multiple Choices。
static int	HTTP_NO_CONTENT HTTP 狀態碼 204：No Content。
static int	HTTP_NOT_ACCEPTABLE HTTP 狀態碼 406：Not Acceptable。
static int	HTTP_NOT_AUTHORITATIVE HTTP 狀態碼 203：Non-Authoritative Information。
static int	HTTP_NOT_FOUND HTTP 狀態碼 404：Not Found。
static int	HTTP_NOT_IMPLEMENTED HTTP 狀態碼 501：Not Implemented。
static int	HTTP_NOT_MODIFIED HTTP 狀態碼 304：Not Modified。
static int	HTTP_OK HTTP 狀態碼 200：OK。
static int	HTTP_PARTIAL HTTP 狀態碼 206：Partial Content。
static int	HTTP_PAYMENT_REQUIRED HTTP 狀態碼 402：Payment Required。
static int	HTTP_PRECON_FAILED HTTP 狀態碼 412：Precondition Failed。
static int	HTTP_PROXY_AUTH HTTP 狀態碼 407：Proxy Authentication Required。
static int	HTTP_REQ_TOO_LONG HTTP 狀態碼 414：Request-URI Too Large。
static int	HTTP_RESET HTTP 狀態碼 205：Reset Content。
static int	HTTP_SEE_OTHER HTTP 狀態碼 303：See Other。
static int	HTTP_SERVER_ERROR 已過時。 放錯了位置，它不應該存在。
static int	HTTP_UNAUTHORIZED HTTP 狀態碼 401：Unauthorized。
static int	HTTP_UNAVAILABLE HTTP 狀態碼 503：Service Unavailable。
static int	HTTP_UNSUPPORTED_TYPE HTTP 狀態碼 415：Unsupported Media Type。
static int	HTTP_USE_PROXY HTTP 狀態碼 305：Use Proxy。
static int	HTTP_VERSION HTTP 狀態碼 505：HTTP Version Not Supported。
protected boolean	instanceFollowRedirects 如果為 true，則協議自動執行重定向。
protected String	method HTTP 方法（GET、POST、PUT 等）。
protected int	responseCode 表示三位字數的 HTTP 狀態碼 (Status-Code) 的 int。
protected String	responseMessage HTTP 回應訊息。

從類別 java.net.URLConnection 繼承的欄位

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

建構子摘要

protected

HttpURLConnection(URL u) HttpURLConnection 的建構子。

方法摘要

abstract void	disconnect() 指示近期伺服器不太可能有其他請求。
InputStream	getErrorStream() 如果連接失敗但伺服器仍然發送了有用資料，則返回錯誤串流。
static boolean	getFollowRedirects() 返回指示是否應該自動執行 HTTP 重定向 (3xx) 的 boolean 值。
String	getHeaderField(int n) 返回 nth 頭欄位的值。
long	getHeaderFieldDate(String name, long Default) 返回解析為日期的指定欄位的值。
String	getHeaderFieldKey(int n) 返回 nth 頭欄位的鍵。
boolean	getInstanceFollowRedirects() 返回此 HttpURLConnection 的 instanceFollowRedirects 欄位的值。
Permission	getPermission() 返回一個權限物件，其代表建立此物件表示的連接所需的權限。
String	getRequestMethod() 獲取請求方法。
int	getResponseCode() 從 HTTP 回應訊息獲取狀態碼。
String	getResponseMessage() 獲取與來自伺服器的回應程式碼一起返回的 HTTP 回應訊息（如果有）。
void	setChunkedStreamingMode(int chunklen) 此方法用於在預先不知道內容長度時啟用沒有進行內部緩衝的 HTTP 請求正文的串流。
void	setFixedLengthStreamingMode(int contentLength) 此方法用於在預先已知內容長度時啟用沒有進行內部緩衝的 HTTP 請求正文的串流。
static void	setFollowRedirects(boolean set) 設置此類別是否應該自動執行 HTTP 重定向（回應程式碼為 3xx 的請求）。
void	setInstanceFollowRedirects(boolean followRedirects) 設置此 HttpURLConnection 實例是否應該自動執行 HTTP 重定向（回應程式碼為 3xx 的請求）。
void	setRequestMethod(String method) 設置 URL 請求的方法， GET POST HEAD OPTIONS PUT DELETE TRACE 以上方法之一是合法的，具體取決於協議的限制。
abstract boolean	usingProxy() 指示連接是否通過代理。

從類別 java.net.URLConnection 繼承的方法

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

從類別 java.lang.Object 繼承的方法

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

欄位詳細資訊

method

protected String method

HTTP 方法（GET、POST、PUT 等）。

chunkLength

protected int chunkLength

使用存儲塊編碼串流網要進行輸出時的存儲塊長度。值 -1 表示對輸出禁用存儲塊編碼。

從以下版本開始：

1.5

fixedContentLength

protected int fixedContentLength

使用固定長度串流網要時的固定內容長度。值 -1 表示對輸出禁用固定長度串流網要。

從以下版本開始：

1.5

responseCode

protected int responseCode

表示三位字數的 HTTP 狀態碼 (Status-Code) 的 int。

• 1xx:Informational
• 2xx:Success
• 3xx:Redirection
• 4xx:Client Error
• 5xx:Server Error

responseMessage

protected String responseMessage

HTTP 回應訊息。

instanceFollowRedirects

protected boolean instanceFollowRedirects

如果為 true，則協議自動執行重定向。如果為 false，則協議不會自動執行重定向。

此欄位由 setInstanceFollowRedirects 方法設置。其值由 getInstanceFollowRedirects 方法返回。

其預設值基於建構 HttpURLConnection 時靜態 followRedirects 的值。

另請參見：

setInstanceFollowRedirects(boolean), getInstanceFollowRedirects(), setFollowRedirects(boolean)

HTTP_OK

public static final int HTTP_OK

HTTP 狀態碼 200：OK。

另請參見：

常數欄位值

HTTP_CREATED

public static final int HTTP_CREATED

HTTP 狀態碼 201：Created。

另請參見：

常數欄位值

HTTP_ACCEPTED

public static final int HTTP_ACCEPTED

HTTP 狀態碼 202：Accepted。

另請參見：

常數欄位值

HTTP_NOT_AUTHORITATIVE

public static final int HTTP_NOT_AUTHORITATIVE

HTTP 狀態碼 203：Non-Authoritative Information。

另請參見：

常數欄位值

HTTP_NO_CONTENT

public static final int HTTP_NO_CONTENT

HTTP 狀態碼 204：No Content。

另請參見：

常數欄位值

HTTP_RESET

public static final int HTTP_RESET

HTTP 狀態碼 205：Reset Content。

另請參見：

常數欄位值

HTTP_PARTIAL

public static final int HTTP_PARTIAL

HTTP 狀態碼 206：Partial Content。

另請參見：

常數欄位值

HTTP_MULT_CHOICE

public static final int HTTP_MULT_CHOICE

HTTP 狀態碼 300：Multiple Choices。

另請參見：

常數欄位值

HTTP_MOVED_PERM

public static final int HTTP_MOVED_PERM

HTTP 狀態碼 301：Moved Permanently。

另請參見：

常數欄位值

HTTP_MOVED_TEMP

public static final int HTTP_MOVED_TEMP

HTTP 狀態碼 302：Temporary Redirect。

另請參見：

常數欄位值

HTTP_SEE_OTHER

public static final int HTTP_SEE_OTHER

HTTP 狀態碼 303：See Other。

另請參見：

常數欄位值

HTTP_NOT_MODIFIED

public static final int HTTP_NOT_MODIFIED

HTTP 狀態碼 304：Not Modified。

另請參見：

常數欄位值

HTTP_USE_PROXY

public static final int HTTP_USE_PROXY

HTTP 狀態碼 305：Use Proxy。

另請參見：

常數欄位值

HTTP_BAD_REQUEST

public static final int HTTP_BAD_REQUEST

HTTP 狀態碼 400：Bad Request。

另請參見：

常數欄位值

HTTP_UNAUTHORIZED

public static final int HTTP_UNAUTHORIZED

HTTP 狀態碼 401：Unauthorized。

另請參見：

常數欄位值

HTTP_PAYMENT_REQUIRED

public static final int HTTP_PAYMENT_REQUIRED

HTTP 狀態碼 402：Payment Required。

另請參見：

常數欄位值

HTTP_FORBIDDEN

public static final int HTTP_FORBIDDEN

HTTP 狀態碼 403：Forbidden。

另請參見：

常數欄位值

HTTP_NOT_FOUND

public static final int HTTP_NOT_FOUND

HTTP 狀態碼 404：Not Found。

另請參見：

常數欄位值

HTTP_BAD_METHOD

public static final int HTTP_BAD_METHOD

HTTP 狀態碼 405：Method Not Allowed。

另請參見：

常數欄位值

HTTP_NOT_ACCEPTABLE

public static final int HTTP_NOT_ACCEPTABLE

HTTP 狀態碼 406：Not Acceptable。

另請參見：

常數欄位值

HTTP_PROXY_AUTH

public static final int HTTP_PROXY_AUTH

HTTP 狀態碼 407：Proxy Authentication Required。

另請參見：

常數欄位值

HTTP_CLIENT_TIMEOUT

public static final int HTTP_CLIENT_TIMEOUT

HTTP 狀態碼 408：Request Time-Out。

另請參見：

常數欄位值

HTTP_CONFLICT

public static final int HTTP_CONFLICT

HTTP 狀態碼 409：Conflict。

另請參見：

常數欄位值

HTTP_GONE

public static final int HTTP_GONE

HTTP 狀態碼 410：Gone。

另請參見：

常數欄位值

HTTP_LENGTH_REQUIRED

public static final int HTTP_LENGTH_REQUIRED

HTTP 狀態碼 411：Length Required。

另請參見：

常數欄位值

HTTP_PRECON_FAILED

public static final int HTTP_PRECON_FAILED

HTTP 狀態碼 412：Precondition Failed。

另請參見：

常數欄位值

HTTP_ENTITY_TOO_LARGE

public static final int HTTP_ENTITY_TOO_LARGE

HTTP 狀態碼 413：Request Entity Too Large。

另請參見：

常數欄位值

HTTP_REQ_TOO_LONG

public static final int HTTP_REQ_TOO_LONG

HTTP 狀態碼 414：Request-URI Too Large。

另請參見：

常數欄位值

HTTP_UNSUPPORTED_TYPE

public static final int HTTP_UNSUPPORTED_TYPE

HTTP 狀態碼 415：Unsupported Media Type。

另請參見：

常數欄位值

HTTP_SERVER_ERROR

@Deprecated
public static final int HTTP_SERVER_ERROR

已過時。 放錯了位置，它不應該存在。

HTTP 狀態碼 500：Internal Server Error。

另請參見：

常數欄位值

HTTP_INTERNAL_ERROR

public static final int HTTP_INTERNAL_ERROR

HTTP 狀態碼 500：Internal Server Error。

另請參見：

常數欄位值

HTTP_NOT_IMPLEMENTED

public static final int HTTP_NOT_IMPLEMENTED

HTTP 狀態碼 501：Not Implemented。

另請參見：

常數欄位值

HTTP_BAD_GATEWAY

public static final int HTTP_BAD_GATEWAY

HTTP 狀態碼 502：Bad Gateway。

另請參見：

常數欄位值

HTTP_UNAVAILABLE

public static final int HTTP_UNAVAILABLE

HTTP 狀態碼 503：Service Unavailable。

另請參見：

常數欄位值

HTTP_GATEWAY_TIMEOUT

public static final int HTTP_GATEWAY_TIMEOUT

HTTP 狀態碼 504：Gateway Timeout。

另請參見：

常數欄位值

HTTP_VERSION

public static final int HTTP_VERSION

HTTP 狀態碼 505：HTTP Version Not Supported。

另請參見：

常數欄位值

建構子詳細資訊

HttpURLConnection

protected HttpURLConnection(URL u)

HttpURLConnection 的建構子。

參數：

u - URL

方法詳細資訊

getHeaderFieldKey

public String getHeaderFieldKey(int n)

返回 n^th 頭欄位的鍵。有些實作可能將 0^th 頭欄位視為特殊狀態行，即由 HTTP 伺服器返回的狀態行。在此情況下，getHeaderField(0) 返回狀態行，而 getHeaderFieldKey(0) 返回 null。

覆寫：

類別 URLConnection 中的 getHeaderFieldKey

參數：

n - 索引，其中 n >=0。

返回：

n^th 頭欄位的鍵；如果鍵不存在，則返回 null。

setFixedLengthStreamingMode

public void setFixedLengthStreamingMode(int contentLength)

此方法用於在預先已知內容長度時啟用沒有進行內部緩衝的 HTTP 請求正文的串流。

如果應用程序嘗試寫入的資料多於指示的內容長度，或者應用程序在寫入指示的內容長度前關閉了 OutputStream，將拋出異常。

啟用輸出串流時，不能自動處理驗證和重定向。如果需要驗證和重定向，則在讀取回應時將拋出 HttpRetryException。可以查詢此異常以獲取錯誤的詳細資訊。

該方法必須在連接 URLConnection 前調用。

參數：

contentLength - 將寫入 OutputStream 的位元組數。

拋出：

IllegalStateException - 如果已連接 URLConnection 或者已啟用另外的串流網要。

IllegalArgumentException - 如果指定的內容長度小於零。

從以下版本開始：

1.5

另請參見：

setChunkedStreamingMode(int)

setChunkedStreamingMode

public void setChunkedStreamingMode(int chunklen)

此方法用於在預先不知道內容長度時啟用沒有進行內部緩衝的 HTTP 請求正文的串流。在此網要下，使用存儲塊傳輸編碼發送請求正文。注意，並非所有 HTTP 伺服器都支持此網要。

啟用輸出串流時，不能自動處理驗證和重定向。如果需要驗證和重定向，則在讀取回應時將拋出 HttpRetryException。可以查詢此異常以獲取錯誤的詳細資訊。

該方法必須在連接 URLConnection 前調用。

參數：

chunklen - 要寫入每個存儲塊的位元組數。如果 chunklen 小於或等於零，則使用預設值。

拋出：

IllegalStateException - 如果已連接 URLConnection 或者已啟用其他串流網要。

從以下版本開始：

1.5

另請參見：

setFixedLengthStreamingMode(int)

getHeaderField

public String getHeaderField(int n)

返回 n^th 頭欄位的值。有些實作可能將 0^th 頭欄位視為特殊狀態行，即由 HTTP 伺服器返回的狀態行。

此方法可以與 getHeaderFieldKey 方法一起使用來迭代訊息中的所有頭。

覆寫：

類別 URLConnection 中的 getHeaderField

參數：

n - 索引，其中 n>=0。

返回：

n^th 頭欄位的值；如果值不存在，則返回 null。

另請參見：

getHeaderFieldKey(int)

setFollowRedirects

public static void setFollowRedirects(boolean set)

設置此類別是否應該自動執行 HTTP 重定向（回應程式碼為 3xx 的請求）。預設情況下為 true。Applet 不能更改此變數。

如果存在安全管理器，則此方法首先調用安全管理器的 checkSetFactory 方法來確保允許操作。這可能會導致 SecurityException 異常。

參數：

set - 指示是否進行 HTTP 重定向的 boolean 值。

拋出：

SecurityException - 如果安全管理器存在並且其 checkSetFactory 方法不允許進行此操作。

另請參見：

SecurityManager.checkSetFactory(), getFollowRedirects()

getFollowRedirects

public static boolean getFollowRedirects()

返回指示是否應該自動執行 HTTP 重定向 (3xx) 的 boolean 值。

返回：

如果應該自動執行 HTTP 重定向，則返回 true；否則返回 false。

另請參見：

setFollowRedirects(boolean)

setInstanceFollowRedirects

public void setInstanceFollowRedirects(boolean followRedirects)

設置此 HttpURLConnection 實例是否應該自動執行 HTTP 重定向（回應程式碼為 3xx 的請求）。

預設值來自 followRedirects，其預設情況下為 true。

參數：

followRedirects - 指示是否執行 HTTP 重定向的 boolean 值。

從以下版本開始：

1.3

另請參見：

instanceFollowRedirects, getInstanceFollowRedirects()

getInstanceFollowRedirects

public boolean getInstanceFollowRedirects()

返回此 HttpURLConnection 的 instanceFollowRedirects 欄位的值。

返回：

此 HttpURLConnection 的 instanceFollowRedirects 欄位的值。

從以下版本開始：

1.3

另請參見：

instanceFollowRedirects, setInstanceFollowRedirects(boolean)

setRequestMethod

public void setRequestMethod(String method)
                      throws ProtocolException

設置 URL 請求的方法，

• GET
• POST
• HEAD
• OPTIONS
• PUT
• DELETE
• TRACE

以上方法之一是合法的，具體取決於協議的限制。預設方法為 GET。

參數：

method - HTTP 方法

拋出：

ProtocolException - 如果無法重置方法或者請求的方法對 HTTP 無效。

另請參見：

getRequestMethod()

getRequestMethod

public String getRequestMethod()

獲取請求方法。

返回：

HTTP 請求方法

另請參見：

setRequestMethod(java.lang.String)

getResponseCode

public int getResponseCode()
                    throws IOException

從 HTTP 回應訊息獲取狀態碼。例如，就以下狀態行來說：

 HTTP/1.0 200 OK
 HTTP/1.0 401 Unauthorized
 

將分別返回 200 和 401。如果無法從回應中識別任何程式碼（即回應不是有效的 HTTP），則返回 -1。

返回：

HTTP 狀態碼或 -1

拋出：

IOException - 如果連接到伺服器時發生錯誤。

getResponseMessage

public String getResponseMessage()
                          throws IOException

獲取與來自伺服器的回應程式碼一起返回的 HTTP 回應訊息（如果有）。對於如下回應：

 HTTP/1.0 200 OK
 HTTP/1.0 404 Not Found
 

分別提取 String "OK" 和 "Not Found"。如果無法從回應識別任何字元（結果不是有效的 HTTP），則返回 null。

返回：

HTTP 回應訊息或 null

拋出：

IOException - 如果連接到伺服器時發生錯誤。

getHeaderFieldDate

public long getHeaderFieldDate(String name,
                               long Default)

從類別 URLConnection 複製的描述

返回解析為日期的指定欄位的值。結果為指定欄位表示的距離格林威治標準時間 1970 年 1 月 1 日的毫秒數。

有些連接型別（例如 http-ng）具有預解析頭，所以存在這種形式的 getHeaderField。用於該型別的連接可覆寫此方法和縮短解析過程。

覆寫：

類別 URLConnection 中的 getHeaderFieldDate

參數：

name - 頭欄位的名稱。

Default - 預設值。

返回：

欄位的值，解析為日期。如果該欄位缺少或有錯誤，則返回 Default 參數的值。

disconnect

public abstract void disconnect()

指示近期伺服器不太可能有其他請求。調用 disconnect() 並不意味著可以對其他請求重用此 HttpURLConnection 實例。

usingProxy

public abstract boolean usingProxy()

指示連接是否通過代理。

返回：

指示連接是否使用代理的 boolean 值。

getPermission

public Permission getPermission()
                         throws IOException

從類別 URLConnection 複製的描述

返回一個權限物件，其代表建立此物件表示的連接所需的權限。如果建立連接不需要任何權限，則此方法返回 null。預設情況下，此方法返回 java.security.AllPermission。子類別應覆寫此方法並返回一個權限物件，該物件最能代表用於建立到 URL 的連接所需的權限。例如表示 file:URL 的 URLConnection 將返回 java.io.FilePermission 物件。

返回的權限可能取決於連接的狀態。例如，連接之前的權限可能不同於連接之後的權限。例如，一個 HTTP 伺服器（如 foo.com）可能將連接重定向到一台不同的主機（如 bar.com）。在連接之前，連接返回的權限將代表連接到 foo.com 所需的權限，而連接之後返回的權限將是連接到 bar.com 所需的權限。

使用權限通常有兩個目的：保護通過 URLConnection 獲取的物件的快取記憶體；檢查接收方的權限以瞭解特定的 URL。第一種情況下，應在獲取物件之後 再獲取權限。例如，在一個 HTTP 連接中，這將代表連接到最終將從該主機獲取資料的主機的權限。第二種情況下，應在連接之前 對權限進行獲取和檢查。

覆寫：

類別 URLConnection 中的 getPermission

返回：

代表建立此 URLConnection 表示的連接所需的權限的權限物件。

拋出：

IOException - 如果計算權限需要網路或檔案 I/O 並且在計算過程中出現異常。

getErrorStream

public InputStream getErrorStream()

如果連接失敗但伺服器仍然發送了有用資料，則返回錯誤串流。典型範例是，當 HTTP 伺服器使用 404 回應時，將導致在連接中拋出 FileNotFoundException，但是伺服器同時還會發送建議如何操作的 HTML 說明頁。

此方法不會導致啟用連接。如果沒有建立連接，或者在連接時伺服器沒有發生錯誤，或伺服器出錯但沒有發送錯誤資料，則此方法返回 null。這是預設設置。

返回：

錯誤串流（如果存在）；如果沒有發生錯誤、沒有建立連接或伺服器沒有發送有用資料，則返回 null。