モジュール 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
関連項目:
disconnect()

  • フィールド詳細

  • コンストラクタの詳細

    • 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()

    • 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
      文字列「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。