java.net.URI
|
JavaTM Platform Standard Ed. 6 |
|||||||||
| 前のクラス 次のクラス | フレームあり フレームなし | |||||||||
| 概要: 入れ子 | フィールド | コンストラクタ | メソッド | 詳細: フィールド | コンストラクタ | メソッド | |||||||||
java.lang.Object
public final class URI
URI (Uniform Resource Identifier) 参照を表します。
後述するいくつかの小さな変更を除けば、このクラスのインスタンスは、「RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax」 で定義され、「RFC 2732: Format for Literal IPv6 Addresses in URLs」 で修正された URI 参照を表します。リテラル IPv6 アドレス形式ではスコープ ID もサポートされます。スコープ ID の構文や使用方法については、ここを参照してください。このクラスは、コンポーネントからまたは文字列形式を解析して URI インスタンスを作成するためのコンストラクタ、インスタンスの各種コンポーネントにアクセスするためのメソッド、および URI インスタンスを正規化、解決、相対化するためのメソッドを提供します。このクラスのインスタンスは不変です。
[スキーマ:]スキーマ固有部分[#フラグメント]ここで、角括弧 [...] は省略可能なコンポーネントを表し、文字 : と # はその文字自体を表します。
「絶対」URI はスキーマを指定し、絶対でない URI は「相対」と呼ばれます。また、URI は「不透明」であるか「階層的」であるかによって分類されます。
「不透明」URI は、スキーマ固有部分がスラッシュ (/) で始まらない絶対 URI です。不透明 URI はそれ以上解析されません。不透明 URI の例を次に示します。
mailto:java-net@java.sun.com news:comp.lang.java urn:isbn:096139210x
「階層」 URI は、スキーマ固有部分がスラッシュで始まる絶対 URI、または相対 URI (スキーマを指定しない URI) です。階層 URI の例を次に示します。
http://java.sun.com/j2se/1.3/
docs/guide/collections/designfaq.html#28
../../../demo/jfc/SwingSet2/src/SwingSet2.java
file:///~/calendar
階層 URI は、構文に従ってさらに解析されます。
[スキーマ:][//機関][パス][?クエリー][#フラグメント]ここで、:、/、?、および # はその文字自体を表します。階層 URI のスキーマ固有部分は、スキーマとフラグメントコンポーネントの間の文字で構成されます。
階層 URI の機関コンポーネントが指定されている場合、その機関コンポーネントは「サーバーベース」または「レジストリベース」です。サーバーベース機関は、よく知られている構文に従って解析されます。
[ユーザー情報@]ホスト[:ポート]ここで、@ と : はその文字自体を表します。現在使用されている URI スキーマのほとんどはサーバーベースです。このように解析されない機関コンポーネントは、レジストリベースと見なされます。
階層 URI のパスコンポーネントは、スラッシュ (/) で始まる場合は絶対と呼ばれ、そうでない場合は相対と呼ばれます。絶対である階層 URI または機関を指定する階層 URI のパスコンポーネントは常に絶対です。
URI インスタンスには、全部で次の 9 つのコンポーネントがあります。
指定されたインスタンスでは、どの特定のコンポーネントも「未定義」か「定義済み」であり、個別の型の値を持ちます。未定義の文字列コンポーネントは null で表され、未定義の整数コンポーネントは -1 で表されます。文字列コンポーネントは、値として空の文字列を持つよう定義できます。これは、そのコンポーネントが未定義であることと同等ではありません。
Component 型 スキーマ String スキーマ固有部分 String 機関 String ユーザー情報 String ホスト String port int パス String クエリー String フラグメント String
特定のコンポーネントがインスタンスで定義されるかされないかは、表現される URI の型により異なります。絶対 URI にはスキーマコンポーネントがあります。不透明 URI にはスキーマ、スキーマ固有部分、およびおそらくフラグメントがありますが、その他のコンポーネントはありません。階層 URI には、常にパス (ただし空の場合あり) およびスキーマ固有部分 (少なくともパスを含む) があり、さらにその他のコンポーネントのいずれかがある場合があります。機関コンポーネントが存在していてサーバーベースである場合、ホストコンポーネントは定義されます。ユーザー情報とポートコンポーネントは定義される場合もあります。
「正規化」は、階層 URI のパスコンポーネントから不要な「.」および「..」セグメントを削除するプロセスです。各「.」セグメントは単に削除されます。「..」セグメントは、「..」以外のセグメントが先行する場合にだけ削除されます。正規化は不透明 URI には影響しません。
「解決」とは、ある URI を別の「ベース」URI に基づいて解決する処理のことです。結果として得られる URI は、RFC 2396 に規定された方法に基づいて、両方の URI のコンポーネントから構築されます。具体的には、元の URI で指定されていないコンポーネントについては、ベース URI から取得されます。階層 URI の場合、元のパスは、ベースのパスに基づいて解決されたあと、正規化されます。たとえば、次のようになります。
docs/guide/collections/designfaq.html#28 (1)をベース URI http://java.sun.com/j2se/1.3/ に対して解決すると、結果の URI は次のようになります。
http://java.sun.com/j2se/1.3/docs/guide/collections/designfaq.html#28相対 URI
../../../demo/jfc/SwingSet2/src/SwingSet2.java (2)をこの結果に対して解決すると、次のようになります。
http://java.sun.com/j2se/1.3/demo/jfc/SwingSet2/src/SwingSet2.java絶対と相対の両方の URI の解決、および階層 URI の場合は絶対と相対の両方のパスの解決がサポートされます。URI file:///~calendar は絶対なので、これをほかの任意の URI に対して解決すると、元の URI が生成されるだけです。上記の相対 URI (2) を相対ベース URI (1) に対して解決すると、正規化されていても相対のままの URI が生成されます。
demo/jfc/SwingSet2/src/SwingSet2.java
最後に「相対化」とは、解決の逆です。任意の 2 つの正規化済み URI u と v について、次が成り立ちます。
u.relativize(u.resolve(v)).equals(v) およびこの操作は、可能であればどこででも、ドキュメントのベース URI に対して相対的でなければならない URI を含むドキュメントを構築する場合に便利です。たとえば、次の URI
u.resolve(u.relativize(v)).equals(v)
http://java.sun.com/j2se/1.3/docs/guide/index.htmlを次のベース URI に対して相対化すると、
http://java.sun.com/j2se/1.3相対 URI docs/guide/index.html が生成されます。
英字 A から Z、および a から z までの US-ASCII 英文字 数字 0 から 9 までの US-ASCII 10 進数字 英数字 すべての「英字」および「数字」文字 未予約 すべての「英数字」文字、および文字列「_-!.~'()*」内の文字 句読 文字列「,;:$&+=」内の文字 予約済み すべての「句読」文字、および文字列「?/[]@」内の文字 エスケープ エスケープされたオクテット。つまり、パーセント文字 (%) とそれに続く 2 桁の 16 進数 (0 - 9、A - F、および a - f) で構成される三重項 other US-ASCII 文字セットに含まれておらず、制御文字 ( Character.isISOControlメソッドを使って判定) でなく、空白文字 (Character.isSpaceCharメソッドを使って判定) でない Unicode 文字 (US-ASCII に限定されている RFC 2396 を変更したもの)
すべての有効な URI 文字のセットは「未予約」、「予約済み」、「エスケープ」、および「その他」の文字で構成されます。
URI に「その他」の文字を 1 つも含めないようにすることで URI を RFC 2396 に厳密に準拠させる必要がある場合に、非 US-ASCII 文字を「エンコード」する。
そのままでは不正になるコンポーネント内の文字を「引用符で囲む」。ユーザー情報、パス、クエリー、およびフラグメントの各コンポーネントは、有効または不正と見なされる文字の条件が多少異なる。
文字は UTF-8 文字セット内のその文字を表すエスケープされたオクテットのシーケンスで置き換えて「エンコード」される。たとえば、ユーロ通貨記号 ('\u20AC') は %E2%82%AC としてエンコードされる(特定の文字セットを指定しない RFC 2396 を変更したもの)
すべての不正な文字は、単に符号化して「引用符で囲まれる」。たとえば空白文字は、%20 で置き換えて引用符で囲まれる。UTF-8 には US-ASCII が含まれるので、US-ASCII 文字の場合、この変換で RFC 2396 で要求される効果が正確に得られる
エスケープされたオクテットのシーケンスを「デコード」する。具体的には、そのシーケンスが UTF-8 文字セット内で表している文字シーケンスで置換する。UTF-8 は US-ASCII を含む。したがって、デコード処理は、引用符で囲まれたすべての US-ASCII 文字の引用符を解除する効果と、エンコードされたすべての非 US-ASCII 文字をデコードする効果がある。エスケープされたオクテットのデコード時にデコードエラーが発生した場合、そのエラーの発生した octet は、Unicode 置換文字である「\uFFFD」に置き換えられる。
単一引数コンストラクタ
複数引数コンストラクタ
getRawUserInfo、getRawPath、getRawQuery、getRawFragment、getRawAuthority、および getRawSchemeSpecificPart メソッドは、対応するコンポーネントの値をそのままの形式で返し、エスケープされたオクテットを解釈しない。これらのメソッドから返される文字列には、エスケープされたオクテットと「その他」の文字の両方が含まれていることがあり、不正な文字は含まれない。
getUserInfo、getPath、getQuery、getFragment、getAuthority、および getSchemeSpecificPart メソッドは、対応するコンポーネント内のすべてのエスケープされたオクテットをデコードする。これらのメソッドから返される文字列には、「その他」の文字と不正文字のどちらも含まれる可能性があるが、エスケープされたオクテットが含まれることはない。
toString メソッドは、すべての必要な引用符を持つ URI 文字列を返すが、「その他」の文字が含まれる場合がある。
toASCIIString メソッドは、完全に引用符で囲まれてエンコードされた URI 文字列を返す。この文字列には「その他」の文字は含まれない。
new URI(u.toString()).equals(u)空の機関の前に 2 つのスラッシュがあったり (file:///tmp/ など)、ホスト名のあとにコロンがあってもポートが指定されていなかったり (http://java.sun.com: など) するような冗長構文を含まず、引用符で囲む必要のある文字以外の文字を符号化しない URI u の場合は、次のようになります。
new URI(u.getScheme(),すべての場合において
u.getSchemeSpecificPart(),
u.getFragment())
.equals(u)
new URI(u.getScheme(),u が階層の場合
u.getUserInfo(), u.getAuthority(),
u.getPath(), u.getQuery(),
u.getFragment())
.equals(u)
new URI(u.getScheme(),u が階層で、機関を持たないかサーバーベースの機関を持つ場合
u.getUserInfo(), u.getHost(), u.getPort(),
u.getPath(), u.getQuery(),
u.getFragment())
.equals(u)
URI と URL との概念上の区別は、このクラスと URL クラスの間の相違に反映されています。
このクラスのインスタンスは、RFC 2396 で定義されている構文としての URI 参照を表します。URI は絶対、相対のいずれかになります。URI 文字列は、スキーマが指定されていてもそれについては考慮せず、一般的な構文に従って解析されます。ホストが存在していてもその検索は実行されず、スキーマに依存するストリームハンドラの構築も行われません。等価性、ハッシュ処理、および比較は、インスタンスの文字内容に基づいて厳密に定義されます。言い換えれば、URI インスタンスは基本的に、比較、正規化、解決、および相対化という、スキーマに依存しない構文上の操作をサポートする、構造化された文字列です。
これに対し、URL クラスのインスタンスは、URL の構文上のコンポーネントを表すだけでなく、その記述対象となるリソースへのアクセスに必要な情報も一部備えています。URL は絶対でなければいけません。つまり、常にスキーマを指定しなければいけません。URL 文字列は、そのスキーマに従って解析されます。どの URL に対してもストリームハンドラが必ず確立されます。実際、使用可能なハンドラが存在しないスキーマの URL インスタンスを作成することは不可能です。等価性とハッシュ処理は、スキーマと、ホストのインターネットアドレス (存在する場合) の両方に依存します。比較は定義されません。言い換えれば、URL は、解決という構文上の操作と、ホストの検索や指定されたリソースへの接続のオープンなどのネットワーク入出力操作をサポートする、構造化された文字列です。
| コンストラクタの概要 | |
|---|---|
URI(String str)
指定された文字列を解析して URI を構築します。 |
|
URI(String scheme,
String ssp,
String fragment)
指定されたコンポーネントから URI を構築します。 |
|
URI(String scheme,
String userInfo,
String host,
int port,
String path,
String query,
String fragment)
指定されたコンポーネントから階層 URI を構築します。 |
|
URI(String scheme,
String host,
String path,
String fragment)
指定されたコンポーネントから階層 URI を構築します。 |
|
URI(String scheme,
String authority,
String path,
String query,
String fragment)
指定されたコンポーネントから階層 URI を構築します。 |
|
| メソッドの概要 | |
|---|---|
int |
compareTo(URI that)
この URI を別のオブジェクトと比較します。 |
static URI |
create(String str)
指定された文字列を解析して URI を作成します。 |
boolean |
equals(Object ob)
この URI が別のオブジェクトと等しいかどうかを判定します。 |
String |
getAuthority()
この URI の復号化された機関コンポーネントを返します。 |
String |
getFragment()
この URI の復号化されたフラグメントコンポーネントを返します。 |
String |
getHost()
この URI のホストコンポーネントを返します。 |
String |
getPath()
この URI の復号化されたパスコンポーネントを返します。 |
int |
getPort()
この URI のポート番号を返します。 |
String |
getQuery()
この URI の復号化されたクエリーコンポーネントを返します。 |
String |
getRawAuthority()
この URI のそのままの機関コンポーネントを返します。 |
String |
getRawFragment()
この URI のそのままのフラグメントコンポーネントを返します。 |
String |
getRawPath()
この URI のそのままのパスコンポーネントを返します。 |
String |
getRawQuery()
この URI のそのままのクエリーコンポーネントを返します。 |
String |
getRawSchemeSpecificPart()
この URI のそのままのスキーマ固有部分を返します。 |
String |
getRawUserInfo()
この URI のそのままのユーザー情報コンポーネントを返します。 |
String |
getScheme()
この URI のスキーマコンポーネントを返します。 |
String |
getSchemeSpecificPart()
この URI の復号化されたスキーマ固有部分を返します。 |
String |
getUserInfo()
この URI の復号化されたユーザー情報コンポーネントを返します。 |
int |
hashCode()
この URI のハッシュコード値を返します。 |
boolean |
isAbsolute()
この URI が絶対かどうかを通知します。 |
boolean |
isOpaque()
この URI が不透明かどうかを通知します。 |
URI |
normalize()
この URI のパスを正規化します。 |
URI |
parseServerAuthority()
この URI の機関コンポーネント (定義されている場合) からユーザー情報、ホスト、およびポートの各コンポーネントへの解析を試みます。 |
URI |
relativize(URI uri)
指定された URI をこの URI に対して相対化します。 |
URI |
resolve(String str)
指定された文字列を解析し、その後その文字列をこの URI に対して解決して、新しい URI を構築します。 |
URI |
resolve(URI uri)
指定された URI をこの URI に対して解決します。 |
String |
toASCIIString()
この URI のコンテンツを US-ASCII 文字列として返します。 |
String |
toString()
この URI のコンテンツを文字列として返します。 |
URL |
toURL()
この URI から URL を構築します。 |
| クラス java.lang.Object から継承されたメソッド |
|---|
clone, finalize, getClass, notify, notifyAll, wait, wait, wait |
| コンストラクタの詳細 |
|---|
public URI(String str)
throws URISyntaxException
このコンストラクタは、指定された文字列を解析する際に、「RFC 2396」の付録 A の文法に厳密に従います。ただし、次の点に関しては、文法に従いません。
空の機関コンポーネントは、その後に空でないパス、クエリーコンポーネント、フラグメントコンポーネントが続いている場合にかぎり、許可される。これにより、「file:///foo/bar」などの URI を解析できるようになる。これは、文法では許可されていないが、RFC 2396 の意図するところと思われる。機関コンポーネントが空の場合、ユーザー情報、ホスト、ポートの各コンポーネントは未定義となる。
空の相対パスは許可される。これは、文法では許可されていないが、RFC 2396 の意図するところと思われる。この逸脱の主な結果として、「#foo」のような単独のフラグメントが、空のパスと指定されたフラグメントを持つ相対 URI として解析されるようになる。この URI はベース URI に基づいて解決できるので便利である。
ホストコンポーネント内の IPv4 アドレスは、「RFC 2732」 に従って厳密に解析される。ドットで 4 つに区切られたアドレスの各要素には、3 桁を超える 10 進を含めることはできない。さらに、各要素の値は 255 を超えてはならないという制約があります。
ホストコンポーネント内のホスト名が単一のドメインラベルだけで構成される場合、そのホスト名は「英数字」文字で始まってもかまわない。これは、文法では許可されていないが、「RFC 2396」のセクション 3.2.2 の意図するところと思われる。この変更の結果として、s://123 のような階層 URI の機関コンポーネントが、サーバーベース機関として解析されるようになる。
ホストコンポーネントで IPv6 アドレスの使用が許可される。「RFC 2732」に従って、IPv6 アドレスは角括弧 (「[」と「]」) で囲まなければいけない。IPv6 アドレス自体は、RFC 2373 に従って解析されなければいけない。IPv6 アドレスはさらに、16 バイトを超えないアドレス情報を記述するよう制約される。この制約は、RFC 2373 で暗黙的に示されているが、文法では表現できません。
「その他」のカテゴリに含まれる文字は、RFC 2396 が「エスケープ」 octet の使用を許可している場所であればどこでも使用できる。つまり、ユーザー情報、パス、クエリー、フラグメントの各コンポーネント内で使用できる。さらに、機関がレジストリベースであれば、機関コンポーネント内でも使用できる。これにより、US-ASCII 文字セットに含まれる文字以外の Unicode 文字を、URI に含めることができるようになる。
str - URI に解析される文字列
NullPointerException - str が null の場合
URISyntaxException - 上記の変更によって拡張された RFC 2396 に、指定された文字列が違反する場合
public URI(String scheme,
String userInfo,
String host,
int port,
String path,
String query,
String fragment)
throws URISyntaxException
スキーマが指定され、パスも指定された場合、そのパスは空であるか、スラッシュ文字 (「/」) で始まっていなければいけません。そうでない場合、新しい URI のコンポーネントは、対応するパラメータに null を渡すか、port パラメータの場合は -1 を渡して、未定義のままになることがあります。
このコンストラクタはまず、次のように指定されたコンポーネントから URI 文字列を構築しますが、その際、「RFC 2396」のセクション 5.2 のステップ 7 に記載されている規則に従います。
最初、結果文字列は空になっている。
スキーマが指定されている場合、そのスキーマが結果の末尾に追加され、その後にコロン文字 (「:」) が追加される。
ユーザー情報、ホスト、またはポートが指定されている場合、文字列「//」が末尾に追加される。
ユーザー情報が指定されている場合、そのユーザー情報が末尾に追加され、その後に単価記号 (「@」) が追加される。「未予約」、「句読」、「エスケープ」、「その他」のどのカテゴリにも含まれない文字はすべて、引用符で囲まれる。
ホストが指定されている場合、そのホストが末尾に追加される。ホストがリテラル IPv6 アドレスであるが、角括弧 (「[」と「]」) で囲まれていない場合は、角括弧が追加される。
ポート番号が指定されている場合、コロン文字 (「:」) が末尾に追加され、その後にその 10 進数のポート番号が追加される。
パスが指定されている場合、そのパスが末尾に追加される。「未予約」、「句読」、「エスケープ」、「その他」のどのカテゴリにも含まれず、スラッシュ文字 (「/」)、単価記号 (「@」) のどちらとも等しくない文字はすべて、引用符で囲まれる。
クエリーが指定されている場合、疑問符文字 (「?」) が末尾に追加され、その後にそのクエリーが追加される。適正な URI 文字でない文字はすべて、引用符で囲まれる。
最後に、フラグメントが指定されている場合、ハッシュ文字 (「#」) が末尾に追加され、その後にそのフラグメントが追加される。適正な URI 文字でない文字はすべて、引用符で囲まれる。
結果として得られる URI 文字列が解析されますが、この解析は、URI(String) コンストラクタを呼び出したあと、その結果に対して parseServerAuthority() メソッドを呼び出したかのように行われます。これにより、URISyntaxException がスローされる可能性があります。
scheme - スキーマ名userInfo - ユーザー名と認証情報host - ホスト名port - ポート番号path - パスquery - クエリーfragment - フラグメント
URISyntaxException - スキーマとパスの両方が指定されているがパスが相対の場合、指定されたコンポーネントから構築された URI 文字列が RFC 2396 に違反する場合、または文字列の機関コンポーネントが存在するがサーバーベースの機関として解析できない場合
public URI(String scheme,
String authority,
String path,
String query,
String fragment)
throws URISyntaxException
スキーマが指定され、パスも指定された場合、そのパスは空であるか、スラッシュ文字 (「/」) で始まっていなければいけません。そうでない場合、新しい URI のコンポーネントは、対応するパラメータに null を渡して、未定義のままになることがあります。
このコンストラクタはまず、次のように指定されたコンポーネントから URI 文字列を構築しますが、その際、「RFC 2396」のセクション 5.2 のステップ 7 に記載されている規則に従います。
最初、結果文字列は空になっている。
スキーマが指定されている場合、そのスキーマが結果の末尾に追加され、その後にコロン文字 (「:」) が追加される。
機関が指定されている場合、文字列「//」が末尾に追加され、その後にその機関が追加される。機関にリテラル IPv6 アドレスが含まれる場合、そのアドレスを角括弧 (「[」と「]」) で囲む必要がある。「未予約」、「句読」、「エスケープ」、「その他」のどのカテゴリにも含まれず、単価記号 (「@」) と等しくない文字はすべて、引用符で囲まれる。
パスが指定されている場合、そのパスが末尾に追加される。「未予約」、「句読」、「エスケープ」、「その他」のどのカテゴリにも含まれず、スラッシュ文字 (「/」)、単価記号 (「@」) のどちらとも等しくない文字はすべて、引用符で囲まれる。
クエリーが指定されている場合、疑問符文字 (「?」) が末尾に追加され、その後にそのクエリーが追加される。適正な URI 文字でない文字はすべて、引用符で囲まれる。
最後に、フラグメントが指定されている場合、ハッシュ文字 (「#」) が末尾に追加され、その後にそのフラグメントが追加される。適正な URI 文字でない文字はすべて、引用符で囲まれる。
結果として得られる URI 文字列が解析されますが、この解析は、URI(String) コンストラクタを呼び出したあと、その結果に対して parseServerAuthority() メソッドを呼び出したかのように行われます。これにより、URISyntaxException がスローされる可能性があります。
scheme - スキーマ名authority - 機関path - パスquery - クエリーfragment - フラグメント
URISyntaxException - スキーマとパスの両方が指定されているがパスが相対の場合、指定されたコンポーネントから構築された URI 文字列が RFC 2396 に違反する場合、または文字列の機関コンポーネントが存在するがサーバーベースの機関として解析できない場合
public URI(String scheme,
String host,
String path,
String fragment)
throws URISyntaxException
コンポーネントは、null を渡して未定義のままになることがあります。
この簡易コンストラクタは、次のように 7 つの引数のコンストラクタを呼び出すかのように動作します。
new URI(scheme, null, host, -1, path, null, fragment);
scheme - スキーマ名host - ホスト名path - パスfragment - フラグメント
URISyntaxException - 指定されたコンポーネントから構築された URI 文字列が RFC 2396 に違反する場合
public URI(String scheme,
String ssp,
String fragment)
throws URISyntaxException
コンポーネントは、null を渡して未定義のままになることがあります。
このコンストラクタはまず、次のように指定されたコンポーネントを使って文字列形式の URI を構築します。
最初、結果文字列は空になっている。
スキーマが指定されている場合、そのスキーマが結果の末尾に追加され、その後にコロン文字 (「:」) が追加される。
スキーマ固有部分が指定されている場合、そのスキーマ固有部分が末尾に追加される。適正な URI 文字でない文字はすべて、引用符で囲まれる。
最後に、フラグメントが指定されている場合、ハッシュ文字 (「#」) が文字列の末尾に追加され、その後にそのフラグメントが追加される。適正な URI 文字でない文字はすべて、引用符で囲まれる。
新しい URI インスタンスを作成するために結果として得られる URI 文字列が解析されますが、この解析は、URI(String) コンストラクタを呼び出したかのように行われます。これにより、URISyntaxException がスローされる可能性があります。
scheme - スキーマ名ssp - スキーマ固有部分fragment - フラグメント
URISyntaxException - 指定されたコンポーネントから構築された URI 文字列が RFC 2396 に違反する場合| メソッドの詳細 |
|---|
public static URI create(String str)
この簡易ファクトリメソッドは、URI(String) コンストラクタを呼び出したかのように動作します。このコンストラクタからスローされた URISyntaxException はすべて、キャッチされて新しい IllegalArgumentException オブジェクト内にラップされたあと、スローされます。
このメソッドは、プログラム内で宣言された URI 定数のように、与えられた文字列が適正な URI であることがあらかじめわかっているために、文字列がそのように解析されない場合はプログラミングエラーとみなされるような状況で使用するために提供されています。ユーザー入力や、エラーが含まれる可能性の高いその他の何らかのソースに基づいて URI が構築されるような状況では、URISyntaxException を直接スローするコンストラクタを使用するようにしてください。
str - URI に解析される文字列
NullPointerException - str が null の場合
IllegalArgumentException - 指定された文字列が RFC 2396 に違反する場合
public URI parseServerAuthority()
throws URISyntaxException
この URI の機関コンポーネントがすでにサーバーベースとして認識されている場合には、それはすでに解析されてユーザー情報、ホスト、ポートの各コンポーネントに分離されています。この場合、またはこの URI が機関コンポーネントを持たない場合には、このメソッドはこの URI をそのまま返します。
そうでない場合、このメソッドは機関コンポーネントからユーザー情報、ホスト、およびポートの各コンポーネントへの解析をもう一度試み、機関コンポーネントがそのように解析できなかった理由を説明する例外をスローします。
このメソッドが提供されているのは、「RFC 2396」 に指定されている総称 URI 構文が、不正なサーバーベース機関と適正なレジストリベース機関とを常に区別できるとはかぎらないからです。このため、それは、前者のケースの一部を後者のケースとして扱わなければいけません。たとえば、URI 文字列「//foo:bar」内の機関コンポーネントは、適正なサーバーベース機関ではありませんが、レジストリベース機関としては適正です。
URN、URL のどちらかであることがわかっている URI を操作する場合のような、多くの一般的な状況では、使用される階層 URI は常にサーバーベースになります。したがって、それらはそのように解析されるか、エラーとして処理されるかのどちらかでなければいけません。これらの場合、
URI u = new URI(str).parseServerAuthority();
のような文を使えば、u が参照する URI に機関コンポーネントが含まれる場合に、その機関が常に適切なユーザー情報、ホスト、ポートの各コンポーネントを含むサーバーベース機関であることを保証できます。また、このメソッドを呼び出せば、機関をそのように解析できなかった場合にも、スローされた例外に基づいて適切な診断メッセージを確実に発行できます。
URISyntaxException - この URI の機関コンポーネントが指定されているが、RFC 2396 に従ってサーバーベース機関として解析できない場合public URI normalize()
この URI が不透明である場合、またはそのパスがすでに正規化された形式になっている場合は、この URI が返されます。そうでない場合は、この URI と同じ新しい URI が構築されます。ただし、そのパスが「RFC 2396」のセクション 5.2、ステップ 6、サブステップ c から f に準拠した方法でこの URI のパスを正規化して求められる場合を除きます。次のようになります。
すべての「.」セグメントが削除される。
「..」セグメントの直前に「..」以外のセグメントが存在する場合、その両方のセグメントが削除される。この手順が該当しなくなるまで繰り返される。
パスが相対であり、その最初のセグメントにコロン文字 (「:」) が含まれている場合、その前に「.」セグメントが追加される。これにより、「a:b/c/d」のようなパスを含む相対 URI が、スキーマ「a」とスキーマ固有部分「b/c/d」を持つ不透明 URI として、あとで再度解析されてしまうのを防ぐことができる。(RFC 2396 からの変更)
正規化されたパスは、削除を可能にする「..」でない先行のセグメントが不十分だった場合、1 つ以上の「..」セグメントで始まります。正規化されたパスが「.」セグメントで始まるのは、上記の手順 3 でそのようなセグメントが挿入された場合です。それ以外の場合は、正規化されたパスに「.」セグメントや「..」セグメントが含まれることはありません。
public URI resolve(URI uri)
指定された URI がすでに絶対である場合、またはこの URI が不透明である場合は、指定された URI が返されます。
指定された URI のフラグメントコンポーネントが定義済みであり、パスコンポーネントが空であり、スキーマ、機関、クエリーの各コンポーネントが未定義である場合、指定されたフラグメントを持つが、それ以外のすべてのコンポーネントはこの URI の値に等しいような URI が返されます。これにより、「#foo」のような単独のフラグメント参照を表す URI をベース URI に基づいて解析できるようになるので便利です。
そうでない場合、このメソッドは、「RFC 2396」のセクション 5.2 に適合する方法で新しい階層 URI を構築します。次のようになります。
この URI のスキーマと指定された URI のクエリーおよびフラグメントコンポーネントを使用して、新しい URI が構築される。
指定された URI に機関コンポーネントがある場合、新しい URI の機関とパスは指定された URI から取られる。
そうでない場合、新しい URI の機関コンポーネントがこの URI からコピーされ、そのパスは次のようにして求められる。
指定された URI のパスが絶対の場合、新しい URI のパスは指定された URI から取られる。
それ以外の場合、指定された URI のパスは相対なので、この URI のパスに基づいて指定された URI のパスを解決することで、新しい URI のパスが計算される。これを行うには、この URI のパス (存在する場合) の最後のセグメント以外のすべてのセグメントを指定された URI のパスに連結したあと、その結果を normalize メソッドを呼び出したかのように正規化する。
このメソッドの結果は、この URI が絶対の場合、または指定された URI が絶対の場合にだけ、絶対になります。
uri - この URI に対して解決される URI
NullPointerException - uri が null の場合public URI resolve(String str)
この簡易メソッドは、このメソッドの呼び出しが式 resolve(URI.create(str)) の評価と同じであるかのように動作します。
str - URI に解析される文字列
NullPointerException - str が null の場合
IllegalArgumentException - 指定された文字列が RFC 2396 に違反する場合public URI relativize(URI uri)
指定された URI のこの URI に対する相対化は、次のようにして求められます。
この URI または指定された URI が不透明である場合、2 つの URI のスキーマと機関コンポーネントが同じでない場合、またはこの URI のパスが指定された URI のパスの接頭辞でない場合は、指定されたURI が返される。
そうでない場合、指定された URI から取られたクエリーおよびフラグメントコンポーネントと、指定された URI のパスの先頭からこの URI のパスを削除して求めたパスコンポーネントを使用して、新しい相対階層 URI が構築される。
uri - この URI に対して相対化される URI
NullPointerException - uri が null の場合
public URL toURL()
throws MalformedURLException
この簡易メソッドは、最初にこの URI が絶対であることを確認してから、このメソッドの呼び出しが式 new URL(this.toString()) の評価と同じであるかのように動作します。
IllegalArgumentException - この URL が絶対でない場合
MalformedURLException - URL のプロトコルハンドラが見つからなかった場合、または URL の構築中にその他の何らかのエラーが発生した場合public String getScheme()
URI のスキーマコンポーネントが定義されている場合、そのコンポーネントに含まれるのは、「英数字」カテゴリまたは文字列「-.+」に含まれる文字だけです。スキーマは常に、「英字」文字で始まります。
URI のスキーマコンポーネントにエスケープされたオクテットを含めることはできません。したがって、このメソッドはデコードを実行しません。
public boolean isAbsolute()
URI が絶対であるのは、その URI にスキーマコンポーネントがある場合だけです。
public boolean isOpaque()
URI が不透明であるのは、その URI が絶対であり、そのスキーマ固有部分がスラッシュ文字 (「/」) で始まっていない場合だけです。不透明 URI は、スキーマとスキーマ固有部分を持つほか、場合によってはフラグメントも持ちます。その他のコンポーネントはすべて未定義となります。
public String getRawSchemeSpecificPart()
URI のスキーマ固有部分には、有効な URI 文字だけが含まれます。
public String getSchemeSpecificPart()
このメソッドから返される文字列は、getRawSchemeSpecificPart メソッドから返される文字列とほぼ同じです。異なるのは、エスケープされたオクテットのシーケンスがすべてデコードされている点だけです。
public String getRawAuthority()
URI の機関コンポーネントが定義されている場合、そのコンポーネントに含まれるのは、単価記号 (「@」) と、「未予約」、「句読」、「エスケープ」、「その他」のいずれかのカテゴリに含まれる文字だけです。機関がサーバーベースである場合、その機関はさらに、有効なユーザー情報、ホスト、ポートの各コンポーネントを持つように制約されます。
public String getAuthority()
このメソッドから返される文字列は、getRawAuthority メソッドから返される文字列とほぼ同じです。異なるのは、エスケープされたオクテットのシーケンスがすべてデコードされている点だけです。
public String getRawUserInfo()
URI のユーザー情報コンポーネントには (定義されている場合)、「未予約」、「句読」、「エスケープ」、および「その他」のカテゴリの文字だけが含まれます。
public String getUserInfo()
このメソッドから返される文字列は、getRawUserInfo メソッドから返される文字列とほぼ同じです。異なるのは、エスケープされたオクテットのシーケンスがすべてデコードされている点だけです。
public String getHost()
URI のホストコンポーネント (定義されている場合) の形式は、次のいずれかです。
ドメイン名。1 つ以上の「ラベル」をピリオド文字 (「.」) で区切った形式になります。末尾にピリオド文字を 1 つ付けてもかまいません。各ラベルは「英数字」文字とハイフン文字 (「-」) から構成されます。ただし、ハイフンがラベル内の先頭または末尾の文字として使用されることはありません。2 つ以上のラベルで構成されるドメイン名のもっとも右側のラベルは、「英字」文字で始まります。
数字+.数字+.数字+.数字+ の形式の、ドットで 4 つに区分された IPv4 アドレス。ここで、数字は 3 文字以内で、その値は 255 を超えません。
IPv6 アドレス。角括弧 (「[」と「]」) で囲まれ、16 進数、コロン文字 (「:」)、および場合によっては埋め込み IPv4 アドレスで構成されます。IPv6 アドレスの完全な構文は、「RFC 2373: IPv6 Addressing Architecture」で指定されています。
public int getPort()
URI のポートコンポーネントは (定義されている場合)、負でない整数です。
public String getRawPath()
URI のパスコンポーネントには (定義されている場合)、スラッシュ (/)、単価記号 (@) と、「未予約」、「句読」、「エスケープ」、および「その他」のカテゴリの文字だけが含まれます。
public String getPath()
このメソッドから返される文字列は、getRawPath メソッドから返される文字列とほぼ同じです。異なるのは、エスケープされたオクテットのシーケンスがすべてデコードされている点だけです。
public String getRawQuery()
URI のクエリーコンポーネントには (定義されている場合)、有効な URI 文字だけが含まれます。
public String getQuery()
このメソッドから返される文字列は、getRawQuery メソッドから返される文字列とほぼ同じです。異なるのは、エスケープされたオクテットのシーケンスがすべてデコードされている点だけです。
public String getRawFragment()
URI のフラグメントコンポーネントには (定義されている場合)、有効な URI 文字だけが含まれます。
public String getFragment()
このメソッドから返される文字列は、getRawFragment メソッドから返される文字列とほぼ同じです。異なるのは、エスケープされたオクテットのシーケンスがすべてデコードされている点だけです。
public boolean equals(Object ob)
指定されたオブジェクトが URI でない場合、このメソッドは直ちに false を返します。
2 つの URI が等しいとみなされるには、どちらも不透明 URI であるか、どちらも階層 URI である必要があります。スキーマは、どちらも未定義であるか、大文字と小文字を区別しない場合に等しくなければいけません。フラグメントは、どちらも未定義であるか、等しくなければいけません。
等しいと見なされる 2 つの不透明 URI の場合、それらのスキーマ固有部分は等しい必要があります。
2 つの階層 URI が等しいとみなされるには、パスが等しく、クエリーがどちらも未定義であるか等しくなければいけません。機関は、どちらも未定義であるか、どちらもレジストリベースであるか、どちらもサーバーベースでなければいけません。機関が定義されており、レジストリベースである場合、それらの機関は等しくなければいけません。機関が定義されており、サーバーベースである場合、大文字と小文字を区別しない場合にホストが等しく、ポート番号が等しく、ユーザー情報コンポーネントが等しくなければいけません。
2 つの URI のユーザー情報、パス、クエリー、フラグメント、機関、またはスキーマ固有部分が等しいかどうか判定する場合、これらのコンポーネントは符号化された形式でなくそのままの形式で比較され、エスケープ octet の 16 進数は大文字小文字に関係なく比較されます。
このメソッドは Object.equals メソッドの汎用規約を満たします。
Object 内の equalsob - このオブジェクトと比較するオブジェクト
Object.hashCode(),
Hashtablepublic int hashCode()
Object.hashCode メソッドの汎用規約を満たします。
Object 内の hashCodeObject.equals(java.lang.Object),
Hashtablepublic int compareTo(URI that)
2 つの URI の対応するコンポーネントを比較する際に、一方のコンポーネントが未定義であるのに他方が定義済みであった場合、前者のほうが後者よりも小さいとみなされます。特に明記されていないかぎり、文字列コンポーネントは、String.compareTo メソッドで定義されているように、本来の大文字小文字を区別した順序に従って順序付けられます。エンコードの対象となる文字列コンポーネントの比較は、エンコードされた形式ではなくそのままの形式で比較されます。
URI の順序は次のように定義されます。
異なるスキーマを持つ 2 つの URI は、大文字小文字に関係なくそれらのスキーマの順序に従って順序付けられる。
階層 URI は、同じスキーマを持つ不透明 URI より小さいと見なされる。
同じスキーマを持つ 2 つの不透明 URI は、それらのスキーマ固有部分の順序に従って順序付けられる。
同じスキーマとスキーマ固有部分を持つ 2 つの不透明 URI は、それらのフラグメントの順序に従って順序付けられる。
同じスキーマを持つ 2 つの階層 URI は、それらの機関コンポーネントの順序に従って順序付けられる。
両方の機関コンポーネントがサーバーベースである場合、URI はそれらのユーザー情報コンポーネントに従って順序付けられる。これらのコンポーネントが同じである場合、URI は大文字小文字に関係なくそれらのホストの順序に従って順序付けられる。ホストが同じである場合、URI はそれらのポートの順序に従って順序付けられる。
一方または両方の機関コンポーネントがレジストリベースである場合、URI はそれらの機関コンポーネントの順序に従って順序付けられる。
最後に、同じスキーマと機関コンポーネントを持つ 2 つの階層 URI は、それらのパスの順序に従って順序付けられる。パスが同じである場合、そららの階層 URI は、それらのクエリーの順序に従って順序付けられる。クエリーが同じである場合は、それらのフラグメントの順序に従って順序付けられる。
このメソッドは Comparable.compareTo メソッドの汎用規約を満たします。
Comparable<URI> 内の compareTothat - この URI と比較するオブジェクト
ClassCastException - 指定されたオブジェクトが URI でない場合public String toString()
この URI がこのクラスのいずれかのコンストラクタを呼び出すことで作成されたものである場合、元の入力文字列と等価な文字列、または最初に指定されたコンポーネントから適宜計算された文字列と等価な文字列が返されます。それ以外の場合、この URI は正規化、解決、または相対化によって作成されたものなので、「RFC 2396」のセクション 5.2、ステップ 7 の規則に従って、この URI のコンポーネントから文字列が構築されます。
Object 内の toStringpublic String toASCIIString()
この URI に「その他」カテゴリの文字が 1 つも含まれていない場合、このメソッドを呼び出すと、toString メソッド呼び出し時と同じ値が返されます。それ以外の場合、そのメソッドの呼び出し後に結果をエンコードしたかのように、このメソッドは動作します。
|
JavaTM Platform Standard Ed. 6 |
|||||||||
| 前のクラス 次のクラス | フレームあり フレームなし | |||||||||
| 概要: 入れ子 | フィールド | コンストラクタ | メソッド | 詳細: フィールド | コンストラクタ | メソッド | |||||||||
Copyright 2009 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Documentation Redistribution Policy も参照してください。