モジュール java.base
パッケージ java.net

クラスHttpURLConnection

java.lang.Object
java.net.URLConnection
java.net.HttpURLConnection
直系の既知のサブクラス:
HttpsURLConnection
public abstract class HttpURLConnection extends URLConnection
HTTP固有の機能をサポートするURLConnectionです。 詳細については、仕様を参照してください。

単一の要求を行う際には個々のHttpURLConnectionインスタンスが使用されますが、その背後のHTTPサーバーへのネットワーク接続は、ほかのインスタンスと透過的に共有される可能性があります。 要求後、HttpURLConnectionのInputStreamまたはOutputStream上でclose()メソッドを呼び出すと、そのインスタンスに関連付けられていたネットワーク・リソースが解放される可能性がありますが、共有されている持続接続への影響はまったくありません。 disconnect()メソッドを呼び出した場合、持続接続がその時点でアイドル状態になっていれば、使用していたソケットがクローズされる可能性があります。

HTTPプロトコル・ハンドラには、システム・プロパティからアクセスできるいくつかの設定があります。 これには、プロキシ設定やさまざまな他の設定が含まれます。

セキュリティ権限

セキュリティ・マネージャがインストールされていて、メソッドが呼び出されて接続を開こうとすると、呼び出し元は次のいずれかを所有している必要があります:

自動リダイレクションが有効になっており、この要求が別の宛先にリダイレクトされる場合、呼出し元にはリダイレクト先のホストまたはURLに接続するためのアクセス権も必要です。

導入されたバージョン:
1.1
関連項目:

  • ﾌｨｰﾙﾄﾞ詳細

    • method

      protected String method
      HTTPメソッド(GET、POST、PUTなど)です。

    • chunkLength

      protected int chunkLength
      出力時にチャンク・エンコーディング・ストリーミング・モードを使用する場合のチャンク長。 値-1は、出力時のチャンク・エンコーディングが無効であることを意味します。
      導入されたバージョン:
      1.5

    • fixedContentLength

      protected int fixedContentLength
      固定長ストリーミング・モードを使用する場合の固定コンテンツ長。 値-1は、出力時の固定長ストリーミング・モードが無効であることを意味します。

      ノート: コンテンツの長さをより長く設定できるため、このフィールドの代わりにfixedContentLengthLongが推奨されています。

      導入されたバージョン:
      1.5

    • fixedContentLengthLong

      protected long fixedContentLengthLong
      固定長ストリーミング・モードを使用する場合の固定コンテンツ長。 値-1は、出力時の固定長ストリーミング・モードが無効であることを意味します。
      導入されたバージョン:
      1.7

    • responseCode

      protected int responseCode
      3桁のHTTPステータス・コードを表すintです。
      • 1xx: 情報
      • 2xx: 成功
      • 3xx: リダイレクション
      • 4xx: クライアント・エラー
      • 5xx: サーバー・エラー

    • responseMessage

      protected String responseMessage
      HTTP応答メッセージです。

    • instanceFollowRedirects

      protected boolean instanceFollowRedirects
      trueの場合、プロトコルは自動的にリダイレクトに従います。 falseの場合、プロトコルは自動的にはリダイレクトに従いません。

      このフィールドは、setInstanceFollowRedirectsメソッドによって設定されます。 その値は、getInstanceFollowRedirectsメソッドによって返されます。

      HttpURLConnection作成時、デフォルト値はstatic followRedirectsの値に基づきます。

      関連項目:

    • HTTP_OK

      public static final int HTTP_OK
      HTTP Status-Code 200: OKです。
      関連項目:

    • HTTP_CREATED

      public static final int HTTP_CREATED
      HTTP Status-Code 201: 作成されました。
      関連項目:

    • HTTP_ACCEPTED

      public static final int HTTP_ACCEPTED
      HTTP Status-Code 202: 受け入れられました。
      関連項目:

    • HTTP_NOT_AUTHORITATIVE

      public static final int HTTP_NOT_AUTHORITATIVE
      HTTP Status-Code 203: 信頼できない情報です。
      関連項目:

    • HTTP_NO_CONTENT

      public static final int HTTP_NO_CONTENT
      HTTP Status-Code 204: コンテンツがありません。
      関連項目:

    • HTTP_RESET

      public static final int HTTP_RESET
      HTTP Status-Code 205: コンテンツをリセットします。
      関連項目:

    • HTTP_PARTIAL

      public static final int HTTP_PARTIAL
      HTTP Status-Code 206: 部分的なコンテンツ。
      関連項目:

    • HTTP_MULT_CHOICE

      public static final int HTTP_MULT_CHOICE
      HTTP Status-Code 300: 複数の選択肢があります。
      関連項目:

    • HTTP_MOVED_PERM

      public static final int HTTP_MOVED_PERM
      HTTP Status-Code 301: 永続的に移動されました。
      関連項目:

    • HTTP_MOVED_TEMP

      public static final int HTTP_MOVED_TEMP
      HTTP Status-Code 302: 一時的なリダイレクト。
      関連項目:

    • HTTP_SEE_OTHER

      public static final int HTTP_SEE_OTHER
      HTTP Status-Code 303: ほかを参照してください。
      関連項目:

    • HTTP_NOT_MODIFIED

      public static final int HTTP_NOT_MODIFIED
      HTTP Status-Code 304: 変更されていません。
      関連項目:

    • HTTP_USE_PROXY

      public static final int HTTP_USE_PROXY
      HTTP Status-Code 305: プロキシを使用します。
      関連項目:

    • HTTP_BAD_REQUEST

      public static final int HTTP_BAD_REQUEST
      HTTP Status-Code 400: 不正な要求。
      関連項目:

    • HTTP_UNAUTHORIZED

      public static final int HTTP_UNAUTHORIZED
      HTTP Status-Code 401: 承認されていません。
      関連項目:

    • HTTP_PAYMENT_REQUIRED

      public static final int HTTP_PAYMENT_REQUIRED
      HTTP Status-Code 402: 支払いの必要があります。
      関連項目:

    • HTTP_FORBIDDEN

      public static final int HTTP_FORBIDDEN
      HTTP Status-Code 403: 禁止されています。
      関連項目:

    • HTTP_NOT_FOUND

      public static final int HTTP_NOT_FOUND
      HTTP Status-Code 404: 見つかりません。
      関連項目:

    • HTTP_BAD_METHOD

      public static final int HTTP_BAD_METHOD
      HTTP Status-Code 405: メソッドが許可されていません。
      関連項目:

    • HTTP_NOT_ACCEPTABLE

      public static final int HTTP_NOT_ACCEPTABLE
      HTTP Status-Code 406: 受け入れられません。
      関連項目:

    • HTTP_PROXY_AUTH

      public static final int HTTP_PROXY_AUTH
      HTTP Status-Code 407: プロキシ認証が必要です。
      関連項目:

    • HTTP_CLIENT_TIMEOUT

      public static final int HTTP_CLIENT_TIMEOUT
      HTTP Status-Code 408: 要求がタイム・アウトしました。
      関連項目:

    • HTTP_CONFLICT

      public static final int HTTP_CONFLICT
      HTTP Status-Code 409: 衝突しています。
      関連項目:

    • HTTP_GONE

      public static final int HTTP_GONE
      HTTP Status-Code 410: 存在しません。
      関連項目:

    • HTTP_LENGTH_REQUIRED

      public static final int HTTP_LENGTH_REQUIRED
      HTTP Status-Code 411: 長さが必要です。
      関連項目:

    • HTTP_PRECON_FAILED

      public static final int HTTP_PRECON_FAILED
      HTTP Status-Code 412: 前提条件が満たされていません。
      関連項目:

    • HTTP_ENTITY_TOO_LARGE

      public static final int HTTP_ENTITY_TOO_LARGE
      HTTP Status-Code 413: 要求のエンティティが大きすぎます。
      関連項目:

    • HTTP_REQ_TOO_LONG

      public static final int HTTP_REQ_TOO_LONG
      HTTP Status-Code 414: 要求のURIが大きすぎます。
      関連項目:

    • HTTP_UNSUPPORTED_TYPE

      public static final int HTTP_UNSUPPORTED_TYPE
      HTTP Status-Code 415: サポートされていないメディア・タイプです。
      関連項目:

    • HTTP_SERVER_ERROR

      @Deprecated public static final int HTTP_SERVER_ERROR
      非推奨。
      間違ったフィールドであり、存在するべきではありません。
      HTTP Status-Code 500: 内部サーバー・エラー。
      関連項目:

    • HTTP_INTERNAL_ERROR

      public static final int HTTP_INTERNAL_ERROR
      HTTP Status-Code 500: 内部サーバー・エラー。
      関連項目:

    • HTTP_NOT_IMPLEMENTED

      public static final int HTTP_NOT_IMPLEMENTED
      HTTP Status-Code 501: 実装されていません。
      関連項目:

    • HTTP_BAD_GATEWAY

      public static final int HTTP_BAD_GATEWAY
      HTTP Status-Code 502: 不正なゲートウェイ。
      関連項目:

    • HTTP_UNAVAILABLE

      public static final int HTTP_UNAVAILABLE
      HTTP Status-Code 503: サービスが使用不可能です。
      関連項目:

    • HTTP_GATEWAY_TIMEOUT

      public static final int HTTP_GATEWAY_TIMEOUT
      HTTP Status-Code 504: ゲートウェイがタイム・アウトしました。
      関連項目:

    • HTTP_VERSION

      public static final int HTTP_VERSION
      HTTP Status-Code 505: サポートされていないHTTPバージョンです。
      関連項目:

  • コンストラクタの詳細

    • HttpURLConnection

      protected HttpURLConnection(URL u)
      HttpURLConnectionのコンストラクタです。
      パラメータ:
      u - URL

  • メソッドの詳細

    • setAuthenticator

      public void setAuthenticator(Authenticator auth)
      このHttpURLConnectionのHTTPプロトコルで認証がリクエストされたときに使用するAuthenticatorを供給します。 オーセンティケータが指定されていない場合は、「デフォルト・オーセンティケータ」が使用されます。
      実装要件:
      このメソッドのデフォルトの動作は、無条件にUnsupportedOperationExceptionをスローすることです。 特定のHttpURLConnectionインスタンスのAuthenticatorの供給をサポートするHttpURLConnectionの具体的な実装では、このメソッドをオーバーライドして別の動作を実装する必要があります。
      実装上のノート:
      認証方式によっては、提供されたオーセンティケータを使用してパスワードを取得する必要があります。 たとえば、サードパーティのセキュリティ・ライブラリに依存する実装では、これらのライブラリがそうするように構成されている場合でも、デフォルトの認証プロバイダが呼び出されることがあります。 同様に、トランスペアレントなNTLM認証をサポートする実装では、提供された認証プログラムを呼び出す前に、まずシステムのユーザー資格証明を使用して接続を試みる可能性があります。
      ただし、オーセンティケータが具体的に提供されている場合は、同じAuthenticatorインスタンスを共有するHttpURLConnectionインスタンスに対してのみ基本接続が再利用され、キャッシュされている場合は同じAuthenticatorを共有するHttpURLConnectionに対してのみ再利用できます。
      パラメータ:
      auth - このHttpURLConnectionによって使用されるべきAuthenticator。
      例外:
      UnsupportedOperationException - Authenticatorの設定が基本となる実装でサポートされていない場合。
      IllegalStateException - URLConnectionがすでに接続されている場合。
      NullPointerException - 提供されたauthがnullの場合。
      導入されたバージョン:
      9

    • getHeaderFieldKey

      public String getHeaderFieldKey(int n)
      n番目のヘッダー・フィールドのキーを返します。 実装によっては、0番目のヘッダー・フィールドを特別なものとして、つまりHTTPサーバーから返されたステータス行として扱うことがあります。 この場合、getHeaderField(0)はそのステータス行を返しますが、getHeaderFieldKey(0)はnullを返します。
      オーバーライド:
      getHeaderFieldKey、クラスURLConnection
      パラメータ:
      n - インデックス。ここでn >=0です。
      戻り値:
      n番目のヘッダー・フィールドのキー。キーが存在しない場合はnull。

    • setFixedLengthStreamingMode

      public void setFixedLengthStreamingMode(int contentLength)
      このメソッドを使用すれば、コンテンツ長があらかじめわかっている場合に、内部バッファを使用しないHTTP要求本体のストリーミングを有効にすることができます。

      アプリケーションが、指定されたコンテンツ長を超えるデータを書き込もうとしたり、指定された量の書込みを終える前にOutputStreamをクローズしたりすると、例外がスローされます。

      出力ストリーム処理を有効にした場合、認証とリダイレクションを自動的に処理することはできません。 認証またはリダイレクションが必要とされる場合には、応答の読取り時にHttpRetryExceptionがスローされます。 この例外を調べれば、エラーの詳細がわかります。

      このメソッドは、URLConnectionの接続前に呼び出してください。

      ノート: コンテンツの長さをより長く設定できるため、このメソッドの代わりにsetFixedLengthStreamingMode(long)が推奨されています。

      パラメータ:
      contentLength - OutputStreamに書き込まれるバイト数。
      例外:
      IllegalStateException - URLConnectionがすでに接続されている場合、または別のストリーミング・モードがすでに有効になっている場合。
      IllegalArgumentException - 0より小さいコンテンツ長が指定された場合。
      導入されたバージョン:
      1.5
      関連項目:

    • setFixedLengthStreamingMode

      public void setFixedLengthStreamingMode(long contentLength)
      このメソッドを使用すれば、コンテンツ長があらかじめわかっている場合に、内部バッファを使用しないHTTP要求本体のストリーミングを有効にすることができます。

      アプリケーションが、指定されたコンテンツ長を超えるデータを書き込もうとしたり、指定された量の書込みを終える前にOutputStreamをクローズしたりすると、例外がスローされます。

      出力ストリーム処理を有効にした場合、認証とリダイレクションを自動的に処理することはできません。 認証またはリダイレクションが必要とされる場合には、応答の読取り時にHttpRetryExceptionがスローされます。 この例外を調べれば、エラーの詳細がわかります。

      このメソッドは、URLConnectionの接続前に呼び出してください。

      このメソッドを呼び出して設定されたコンテンツの長さは、setFixedLengthStreamingMode(int)によって設定されたどの値よりも優先されます。

      パラメータ:
      contentLength - OutputStreamに書き込まれるバイト数。
      例外:
      IllegalStateException - URLConnectionがすでに接続されている場合、または別のストリーミング・モードがすでに有効になっている場合。
      IllegalArgumentException - 0より小さいコンテンツ長が指定された場合。
      導入されたバージョン:
      1.7

    • setChunkedStreamingMode

      public void setChunkedStreamingMode(int chunklen)
      このメソッドを使用すれば、コンテンツ長があらかじめわかっていない場合に、内部バッファを使用しないHTTP要求本体のストリーミングを有効にできます。 このモードでは、要求本体の送信時にチャンク転送エンコーディングが使用されます。 すべてのHTTPサーバーがこのモードをサポートしているわけではないので注意してください。

      出力ストリーム処理を有効にした場合、認証とリダイレクションを自動的に処理することはできません。 認証またはリダイレクションが必要とされる場合には、応答の読取り時にHttpRetryExceptionがスローされます。 この例外を調べれば、エラーの詳細がわかります。

      このメソッドは、URLConnectionの接続前に呼び出してください。

      パラメータ:
      chunklen−各チャンク内に書き込むバイト数。 chunklenが0以下の場合はデフォルト値が使用される。
      例外:
      IllegalStateException - URLConnectionがすでに接続されている場合、または別のストリーミング・モードがすでに有効になっている場合。
      導入されたバージョン:
      1.5
      関連項目:

    • getHeaderField

      public String getHeaderField(int n)
      n番目のヘッダー・フィールドの値を返します。 実装によっては、0番目のヘッダー・フィールドを特別なものとして、つまりHTTPサーバーから返されたステータス行として扱うことがあります。

      このメソッドとgetHeaderFieldKeyメソッドを組み合わせて使用すると、メッセージ内のすべてのヘッダーを反復できます。

      オーバーライド:
      getHeaderField、クラスURLConnection
      パラメータ:
      n - インデックス。ここでn>=0です。
      戻り値:
      n番目のヘッダー・フィールドの値。値が存在しない場合はnull。
      関連項目:

    • setFollowRedirects

      public static void setFollowRedirects(boolean set)
      HTTPリダイレクト(応答コード3xxの要求)に、このクラスが自動的に従うべきかどうかを設定します。 デフォルトはtrueです。 アプレットはこの変数を変更できません。

      セキュリティ・マネージャが存在する場合、この操作が許可されるように、このメソッドは最初にセキュリティ・マネージャのcheckSetFactoryメソッドを呼び出します。 この結果、SecurityExceptionがスローされることがあります。

      パラメータ:
      set - HTTPリダイレクトに従うかどうかを示すboolean。
      例外:
      SecurityException - セキュリティ・マネージャが存在し、そのcheckSetFactoryメソッドでこの操作が許可されていない場合。
      関連項目:

    • getFollowRedirects

      public static boolean getFollowRedirects()
      HTTPリダイレクト(3xx)に自動的に従うかどうかを示すbooleanを返します。
      戻り値:
      HTTPリダイレクトに自動的に従うべきである場合はtrue、そうでない場合はfalse。
      関連項目:

    • setInstanceFollowRedirects

      public void setInstanceFollowRedirects(boolean followRedirects)
      HTTPリダイレクト(応答コード3xxの要求)を、このHttpURLConnectionインスタンスで自動的に従うかどうかを設定します。

      デフォルトがtrueである、followRedirectsからのデフォルト値。

      パラメータ:
      followRedirects - HTTPリダイレクトに従うかどうかを示すboolean。
      導入されたバージョン:
      1.3
      関連項目:

    • getInstanceFollowRedirects

      public boolean getInstanceFollowRedirects()
      このHttpURLConnectionのinstanceFollowRedirectsフィールドの値を返します。
      戻り値:
      このHttpURLConnectionのinstanceFollowRedirectsフィールドの値。
      導入されたバージョン:
      1.3
      関連項目:

    • setRequestMethod

      public void setRequestMethod(String method) throws ProtocolException
      URL要求のメソッドを次のどれかに設定します。
      • GET
      • POST
      • HEAD
      • OPTIONS
      • PUT
      • DELETE
      • TRACE
      これらのメソッドのうち、どれが有効であるかはプロトコルの制限によって決まります。 デフォルトのメソッドはGETです。
      パラメータ:
      method−HTTPメソッド
      例外:
      ProtocolException−メソッドをリセットできない場合、または要求されたメソッドがHTTPで有効でない場合。
      SecurityException - セキュリティ・マネージャが設定され、メソッドが「TRACE」であるが、「allowHttpTrace」のNetPermissionが許可されない場合。
      関連項目:

    • getRequestMethod

      public String getRequestMethod()
      要求メソッドを取得します。
      戻り値:
      HTTP要求メソッド
      関連項目:

    • 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
      文字列「OK」と「Not Found」をそれぞれ抽出します。 応答から何も認識できなかった場合(結果が有効なHTTPではなかった場合)、nullを返します。
      戻り値:
      HTTP応答メッセージまたはnull
      例外:
      IOException - サーバーへの接続でエラーが発生した場合。

    • disconnect

      public abstract void disconnect()
      サーバーへの要求が近い将来発生しそうにないことを示します。 disconnect()の呼出しが、このHttpURLConnectionインスタンスがほかの要求用として再利用可能であることを意味することのないようにしてください。

    • usingProxy

      public abstract boolean usingProxy()
      接続でプロキシを使用するかどうかを表します。 このメソッドは、接続が進行中であるかプロキシを経由したことがわかっている場合はtrueを返し、接続がプロキシを経由しない場合やプロキシの使用を判断できない場合はfalseを返します。
      戻り値:
      この接続がプロキシを使用するかどうかを示すboolean。

    • getPermission

      public Permission getPermission() throws IOException
      接続先のホストとポートに接続するために必要なアクセス権を表すSocketPermissionオブジェクトを返します。
      オーバーライド:
      getPermission、クラスURLConnection
      戻り値:
      接続先のホストとポートに接続するために必要なアクセス権を表すSocketPermissionオブジェクト。
      例外:
      IOException - アクセス権の処理中にエラーが発生した場合。

    • getErrorStream

      public InputStream getErrorStream()
      接続が失敗したが、それにもかかわらずサーバーから有用なデータを送信されてきた場合に、エラー・ストリームを返します。 典型的な例としては、HTTPサーバーが404で応答し、それによって接続内でFileNotFoundExceptionがスローされたが、そのサーバーから対処策を含むHTMLヘルプ・ページが送信されてきた、といった場合です。

      このメソッドを呼び出しても、接続は開始されません。 接続が確立されなかった場合、接続中にサーバーでエラーが発生しなかった場合、またはサーバーでエラーが発生したがエラー・データは送信されなかった場合には、このメソッドはnullを返します。 これはデフォルトです。

      戻り値:
      エラー・ストリームが存在する場合はそのストリーム。エラーが発生しなかった場合、接続が確立されていない場合、またはサーバーが有用なデータを送信しなかった場合はnull。