java.net

クラス URI

java.lang.Object

java.net.URI

すべての実装されたインタフェース:

Serializable, Comparable<URI>

public final class URI
extends Object
implements Comparable<URI>, Serializable

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 は、スキーム固有部分がスラッシュ (「/」) で始まらない絶対 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 つのコンポーネントがあります。

コンポーネント	型
スキーム	String
スキーム固有部分	String
機関	String
ユーザー情報	String
ホスト	String
ポート	int
パス	String
クエリー	String
フラグメント	String

指定されたインスタンスでは、どの特定のコンポーネントも未定義か定義済みであり、個別の型の値を持ちます。未定義の文字列コンポーネントは null で表され、未定義の整数コンポーネントは -1 で表されます。文字列コンポーネントは、値として空の文字列を持つよう定義できます。これは、そのコンポーネントが未定義であることと同等ではありません。

特定のコンポーネントがインスタンスで定義されるかされないかは、表現される URI の型により異なります。絶対 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) および
u.resolve(u.relativize(v)).equals(v) 。

この操作は、可能であればどこででも、ドキュメントのベース URI に対して相対的でなければならない URI を含むドキュメントを構築する場合に便利です。たとえば、次の URI

http://java.sun.com/j2se/1.3/docs/guide/index.html

を次のベース URI に対して相対化すると、

http://java.sun.com/j2se/1.3

相対 URI docs/guide/index.html が生成されます。

文字カテゴリ

URI 参照の各種コンポーネントで許可される文字は、RFC 2396 で厳密に指定されています。次のカテゴリを使用して、この制約について説明します。これらのカテゴリのほとんどはその仕様から取られています。

英字	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 を変更したもの)

すべての有効な URI 文字のセットは未予約、予約済み、エスケープ、およびその他の文字で構成されます。

エスケープオクテット、引用符、エンコーディング、およびデコーディング

RFC 2396 では、エスケープオクテットをユーザー情報、パス、クエリー、およびフラグメントの各コンポーネントに表示することができます。URI におけるエスケープ処理の目的は、次の 2 つです。

• URI にその他の文字を 1 つも含めないようにすることで URI を RFC 2396 に厳密に準拠させる必要がある場合に、非 US-ASCII 文字をエンコードする。

• そのままでは不正になるコンポーネント内の文字を引用符で囲む。ユーザー情報、パス、クエリー、およびフラグメントの各コンポーネントは、有効または不正と見なされる文字の条件が多少異なる。

これらの目的のため、このクラスには次の 3 つの関連操作が用意されています。

• 文字は 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 文字をデコードする効果がある。エスケープされたオクテットのデコード時にデコードエラーが発生した場合、そのエラーの発生したオクテットは、Unicode 置換文字である uFFFD に置き換えられる。

これらの操作は、次に示すように、このクラスのコンストラクタとメソッドで公開されます。

• 単一引数コンストラクタ は、その引数内のすべての不正文字が引用符で囲むことを要求するが、存在するエスケープされたオクテットとその他の文字はすべてそのまま維持する。

• 複数引数コンストラクタ は、不正文字を含むコンポーネントからの要求に従って不正文字を引用符で囲む。パーセント文字 (%) は常に、これらのコンストラクタによって囲まれる。その他の文字はすべてそのまま維持される。

• 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.getUserInfo(), u.getAuthority(),
u.getPath(), u.getQuery(),
u.getFragment())
.equals(u)

u が階層の場合

new URI(u.getScheme(),
u.getUserInfo(), u.getHost(), u.getPort(),
u.getPath(), u.getQuery(),
u.getFragment())
.equals(u)

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 の例です。

URI と URL との概念上の区別は、このクラスと URL クラスの間の相違に反映されています。

このクラスのインスタンスは、RFC 2396 で定義されている構文としての URI 参照を表します。URI は絶対、相対のいずれかになります。URI 文字列は、スキームが指定されていてもそれについては考慮せず、ジェネリックな構文に従って解析されます。ホストが存在していてもその検索は実行されず、スキームに依存するストリームハンドラの構築も行われません。等価性、ハッシュ処理、および比較は、インスタンスの文字内容に基づいて厳密に定義されます。言い換えれば、URI インスタンスは基本的に、比較、正規化、解決、および相対化という、スキームに依存しない構文上の操作をサポートする、構造化された文字列です。

これに対し、URL クラスのインスタンスは、URL の構文上のコンポーネントを表すだけでなく、その記述対象となるリソースへのアクセスに必要な情報も一部備えています。URL は絶対でなければいけません。つまり、常にスキームを指定しなければいけません。URL 文字列は、そのスキームに従って解析されます。どの URL に対してもストリームハンドラが必ず確立されます。実際、使用可能なハンドラが存在しないスキームの URL インスタンスを作成することは不可能です。等価性とハッシュ処理は、スキームと、ホストのインターネットアドレス (存在する場合) の両方に依存します。比較は定義されません。言い換えれば、URL は、解決という構文上の操作と、ホストの検索や指定されたリソースへの接続のオープンなどのネットワーク入出力操作をサポートする、構造化された文字列です。

導入されたバージョン:

1.4

関連項目:

RFC 2279: UTF-8, a transformation format of ISO 10646,
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(URI that) この URI を別のオブジェクトと比較します。そのオブジェクトは 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

コンストラクタの詳細

URI

public URI(String str)
    throws URISyntaxException

指定された文字列を解析して URI を構築します。

このコンストラクタは、指定された文字列を解析する際に、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 がエスケープされたオクテットの使用を許可している場所であればどこでも使用できる。つまり、ユーザー情報、パス、クエリー、フラグメントの各コンポーネント内で使用できる。さらに、機関がレジストリベースであれば、機関コンポーネント内でも使用できる。これにより、US-ASCII 文字セットに含まれる文字以外の Unicode 文字を、URI に含めることができるようになる。

パラメータ:

str - URI に解析される文字列

例外:

NullPointerException - str が null の場合

URISyntaxException − 上記の変更によって拡張された RFC 2396 に、指定された文字列が違反する場合

URI

public URI(String scheme,
   String userInfo,
   String host,
   int port,
   String path,
   String query,
   String fragment)
    throws URISyntaxException

指定されたコンポーネントから階層 URI を構築します。

スキームが指定され、パスも指定された場合、そのパスは空であるか、スラッシュ文字 (「/」) で始まっていなければいけません。そうでない場合、新しい URI のコンポーネントは、対応するパラメータに null を渡すか、port パラメータの場合は -1 を渡して、未定義のままになることがあります。

このコンストラクタはまず、次のように指定されたコンポーネントから URI 文字列を構築しますが、その際、RFC 2396 のセクション 5.2 のステップ 7 に記載されている規則に従います。

1. 最初、結果文字列は空になっている。

2. スキームが指定されている場合、そのスキームが結果の末尾に追加され、そのあとにコロン文字 (「:」) が追加される。

3. ユーザー情報、ホスト、またはポートが指定されている場合、文字列「//」が末尾に追加される。

4. ユーザー情報が指定されている場合、そのユーザー情報が末尾に追加され、その後に単価記号 (「@」) が追加される。未予約、句読、エスケープ、その他のどのカテゴリにも含まれない文字はすべて、引用符で囲まれる。

5. ホストが指定されている場合、そのホストが末尾に追加される。ホストがリテラル IPv6 アドレスであるが、角括弧 (「[」と「]」) で囲まれていない場合は、角括弧が追加される。

6. ポート番号が指定されている場合、コロン文字 (「:」) が末尾に追加され、その後にその 10 進数のポート番号が追加される。

7. パスが指定されている場合、そのパスが末尾に追加される。未予約、句読、エスケープ、その他のどのカテゴリにも含まれず、スラッシュ文字 (「/」)、単価記号 (「@」) のどちらとも等しくない文字はすべて、引用符で囲まれる。

8. クエリーが指定されている場合、疑問符文字 (「?」) が末尾に追加され、そのあとにそのクエリーが追加される。適正な URI 文字でない文字はすべて、引用符で囲まれる。

9. 最後に、フラグメントが指定されている場合、ハッシュ文字 (「#」) が末尾に追加され、そのあとにそのフラグメントが追加される。適正な URI 文字でない文字はすべて、引用符で囲まれる。

結果として得られる URI 文字列が解析されますが、この解析は、URI(String) コンストラクタを呼び出したあと、その結果に対して parseServerAuthority() メソッドを呼び出したかのように行われます。これにより、URISyntaxException がスローされる可能性があります。

パラメータ:

scheme - スキーム名

userInfo − ユーザー名と認証情報

host - ホスト名

port − ポート番号

path - パス

query - クエリー

fragment - フラグメント

例外:

URISyntaxException - スキームとパスの両方が指定されているがパスが相対の場合、指定されたコンポーネントから構築された URI 文字列が RFC 2396 に違反する場合、または文字列の機関コンポーネントが存在するがサーバーベースの機関として解析できない場合

URI

public URI(String scheme,
   String authority,
   String path,
   String query,
   String fragment)
    throws URISyntaxException

指定されたコンポーネントから階層 URI を構築します。

スキームが指定され、パスも指定された場合、そのパスは空であるか、スラッシュ文字 (「/」) で始まっていなければいけません。そうでない場合、新しい URI のコンポーネントは、対応するパラメータに null を渡して、未定義のままになることがあります。

このコンストラクタはまず、次のように指定されたコンポーネントから URI 文字列を構築しますが、その際、RFC 2396 のセクション 5.2 のステップ 7 に記載されている規則に従います。

1. 最初、結果文字列は空になっている。

2. スキームが指定されている場合、そのスキームが結果の末尾に追加され、そのあとにコロン文字 (「:」) が追加される。

3. 機関が指定されている場合、文字列「//」が末尾に追加され、その後にその機関が追加される。機関にリテラル IPv6 アドレスが含まれる場合、そのアドレスを角括弧 (「[」と「]」) で囲む必要がある。未予約、句読、エスケープ、その他のどのカテゴリにも含まれず、単価記号 (「@」) と等しくない文字はすべて、引用符で囲まれる。

4. パスが指定されている場合、そのパスが末尾に追加される。未予約、句読、エスケープ、その他のどのカテゴリにも含まれず、スラッシュ文字 (「/」)、単価記号 (「@」) のどちらとも等しくない文字はすべて、引用符で囲まれる。

5. クエリーが指定されている場合、疑問符文字 (「?」) が末尾に追加され、そのあとにそのクエリーが追加される。適正な URI 文字でない文字はすべて、引用符で囲まれる。

6. 最後に、フラグメントが指定されている場合、ハッシュ文字 (「#」) が末尾に追加され、そのあとにそのフラグメントが追加される。適正な URI 文字でない文字はすべて、引用符で囲まれる。

結果として得られる URI 文字列が解析されますが、この解析は、URI(String) コンストラクタを呼び出したあと、その結果に対して parseServerAuthority() メソッドを呼び出したかのように行われます。これにより、URISyntaxException がスローされる可能性があります。

パラメータ:

scheme - スキーム名

authority − 機関

path - パス

query - クエリー

fragment - フラグメント

例外:

URISyntaxException - スキームとパスの両方が指定されているがパスが相対の場合、指定されたコンポーネントから構築された URI 文字列が RFC 2396 に違反する場合、または文字列の機関コンポーネントが存在するがサーバーベースの機関として解析できない場合

URI

public URI(String scheme,
   String host,
   String path,
   String fragment)
    throws URISyntaxException

指定されたコンポーネントから階層 URI を構築します。

コンポーネントは、null を渡して未定義のままになることがあります。

この簡易コンストラクタは、次のように 7 つの引数のコンストラクタを呼び出すかのように動作します。

new URI(scheme, null, host, -1, path, null, fragment);

パラメータ:

scheme - スキーム名

host - ホスト名

path - パス

fragment - フラグメント

例外:

URISyntaxException - 指定されたコンポーネントから構築された URI 文字列が RFC 2396 に違反する場合

URI

public URI(String scheme,
   String ssp,
   String fragment)
    throws URISyntaxException

指定されたコンポーネントから URI を構築します。

コンポーネントは、null を渡して未定義のままになることがあります。

このコンストラクタはまず、次のように指定されたコンポーネントを使って文字列形式の URI を構築します。

1. 最初、結果文字列は空になっている。

2. スキームが指定されている場合、そのスキームが結果の末尾に追加され、そのあとにコロン文字 (「:」) が追加される。

3. スキーム固有部分が指定されている場合、そのスキーム固有部分が末尾に追加される。適正な URI 文字でない文字はすべて、引用符で囲まれる。

4. 最後に、フラグメントが指定されている場合、ハッシュ文字 (「#」) が文字列の末尾に追加され、その後にそのフラグメントが追加される。適正な URI 文字でない文字はすべて、引用符で囲まれる。

新しい URI インスタンスを作成するために結果として得られる URI 文字列が解析されますが、この解析は、URI(String) コンストラクタを呼び出したかのように行われます。これにより、URISyntaxException がスローされる可能性があります。

パラメータ:

scheme - スキーム名

ssp − スキーム固有部分

fragment - フラグメント

例外:

URISyntaxException - 指定されたコンポーネントから構築された URI 文字列が RFC 2396 に違反する場合

メソッドの詳細

create

public static URI create(String str)

指定された文字列を解析して URI を作成します。

この簡易ファクトリメソッドは、URI(String) コンストラクタを呼び出したかのように動作します。このコンストラクタからスローされたURISyntaxException はすべて、キャッチされて新しい IllegalArgumentException オブジェクト内にラップされたあと、スローされます。

このメソッドは、プログラム内で宣言された URI 定数のように、与えられた文字列が適正な URI であることがあらかじめわかっているために、文字列がそのように解析されない場合はプログラミングエラーと見なされるような状況で使用するために提供されています。ユーザー入力や、エラーが含まれる可能性の高いその他の何らかのソースに基づいて URI が構築されるような状況では、URISyntaxException を直接スローするコンストラクタを使用するようにしてください。

パラメータ:

str - URI に解析される文字列

戻り値:

新しい URI

例外:

NullPointerException - str が null の場合

IllegalArgumentException - 指定された文字列が RFC 2396 に違反する場合

parseServerAuthority

public URI parseServerAuthority()
                         throws URISyntaxException

この URI の機関コンポーネント (定義されている場合) からユーザー情報、ホスト、およびポートの各コンポーネントへの解析を試みます。

この URI の機関コンポーネントがすでにサーバーベースとして認識されている場合には、それはすでに解析されてユーザー情報、ホスト、ポートの各コンポーネントに分離されています。この場合、またはこの URI が機関コンポーネントを持たない場合には、このメソッドはこの URI をそのまま返します。

そうでない場合、このメソッドは機関コンポーネントからユーザー情報、ホスト、およびポートの各コンポーネントへの解析をもう一度試み、機関コンポーネントがそのように解析できなかった理由を説明する例外をスローします。

このメソッドが提供されているのは、RFC 2396 に指定されているジェネリック URI 構文が、不正なサーバーベース機関と適正なレジストリベース機関とを常に区別できるとはかぎらないからです。このため、それは、前者のケースの一部を後者のケースとして扱わなければいけません。たとえば、URI 文字列「//foo:bar」内の機関コンポーネントは、適正なサーバーベース機関ではありませんが、レジストリベース機関としては適正です。

URN、URL のどちらかであることがわかっている URI を操作する場合のような、多くの一般的な状況では、使用される階層 URI は常にサーバーベースになります。したがって、それらはそのように解析されるか、エラーとして処理されるかのどちらかでなければいけません。これらの場合、

URI u = new URI(str).parseServerAuthority();

上のような文を使えば、u が参照する URI に機関コンポーネントが含まれる場合に、その機関が常に適切なユーザー情報、ホスト、ポートの各コンポーネントを含むサーバーベース機関であることを保証できます。また、このメソッドを呼び出せば、機関をそのように解析できなかった場合にも、スローされた例外に基づいて適切な診断メッセージを確実に発行できます。

戻り値:

機関フィールドがサーバーベース機関として解析された URI

例外:

URISyntaxException − この URI の機関コンポーネントが指定されているが、RFC 2396 に従ってサーバーベース機関として解析できない場合

normalize

public URI normalize()

この URI のパスを正規化します。

この URI が不透明である場合、またはそのパスがすでに正規化された形式になっている場合は、この URI が返されます。そうでない場合は、この URI と同じ新しい URI が構築されます。ただしそのパスが、RFC 2396 のセクション 5.2、ステップ 6、サブステップ c から f に準拠した方法でこの URI のパスを正規化して求められる場合を除きます。次のようになります。

1. すべての「.」セグメントが削除される。

2. 「..」セグメントの直前に「..」以外のセグメントが存在する場合、その両方のセグメントが削除される。この手順が該当しなくなるまで繰り返される。

3. パスが相対であり、その最初のセグメントにコロン文字 (「:」) が含まれている場合、その前に「.」セグメントが追加される。これにより、「a:b/c/d」のようなパスを含む相対 URI が、スキーム「a」とスキーム固有部分「b/c/d」を持つ不透明 URI として、あとで再度解析されてしまうのを防ぐことができる。(RFC 2396 からの変更)

正規化されたパスは、削除を可能にする「..」でない先行のセグメントが不十分だった場合、1 つ以上の「..」セグメントで始まります。正規化されたパスが「.」セグメントで始まるのは、上記の手順 3 でそのようなセグメントが挿入された場合です。それ以外の場合は、正規化されたパスに「.」セグメントや「..」セグメントが含まれることはありません。

戻り値:

この URI と等価な URI。ただし、そのパスは正規化された形式になっている

resolve

public URI resolve(URI uri)

指定された URI をこの URI に対して解決します。

指定された URI がすでに絶対である場合、またはこの URI が不透明である場合は、指定された URI が返されます。

指定された URI のフラグメントコンポーネントが定義済みであり、パスコンポーネントが空であり、スキーム、機関、クエリーの各コンポーネントが未定義である場合、指定されたフラグメントを持つが、それ以外のすべてのコンポーネントはこの URI の値に等しいような URI が返されます。これにより、「#foo」のような単独のフラグメント参照を表す URI をベース URI に基づいて解析できるようになるので便利です。

そうでない場合、このメソッドは、RFC 2396 のセクション 5.2 に適合する方法で新しい階層 URI を構築します。次のようになります。

1. この URI のスキームと指定された URI のクエリーおよびフラグメントコンポーネントを使用して、新しい URI が構築される。

2. 指定された URI に機関コンポーネントがある場合、新しい URI の機関とパスは指定された URI から取られる。

3. そうでない場合、新しい URI の機関コンポーネントがこの URI からコピーされ、そのパスは次のようにして求められる。

   1. 指定された URI のパスが絶対の場合、新しい URI のパスは指定された URI から取られる。

   2. それ以外の場合、指定された URI のパスは相対なので、この URI のパスに基づいて指定された URI のパスを解決することで、新しい URI のパスが計算される。これを行うには、この URI のパス (存在する場合) の最後のセグメント以外のすべてのセグメントを指定された URI のパスに連結したあと、その結果を normalize メソッドを呼び出したかのように正規化する。

このメソッドの結果は、この URI が絶対の場合、または指定された URI が絶対の場合にだけ、絶対になります。

パラメータ:

uri − この URI に対して解決される URI

戻り値:

結果として得られる URI

例外:

NullPointerException - uri が null の場合

resolve

public URI resolve(String str)

指定された文字列を解析し、その後その文字列をこの URI に対して解決して、新しい URI を構築します。

この簡易メソッドは、このメソッドの呼び出しが式 resolve(URI.create(str)) の評価と同じであるかのように動作します。

パラメータ:

str - URI に解析される文字列

戻り値:

結果として得られる URI

例外:

NullPointerException - str が null の場合

IllegalArgumentException - 指定された文字列が RFC 2396 に違反する場合

relativize

public URI relativize(URI uri)

指定された URI をこの URI に対して相対化します。

指定された URI のこの URI に対する相対化は、次のようにして求められます。

1. この URI または指定された URI が不透明である場合、2 つの URI のスキームと機関コンポーネントが同じでない場合、またはこの URI のパスが指定された URI のパスの接頭辞でない場合は、指定された URI が返される。

2. そうでない場合、指定された URI から取られたクエリーおよびフラグメントコンポーネントと、指定された URI のパスの先頭からこの URI のパスを削除して求めたパスコンポーネントを使用して、新しい相対階層 URI が構築される。

パラメータ:

uri − この URI に対して相対化される URI

戻り値:

結果として得られる URI

例外:

NullPointerException - uri が null の場合

toURL

public URL toURL()
          throws MalformedURLException

この URI から URL を構築します。

この簡易メソッドは、最初にこの URI が絶対であることを確認してから、このメソッドの呼び出しが式 new URL(this.toString()) の評価と同じであるかのように動作します。

戻り値:

この URI から構築された URL

例外:

IllegalArgumentException − この URL が絶対でない場合

MalformedURLException − URL のプロトコルハンドラが見つからなかった場合、または URL の構築中にその他の何らかのエラーが発生した場合

getScheme

public String getScheme()

この URI のスキームコンポーネントを返します。

URI のスキームコンポーネントが定義されている場合、そのコンポーネントに含まれるのは、英数字カテゴリまたは文字列「-.+」に含まれる文字だけです。スキームは常に、英字文字で始まります。

URI のスキームコンポーネントにエスケープされたオクテットを含めることはできません。したがって、このメソッドはデコードを実行しません。

戻り値:

この URI のスキームコンポーネント。スキームが未定義の場合は null

isAbsolute

public boolean isAbsolute()

この URI が絶対かどうかを通知します。

URI が絶対であるのは、その URI にスキームコンポーネントがある場合だけです。

戻り値:

この URI が絶対である場合だけ true

isOpaque

public boolean isOpaque()

この URI が不透明かどうかを通知します。

URI が不透明であるのは、その URI が絶対であり、そのスキーム固有部分がスラッシュ文字 (「/」) で始まっていない場合だけです。不透明 URI は、スキームとスキーム固有部分を持つほか、場合によってはフラグメントも持ちます。その他のコンポーネントはすべて未定義となります。

戻り値:

この URI が不透明の場合だけ true

getRawSchemeSpecificPart

public String getRawSchemeSpecificPart()

この URI のそのままのスキーム固有部分を返します。スキーム固有部分は、未定義になることはありませんが、空になることはあります。

URI のスキーム固有部分には、有効な URI 文字だけが含まれます。

戻り値:

この URI のそのままのスキーム固有部分 (決して null ではない)

getSchemeSpecificPart

public String getSchemeSpecificPart()

この URI のデコードされたスキーム固有部分を返します。

このメソッドから返される文字列は、getRawSchemeSpecificPart メソッドから返される文字列とほぼ同じです。異なるのは、エスケープされたオクテットのシーケンスがすべてデコードされている点だけです。

戻り値:

この URI のデコードされたスキーム固有部分 (決して null ではない)

getRawAuthority

public String getRawAuthority()

この URI のそのままの機関コンポーネントを返します。

URI の機関コンポーネントが定義されている場合、そのコンポーネントに含まれるのは、単価記号 (「@」) と、未予約、句読、エスケープ、その他のいずれかのカテゴリに含まれる文字だけです。機関がサーバーベースである場合、その機関はさらに、有効なユーザー情報、ホスト、ポートの各コンポーネントを持つように制約されます。

戻り値:

この URI のそのままの機関コンポーネント。機関が未定義の場合は null

getAuthority

public String getAuthority()

この URI のデコードされた機関コンポーネントを返します。

このメソッドから返される文字列は、getRawAuthority メソッドから返される文字列とほぼ同じです。異なるのは、エスケープされたオクテットのシーケンスがすべてデコードされている点だけです。

戻り値:

この URI のデコードされた機関コンポーネント。機関が未定義の場合は null

getRawUserInfo

public String getRawUserInfo()

この URI のそのままのユーザー情報コンポーネントを返します。

URI のユーザー情報コンポーネントには (定義されている場合)、未予約、句読、エスケープ、およびその他のカテゴリの文字だけが含まれます。

戻り値:

この URI のそのままのユーザー情報コンポーネント。ユーザー情報が未定義の場合は null

getUserInfo

public String getUserInfo()

この URI のデコードされたユーザー情報コンポーネントを返します。

このメソッドから返される文字列は、getRawUserInfo メソッドから返される文字列とほぼ同じです。異なるのは、エスケープされたオクテットのシーケンスがすべてデコードされている点だけです。

戻り値:

この URI のデコードされたユーザー情報コンポーネント。ユーザー情報が未定義の場合は null

getHost

public String getHost()

この URI のホストコンポーネントを返します。

URI のホストコンポーネント (定義されている場合) の形式は、次のいずれかです。

• ドメイン名。1 つ以上のラベルをピリオド文字 (「.」) で区切った形式になります。末尾にピリオド文字を 1 つ付けてもかまいません。各ラベルは英数字文字とハイフン文字 (「-」) から構成されます。ただし、ハイフンがラベル内の先頭または末尾の文字として使用されることはありません。2 つ以上のラベルで構成されるドメイン名のもっとも右側のラベルは、英字文字で始まります。

• 数字+.数字+.数字+.数字+ の形式の、ドットで 4 つに区分された IPv4 アドレス。ここで、数字は 3 文字以内で、その値は 255 を超えません。

• IPv6 アドレス。角括弧 (「[」と「]」) で囲まれ、16 進数、コロン文字 (「:」)、および場合によっては埋め込み IPv4 アドレスで構成されます。IPv6 アドレスの完全な構文は、「RFC 2373: IPv6 Addressing Architecture」で指定されています。

URI のホストコンポーネントにエスケープされたオクテットを含めることはできません。したがって、このメソッドはデコードを実行しません。

戻り値:

この URI のホストコンポーネント。ホストが未定義の場合は null

getPort

public int getPort()

この URI のポート番号を返します。

URI のポートコンポーネントは (定義されている場合)、負でない整数です。

戻り値:

この URI のポートコンポーネント。ポートが未定義の場合は -1

getRawPath

public String getRawPath()

この URI のそのままのパスコンポーネントを返します。

URI のパスコンポーネントには (定義されている場合)、スラッシュ (「/」)、単価記号 (「@」) と、未予約、句読、エスケープ、およびその他のカテゴリの文字だけが含まれます。

戻り値:

この URI のパスコンポーネント。パスが未定義の場合は null

getPath

public String getPath()

この URI のデコードされたパスコンポーネントを返します。

このメソッドから返される文字列は、getRawPath メソッドから返される文字列とほぼ同じです。異なるのは、エスケープされたオクテットのシーケンスがすべてデコードされている点だけです。

戻り値:

この URI のデコードされたパスコンポーネント。パスが未定義の場合は null

getRawQuery

public String getRawQuery()

この URI のそのままのクエリーコンポーネントを返します。

URI のクエリーコンポーネントには (定義されている場合)、有効な URI 文字だけが含まれます。

戻り値:

この URI のそのままのクエリーコンポーネント。クエリーが未定義の場合は null

getQuery

public String getQuery()

この URI のデコードされたクエリーコンポーネントを返します。

このメソッドから返される文字列は、getRawQuery メソッドから返される文字列とほぼ同じです。異なるのは、エスケープされたオクテットのシーケンスがすべてデコードされている点だけです。

戻り値:

この URI のデコードされたクエリーコンポーネント。クエリーが未定義の場合は null

getRawFragment

public String getRawFragment()

この URI のそのままのフラグメントコンポーネントを返します。

URI のフラグメントコンポーネントには (定義されている場合)、有効な URI 文字だけが含まれます。

戻り値:

この URI のそのままのフラグメントコンポーネント。フラグメントが未定義の場合は null

getFragment

public String getFragment()

この URI のデコードされたフラグメントコンポーネントを返します。

このメソッドから返される文字列は、getRawFragment メソッドから返される文字列とほぼ同じです。異なるのは、エスケープされたオクテットのシーケンスがすべてデコードされている点だけです。

戻り値:

この URI のデコードされたフラグメントコンポーネント。フラグメントが未定義の場合は null

equals

public boolean equals(Object ob)

この URI が別のオブジェクトと等しいかどうかを判定します。

指定されたオブジェクトが URI でない場合、このメソッドは直ちに false を返します。

2 つの URI が等しいと見なされるには、どちらも不透明 URI であるか、どちらも階層 URI である必要があります。スキームは、どちらも未定義であるか、大文字と小文字を区別しない場合に等しくなければいけません。フラグメントは、どちらも未定義であるか、等しくなければいけません。

等しいと見なされる 2 つの不透明 URI の場合、それらのスキーム固有部分は等しい必要があります。

2 つの階層 URI が等しいと見なされるには、パスが等しく、クエリーがどちらも未定義であるか等しくなければいけません。機関は、どちらも未定義であるか、どちらもレジストリベースであるか、どちらもサーバーベースでなければいけません。機関が定義されており、レジストリベースである場合、それらの機関は等しくなければいけません。機関が定義されており、サーバーベースである場合、大文字と小文字を区別しない場合にホストが等しく、ポート番号が等しく、ユーザー情報コンポーネントが等しくなければいけません。

2 つの URI のユーザー情報、パス、クエリー、フラグメント、機関、またはスキーム固有部分が等しいかどうか判定する場合、これらのコンポーネントはエンコードされた形式でなくそのままの形式で比較され、エスケープオクテットの 16 進数は大文字小文字に関係なく比較されます。

このメソッドは Object.equals の汎用規約を満たします。

オーバーライド:

equals、クラス: Object

パラメータ:

ob - このオブジェクトと比較するオブジェクト

戻り値:

指定されたオブジェクトがこの URI と同じ URI である場合だけ true

関連項目:

Object.hashCode(), HashMap

hashCode

public int hashCode()

この URI のハッシュコード値を返します。このハッシュコードは、URI のすべてのコンポーネントに基づき、Object.hashCode メソッドの汎用規約を満たします。

オーバーライド:

hashCode、クラス: Object

戻り値:

この URI のハッシュコード値

関連項目:

Object.equals(java.lang.Object), System.identityHashCode(java.lang.Object)

compareTo

public int compareTo(URI that)

この URI を別のオブジェクトと比較します。そのオブジェクトは URI である必要があります。

2 つの URI の対応するコンポーネントを比較する際に、一方のコンポーネントが未定義であるのに他方が定義済みであった場合、前者のほうが後者よりも小さいと見なされます。特に明記されていないかぎり、文字列コンポーネントは、String.compareTo メソッドで定義されているように、本来の大文字小文字を区別した順序に従って順序付けられます。エンコードの対象となる文字列コンポーネントの比較は、エンコードされた形式ではなくそのままの形式で比較されます。

URI の順序は次のように定義されます。

• 異なるスキームを持つ 2 つの URI は、大文字小文字に関係なくそれらのスキームの順序に従って順序付けられる。

• 階層 URI は、同じスキームを持つ不透明 URI より小さいと見なされる。

• 同じスキームを持つ 2 つの不透明 URI は、それらのスキーム固有部分の順序に従って順序付けられる。

• 同じスキームとスキーム固有部分を持つ 2 つの不透明 URI は、それらのフラグメントの順序に従って順序付けられる。

• 同じスキームを持つ 2 つの階層 URI は、それらの機関コンポーネントの順序に従って順序付けられる。

  • 両方の機関コンポーネントがサーバーベースである場合、URI はそれらのユーザー情報コンポーネントに従って順序付けられる。これらのコンポーネントが同じである場合、URI は大文字小文字に関係なくそれらのホストの順序に従って順序付けられる。ホストが同じである場合、URI はそれらのポートの順序に従って順序付けられる。

  • 一方または両方の機関コンポーネントがレジストリベースである場合、URI はそれらの機関コンポーネントの順序に従って順序付けられる。

• 最後に、同じスキームと機関コンポーネントを持つ 2 つの階層 URI は、それらのパスの順序に従って順序付けられる。パスが同じである場合、それらの階層 URI は、それらのクエリーの順序に従って順序付けられる。クエリーが同じである場合は、それらのフラグメントの順序に従って順序付けられる。

このメソッドは Comparable.compareTo の汎用規約を満たします。

定義:

compareTo、インタフェース: Comparable<URI>

パラメータ:

that − この URI と比較するオブジェクト

戻り値:

この URI が指定された URI より小さい場合は負の整数、等しい場合は 0、大きい場合は正の整数

例外:

ClassCastException − 指定されたオブジェクトが URI でない場合

toString

public String toString()

この URI のコンテンツを文字列として返します。

この URI がこのクラスのいずれかのコンストラクタを呼び出すことで作成されたものである場合、元の入力文字列と等価な文字列、または最初に指定されたコンポーネントから適宜計算された文字列と等価な文字列が返されます。それ以外の場合、この URI は正規化、解決、または相対化によって作成されたものなので、RFC 2396 のセクション 5.2、ステップ 7 の規則に従って、この URI のコンポーネントから文字列が構築されます。

オーバーライド:

toString、クラス: Object

戻り値:

この URI の文字列形式

toASCIIString

public String toASCIIString()

この URI のコンテンツを US-ASCII 文字列として返します。

この URI にその他カテゴリの文字が 1 つも含まれていない場合、このメソッドを呼び出すと、toString メソッド呼び出し時と同じ値が返されます。それ以外の場合、そのメソッドの呼び出し後に結果をエンコードしたかのように、このメソッドは動作します。

戻り値:

この URI の文字列形式。US-ASCII 文字セットの文字だけが含まれるよう、必要に応じてエンコードされる