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

クラスHttpURLConnection

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

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

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

    セキュリティ権限

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

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

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

    • フィールドの詳細

      • 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の値に基づきます。

        関連項目:
        setInstanceFollowRedirects(boolean), getInstanceFollowRedirects(), setFollowRedirects(boolean)

      • 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
        関連項目:
        setChunkedStreamingMode(int)

      • 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
        関連項目:
        setFixedLengthStreamingMode(int)

      • getHeaderField

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

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

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

      • setFollowRedirects

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

        セキュリティ・マネージャが存在する場合、この操作が許可されるように、このメソッドは最初にセキュリティ・マネージャの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)
        HTTPリダイレクト(応答コード3xxの要求)を、このHttpURLConnectionインスタンスで自動的に従うかどうかを設定します。

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

        パラメータ:
        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で有効でない場合。
        SecurityException - セキュリティ・マネージャが設定され、メソッドが「TRACE」であるが、「allowHttpTrace」のNetPermissionが許可されない場合。
        関連項目:
        getRequestMethod()

      • 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()
        接続でプロキシを使用するかどうかを表します。
        戻り値:
        この接続がプロキシを使用するかどうかを示すboolean。

      • getPermission

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

      • getErrorStream

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

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

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