- すべての実装されたインタフェース:
Serializable
,Comparable<URI>
後述するいくつかの小さな変更を除けば、このクラスのインスタンスは、「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@www.example.com
news:comp.lang.java
urn:isbn:096139210x
階層 URIは、スキーム固有部分がスラッシュで始まる絶対URI、または相対URI (スキームを指定しないURI)です。 階層URIの例を次に示します。
http://example.com/languages/java/
sample/a/index.html#28
../../demo/b/index.html
file:///~/calendar
階層URIは、構文に従ってさらに解析されます。
[スキームここで、:
][//
機関][パス][?
クエリー][#
フラグメント]
:
、/
、?
、および#
はその文字自体を表します。 階層URIのスキーム固有部分は、スキームとフラグメント・コンポーネントの間の文字で構成されます。
階層URIの機関コンポーネントが指定されている場合、その機関コンポーネントはサーバー・ベースまたはレジストリ・ベースです。 サーバー・ベース機関は、よく知られている構文に従って解析されます。
[ユーザー情報ここで、@
]ホスト[:
ポート]
@
と:
はその文字自体を表します。 現在使用されているURIスキームのほとんどはサーバー・ベースです。 このように解析されない機関コンポーネントは、レジストリ・ベースと見なされます。
階層URIのパス・コンポーネントは、スラッシュ(「/」
)で始まる場合は絶対と呼ばれ、そうでない場合は相対と呼ばれます。 絶対である階層URIまたは機関を指定する階層URIのパス・コンポーネントは常に絶対です。
URIインスタンスには、全部で次の9つのコンポーネントがあります。
Component | 型 |
---|---|
スキーム | 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の場合、元のパスは、ベースのパスに基づいて解決されたあと、正規化されます。 たとえば、次のようになります。
sample/a/index.html#28
(1)
ベースURIに対してhttp://example.com/languages/java/
は結果URIは、
http://example.com/languages/java/sample/a/index.html#28
相対URI
../../demo/b/index.html
(2)
をこの結果に対して解決すると、次のようになります。
http://example.com/languages/java/demo/b/index.html
絶対と相対の両方のURIの解決、および階層URIの場合は絶対と相対の両方のパスの解決がサポートされます。 URI file:///~calendar
は絶対なので、これをほかの任意のURIに対して解決すると、元のURIが生成されるだけです。 上記の相対URI (2)を相対ベースURI (1)に対して解決すると、正規化されていても相対のままのURIが生成されます。
demo/b/index.html
最後に相対化とは、解決の逆です。任意の2つの正規化済みURI uと vについて、次が成り立ちます。
uこの操作は、可能であればどこででも、ドキュメントのベースURIに対して相対的でなければならないURIを含むドキュメントを構築する場合に便利です。 たとえば、次のURI.relativize(
u.resolve(
v)).equals(
v)
および
u.resolve(
u.relativize(
v)).equals(
v)
。
http://example.com/languages/java/sample/a/index.html#28
を次のベースURIに対して相対化すると、
http://example.com/languages/java/
相対URI sample/a/index.html#28
が生成されます。
文字カテゴリ
URI参照の各種コンポーネントで許可される文字は、RFC 2396で厳密に指定されています。 次のカテゴリを使用して、この制約について説明します。これらのカテゴリのほとんどはその仕様から取られています。カテゴリ | 説明 |
---|---|
alpha | A から Z 、およびa から z までのUS-ASCII英文字 |
digit | 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文字のセットは未予約、予約済み、エスケープ、およびその他の文字で構成されます。
エスケープ・オクテット、引用符、エンコーディング、およびデコーディング
RFC 2396では、エスケープ・オクテットをユーザー情報、パス、クエリー、およびフラグメントの各コンポーネントに表示することができます。 URIにおけるエスケープ処理の目的は、次の2つです。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文字をデコードする効果がある。 エスケープされたオクテットのデコード時にデコード・エラーが発生した場合、そのエラーの発生したオクテットは、Unicode置換文字である
\uFFFD
に置き換えられる。
単一引数コンストラクタは、その引数内のすべての不正文字が引用符で囲まれることを要求するが、存在するエスケープされたオクテットとその他の文字はすべてそのまま維持する。
複数引数コンストラクタは、不正文字を含むコンポーネントからの要求に従って不正文字を引用符で囲む。 パーセント文字(
%
)は常に、これらのコンストラクタによって囲まれる。 その他の文字はすべてそのまま維持される。getRawUserInfo
、getRawPath
、getRawQuery
、getRawFragment
、getRawAuthority
、およびgetRawSchemeSpecificPart
メソッドは、対応するコンポーネントの値をそのままの形式で返し、エスケープされたオクテットを解釈しない。 これらのメソッドから返される文字列には、エスケープされたオクテットとその他の文字の両方が含まれていることがあり、不正な文字は含まれない。getUserInfo
、getPath
、getQuery
、getFragment
、getAuthority
、およびgetSchemeSpecificPart
メソッドは、対応するコンポーネント内のすべてのエスケープされたオクテットをデコードする。 これらのメソッドから返される文字列には、その他の文字と不正文字のどちらも含まれる可能性があるが、エスケープされたオクテットが含まれることはない。toString
メソッドは、すべての必要な引用符を持つURI文字列を返すが、その他の文字が含まれる場合がある。toASCIIString
メソッドは、完全に引用符で囲まれてエンコードされたURI文字列を返す。この文字列にはその他の文字は含まれない。
アイデンティティ
任意のURI uの場合に、常に次のようになります。空の機関uの前に2つのスラッシュなどの冗長構文が含まれていないURI (new URI(
u.toString()).equals(
u)
。
file:///tmp/
のとおり)の場合、またはホスト名の後にコロンが含まれていてもポート(http://www.example.com:
のとおり)がなく、引用符で囲む必要のある文字以外の文字はエンコードしない場合は、次のIDも保持されます:
new URI(u.getScheme(), u.getSchemeSpecificPart(), u.getFragment()) .equals(u)すべての場合において
new URI(u.getScheme(), 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)があるためです。 前に示したmailto
、news
およびisbn
の各URIは、URNの例です。
URIとURLとの概念上の区別は、このクラスとURL
クラスの間の相違に反映されています。
このクラスのインスタンスは、RFC 2396で定義されている構文としてのURI参照を表します。 URIは絶対、相対のいずれかになります。 URI文字列は、スキームが指定されていてもそれについては考慮せず、ジェネリックな構文に従って解析されます。 ホストが存在していてもその検索は実行されず、スキームに依存するストリーム・ハンドラの構築も行われません。 等価性、ハッシュ処理、および比較は、インスタンスの文字内容に基づいて厳密に定義されます。 言い換えれば、URIインスタンスは基本的に、比較、正規化、解決、および相対化という、スキームに依存しない構文上の操作をサポートする、構造化された文字列です。
これに対し、URL
クラスのインスタンスは、URLの構文上のコンポーネントを表すだけでなく、その記述対象となるリソースへのアクセスに必要な情報も一部備えています。 URLは絶対でなければいけません。つまり、常にスキームを指定しなければいけません。 URL文字列は、そのスキームに従って解析されます。 どのURLに対してもストリーム・ハンドラが必ず確立されます。実際、使用可能なハンドラが存在しないスキームのURLインスタンスを作成することは不可能です。 等価性とハッシュ処理は、スキームと、ホストのインターネット・アドレス(存在する場合)の両方に依存します。比較は定義されません。 言い換えれば、URLは、解決という構文上の操作と、ホストの検索や指定されたリソースへの接続のオープンなどのネットワーク入出力操作をサポートする、構造化された文字列です。
- APIのノート:
- ファイル・パスおよびファイルUriを操作するアプリケーションは、2つの間で変換する適切なメソッドを使用することを検討する必要があります。
Path.of(URI)
ファクトリ・メソッドとFile(URI)
コンストラクタを使用して、ファイルURIからPath
またはFile
オブジェクトを作成できます。Path.toUri()
とFile.toURI()
を使用すると、ファイル・パスからURI
を作成できます。 アプリケーションは、File
またはPath
インスタンスの直接文字列表現から、construct、parse、またはresolveをURI
に試みないでください。URLまたはURIの一部のコンポーネント(userinfoなど)は、先行するURLまたはURIの構築に不正に使用される可能性があります。 Urlまたはuriを処理するアプリケーションは、「RFC3986,セクション7,セキュリティに関する考慮事項」で推奨される推奨事項を考慮してください。
- 導入されたバージョン:
- 1.4
- 関連項目:
-
コンストラクタのサマリー
コンストラクタ -
メソッドのサマリー
修飾子と型メソッド説明int
このURIを別のオブジェクトと比較します。そのオブジェクトはURIである必要があります。static URI
指定された文字列を解析してURIを作成します。boolean
このURIが別のオブジェクトと等しいかどうかを判定します。このURIのデコードされた機関コンポーネントを返します。このURIのデコードされたフラグメント・コンポーネントを返します。getHost()
このURIのホスト・コンポーネントを返します。getPath()
このURIのデコードされたパス・コンポーネントを返します。int
getPort()
このURIのポート番号を返します。getQuery()
このURIのデコードされたクエリー・コンポーネントを返します。このURIのそのままの機関コンポーネントを返します。このURIのそのままのフラグメント・コンポーネントを返します。このURIのそのままのパス・コンポーネントを返します。このURIのそのままのクエリー・コンポーネントを返します。このURIのそのままのスキーム固有部分を返します。このURIのそのままのユーザー情報コンポーネントを返します。このURIのスキーム・コンポーネントを返します。このURIのデコードされたスキーム固有部分を返します。このURIのデコードされたユーザー情報コンポーネントを返します。int
hashCode()
このURIのハッシュ・コード値を返します。boolean
このURIが絶対かどうかを通知します。boolean
isOpaque()
このURIが不透明かどうかを通知します。このURIのパスを正規化します。このURIの機関コンポーネント(定義されている場合)からユーザー情報、ホスト、およびポートの各コンポーネントへの解析を試みます。relativize
(URI uri) 指定されたURIをこのURIに対して相対化します。指定された文字列を解析し、その後その文字列をこのURIに対して解決して、新しいURIを構築します。指定されたURIをこのURIに対して解決します。このURIのコンテンツをUS-ASCII文字列として返します。toString()
このURIのコンテンツを文字列として返します。toURL()
このURIからURLを構築します。
-
コンストラクタの詳細
-
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に記載されているルールに従います。
最初、結果文字列は空になっている。
スキームが指定されている場合、そのスキームが結果の末尾に追加され、そのあとにコロン文字(
「:」
)が追加される。ユーザー情報、ホスト、またはポートが指定されている場合、文字列
「//」
が末尾に追加される。ユーザー情報が指定されている場合、そのユーザー情報が末尾に追加され、その後に単価記号(
「@」
)が追加される。 未予約、句読、エスケープ、その他のどのカテゴリにも含まれない文字はすべて、引用符で囲まれる。ホストが指定されている場合、そのホストが末尾に追加される。 ホストがリテラルIPv6アドレスであるが、角カッコ(
「[」
と「]」
)で囲まれていない場合は、角カッコが追加される。ポート番号が指定されている場合、コロン文字(
「:」
)が末尾に追加され、その後にその10進数のポート番号が追加される。パスが指定されている場合、そのパスが末尾に追加される。 未予約、句読、エスケープ、その他のどのカテゴリにも含まれず、スラッシュ文字(
「/」
)、単価記号(「@」
)のどちらとも等しくない文字はすべて、引用符で囲まれる。クエリーが指定されている場合、疑問符文字(
「?」
)が末尾に追加され、そのあとにそのクエリーが追加される。 適正なURI文字でない文字はすべて、引用符で囲まれる。最後に、フラグメントが指定されている場合、ハッシュ文字(
「#」
)が末尾に追加され、そのあとにそのフラグメントが追加される。 適正な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に記載されているルールに従います。
最初、結果文字列は空になっている。
スキームが指定されている場合、そのスキームが結果の末尾に追加され、そのあとにコロン文字(
「:」
)が追加される。機関が指定されている場合、文字列
「//」
が末尾に追加され、その後にその機関が追加される。 機関にリテラルIPv6アドレスが含まれる場合、そのアドレスを角カッコ(「[」
と「]」
)で囲む必要がある。 未予約、句読、エスケープ、その他のどのカテゴリにも含まれず、単価記号(「@」
)と等しくない文字はすべて、引用符で囲まれる。パスが指定されている場合、そのパスが末尾に追加される。 未予約、句読、エスケープ、その他のどのカテゴリにも含まれず、スラッシュ文字(
「/」
)、単価記号(「@」
)のどちらとも等しくない文字はすべて、引用符で囲まれる。クエリーが指定されている場合、疑問符文字(
「?」
)が末尾に追加され、そのあとにそのクエリーが追加される。 適正なURI文字でない文字はすべて、引用符で囲まれる。最後に、フラグメントが指定されている場合、ハッシュ文字(
「#」
)が末尾に追加され、そのあとにそのフラグメントが追加される。 適正な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を構築します。
最初、結果文字列は空になっている。
スキームが指定されている場合、そのスキームが結果の末尾に追加され、そのあとにコロン文字(
「:」
)が追加される。スキーム固有部分が指定されている場合、そのスキーム固有部分が末尾に追加される。 適正なURI文字でない文字はすべて、引用符で囲まれる。
最後に、フラグメントが指定されている場合、ハッシュ文字(
「#」
)が文字列の末尾に追加され、その後にそのフラグメントが追加される。 適正なURI文字でない文字はすべて、引用符で囲まれる。
新しいURIインスタンスを作成するために結果として得られるURI文字列が解析されますが、この解析は、
URI(String)
コンストラクタを呼び出したかのように行われます。これにより、URISyntaxException
がスローされる可能性があります。- パラメータ:
scheme
- スキーム名ssp
−スキーム固有部分fragment
- フラグメント- 例外:
URISyntaxException
- 指定されたコンポーネントから構築されたURI文字列がRFC 2396に違反する場合
-
-
メソッドの詳細
-
create
指定された文字列を解析してURIを作成します。この簡易ファクトリ・メソッドは、
URI(String)
コンストラクタを呼び出したかのように動作します。このコンストラクタからスローされたURISyntaxException
はすべて、キャッチされて新しいIllegalArgumentException
オブジェクト内にラップされたあと、スローされます。このメソッドは、指定された文字列がプログラム内で宣言されたURI定数などの有効なURIであることがわかっている場合に、そのような文字列を解析しないときに使用するために提供されます。
URISyntaxException
を直接スローするコンストラクタは、ユーザー入力またはエラーが発生する可能性があるその他のソースからURIが構築されている場合に使用する必要があります。- パラメータ:
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のパスを正規化して求められる場合を除きます。次のようになります。
すべての
「.」
セグメントが削除される。「..」
セグメントの直前に「..」
以外のセグメントが存在する場合、その両方のセグメントが削除される。 このステップが該当しなくなるまで繰り返される。パスが相対であり、その最初のセグメントにコロン文字(
「:」
)が含まれている場合、その前に「.」
セグメントが追加される。 これにより、「a:b/c/d」
のようなパスを含む相対URIが、スキーム「a」
とスキーム固有部分「b/c/d」
を持つ不透明URIとして、あとで再度解析されてしまうのを防ぐことができる。 (RFC 2396からの変更)
正規化されたパスは、削除を可能にする
「..」
でない先行のセグメントが不十分だった場合、1つ以上の「..」
セグメントで始まります。 正規化されたパスが「.」
セグメントで始まるのは、上記のステップ3でそのようなセグメントが挿入された場合です。 それ以外の場合は、正規化されたパスに「.」
セグメントや「..」
セグメントが含まれることはありません。- 戻り値:
- このURIと等価な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- 戻り値:
- 結果として得られるURI
- 例外:
NullPointerException
-uri
がnull
の場合
-
resolve
指定された文字列を解析し、その後その文字列をこのURIに対して解決して、新しいURIを構築します。この簡易メソッドは、このメソッドの呼出しが式
resolve
(URI.
create
(str))
の評価と同じであるかのように動作します。- パラメータ:
str
- URIに解析される文字列- 戻り値:
- 結果として得られるURI
- 例外:
NullPointerException
-str
がnull
の場合IllegalArgumentException
- 指定された文字列がRFC 2396に違反する場合
-
relativize
指定されたURIをこのURIに対して相対化します。指定されたURIのこのURIに対する相対化は、次のようにして求められます。
このURIまたは指定されたURIが不透明である場合、2つのURIのスキームと機関コンポーネントが同じでない場合、またはこのURIのパスが指定されたURIのパスの接頭辞でない場合は、指定されたURIが返される。
そうでない場合、指定された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のホスト・コンポーネント。ホストが未定義の場合は
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
メソッドの汎用規約を満たします。 -
hashCode
public int hashCode()このURIのハッシュ・コード値を返します。 このハッシュ・コードは、URIのすべてのコンポーネントに基づき、Object.hashCode
メソッドの汎用規約を満たします。 -
compareTo
public int compareTo(URI that) このURIを別のオブジェクトと比較します。そのオブジェクトはURIである必要があります。2つのURIの対応するコンポーネントを比較する際に、一方のコンポーネントが未定義であるのに他方が定義済みであった場合、前者のほうが後者よりも小さいと見なされます。 特に明記されていないかぎり、文字列コンポーネントは、
String.compareTo
メソッドで定義されているように、本来の大文字小文字を区別した順序に従って順序付けられます。 エンコーディングの対象となる文字列コンポーネントは、エンコードされた形式ではなくraw形式を比較することで比較され、エスケープされたオクテットの16進数は大文字と小文字に関係なく比較されます。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のコンポーネントから文字列が構築されます。
-
toASCIIString
public String toASCIIString()このURIのコンテンツをUS-ASCII文字列として返します。このURIにその他カテゴリの文字が1つも含まれていない場合、このメソッドを呼び出すと、
toString
メソッド呼出し時と同じ値が返されます。 それ以外の場合、そのメソッドの呼出し後に結果をエンコードしたかのように、このメソッドは動作します。- 戻り値:
- このURIの文字列形式。US-ASCII文字セットの文字だけが含まれるよう、必要に応じてエンコードされる
-