|
Foundation 1.1.2 | |||||||||
前のクラス 次のクラス | フレームあり フレームなし | |||||||||
概要: 入れ子 | フィールド | コンストラクタ | メソッド | 詳細: フィールド | コンストラクタ | メソッド |
java.lang.Object java.net.URI
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 参照を表します。このクラスは、コンポーネントからまたは文字列形式を解析して 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 ポート 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 をベース 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 を含むドキュメントを構築する場合に便利です。次に例を示します。
u.resolve(u.relativize(v)).equals(v)
http://java.sun.com/j2se/1.3/docs/guide/index.html上の URI を次のベース 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) で構成される三重項 その他 US-ASCII 文字セットに含まれておらず、制御文字 ( Character.isISOControl
メソッドを使って判定) でなく、空白文字 (Character.isSpaceChar
メソッドを使って判定) でない Unicode 文字 (US-ASCII に限定されている RFC 2396 を変更したもの)
不正な文字は、単にエンコードして「引用符」で囲まれます。たとえば空白文字は、%20 で置き換えて引用符で囲まれます。UTF-8 には US-ASCII が含まれるので、US-ASCII 文字の場合、この変換で RFC 2396 で要求される効果が正確に得られます。
エスケープされたオクテットのシーケンスを「デコード」します。具体的には、そのシーケンスが UTF-8 文字セット内で表している文字シーケンスで置換します。UTF-8 は US-ASCII を含みます。したがって、デコード処理は、引用符で囲まれたすべての US-ASCII 文字の引用符を解除する効果と、エンコードされたすべての非 US-ASCII 文字をデコードする効果があります。エスケープされたオクテットのデコード時にデコードエラーが発生した場合、そのエラーの発生した octet は、Unicode 置換文字である「\uFFFD」に置き換えられます。 URI と URL との概念上の区別は、このクラスと このクラスのインスタンスは、RFC 2396 で定義されている構文としての URI 参照を表します。URI は絶対、相対のいずれかになります。URI 文字列は、スキーマが指定されていてもそれについては考慮せず、一般的な構文に従って解析されます。ホストが存在していてもその検索は実行されず、スキーマに依存するストリームハンドラの構築も行われません。等価性、ハッシュ処理、および比較は、インスタンスの文字内容に基づいて厳密に定義されます。言い換えれば、URI インスタンスは基本的に、比較、正規化、解決、および相対化という、スキーマに依存しない構文上の操作をサポートする、構造化された文字列です。
これに対し、URL クラスのインスタンスは、URL の構文的コンポーネント、および URL が記述するリソースへのアクセスに必要な情報の一部を表します。URL は絶対である必要があります。つまり、常にスキーマを指定する必要があります。URL 文字列はそのスキーマに従って解析されます。ストリームハンドラは常に URL 用に確立され、事実、ハンドラが使用できないスキーマの URL インスタンスを作成することはできません。同等性とハッシュは、もしあれば、スキーマとホストのインターネットアドレスの両方に依存します。比較は定義されません。つまり、URL は、解決の構文的操作と、ホストを参照し、指定されたリソースへの接続を開くネットワーク入出力操作をサポートする構造化文字列です。
単一引数コンストラクタ
は、その引数内のすべての不正文字を引用符で囲むことを要求しますが、存在するエスケープされたオクテットと「その他」の文字はすべてそのまま維持します。
複数引数コンストラクタ
は、不正文字を含むコンポーネントからの要求に従って不正文字を引用符で囲みます。パーセント文字 (「%」) は常に、これらのコンストラクタによって囲まれます。「その他」の文字はすべてそのまま維持されます。
getRawUserInfo
、getRawPath
、getRawQuery
、getRawFragment
、getRawAuthority
、および getRawSchemeSpecificPart
メソッドは、対応するコンポーネントの値をそのままの形式で返し、エスケープされたオクテットを解釈しません。これらのメソッドから返される文字列には、エスケープされたオクテットと「その他」の文字の両方が含まれていることがあり、不正な文字は含まれません。 getUserInfo
、getPath
、getQuery
、getFragment
、getAuthority
、および getSchemeSpecificPart
メソッドは、対応するコンポーネント内のすべてのエスケープされたオクテットをデコードします。これらのメソッドから返される文字列には、「その他」の文字と不正文字のどちらも含まれる可能性がありますが、エスケープされたオクテットが含まれることはありません。 toString
メソッドは、すべての必要な引用符を持つ URI 文字列を返しますが、「その他」の文字が含まれる場合があります。
toASCIIString
メソッドは、完全に引用符で囲まれてエンコードされた URI 文字列を返します。この文字列には「その他」の文字は含まれません。 アイデンティティー
任意の URI u の場合に、常に次のようになります。
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、および URN
URI は Uniform Resource Identifier であり、URL は Uniform Resource Locator です。したがって、抽象的に言えば、すべての URL は URI ですが、すべての URI が URL であるとはかぎりません。これは、URI の別のサブカテゴリである URN (Uniform Resource Names) があるためです。URN はリソースに名前を付けますが、その検索方法は指定しません。前に示した mailto、news、および isbn の各 URI は、URN の例です。
URL
クラスの間の相違に反映されています。
RFC 2373:IPv6 Addressing
Architecture、
RFC 2396:Uniform
Resource Identifiers (URI):Generic Syntax、
RFC 2732:Format for
Literal IPv6 Addresses in URLs、
URISyntaxException,
直列化された形式
コンストラクタの概要 | |
---|---|
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(Object ob)
この 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 のパスに連結したあと、その結果を このメソッドの結果は、この URI が絶対の場合、または指定された URI が絶対の場合にだけ、絶対になります。
normalize
メソッドを呼び出したかのように正規化します。
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
メソッドの汎用規約を満たします。
ob
- このオブジェクトと比較するオブジェクト
Object.hashCode()
,
Hashtable
public int hashCode()
Object.hashCode
メソッドの汎用規約を満たします。
Object.equals(java.lang.Object)
,
Hashtable
public int compareTo(Object ob)
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
内の compareTo
ob
- この URI と比較するオブジェクト
ClassCastException
- 指定されたオブジェクトが URI でない場合public String toString()
この URI がこのクラスのいずれかのコンストラクタを呼び出すことで作成されたものである場合、元の入力文字列と等価な文字列、または最初に指定されたコンポーネントから適宜計算された文字列と等価な文字列が返されます。それ以外の場合、この URI は正規化、解決、または相対化によって作成されたものなので、RFC 2396 のセクション 5.2、ステップ 7 の規則に従って、この URI のコンポーネントから文字列が構築されます。
public String toASCIIString()
この URI に「その他」カテゴリの文字が 1 つも含まれていない場合、このメソッドを呼び出すと、toString
メソッド呼び出し時と同じ値が返されます。それ以外の場合、そのメソッドの呼び出し後に結果をエンコードしたかのように、このメソッドは動作します。
|
Foundation 1.1.2 | |||||||||
前のクラス 次のクラス | フレームあり フレームなし | |||||||||
概要: 入れ子 | フィールド | コンストラクタ | メソッド | 詳細: フィールド | コンストラクタ | メソッド |
Copyright 2006 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Documentation Redistribution Policy も参照してください。