URI (Java 2 Platform SE 6)

除了以下提到的一些細微不同之處外，此類別的實例代表一個 URI 參考，這在以下文檔中定義：RFC 2396: Uniform Resource Identifiers (URI):Generic Syntax；在此檔案中對其內容又進行了修正：RFC 2732:Format for Literal IPv6 Addresses in URLs。文字值 IPv6 位址格式還支持 scope_ids。scope_ids 的語法和用法在此處描述。此類別提供了用於從其組成部分或通過解析其字元串形式創建 URI 實例的建構子、用於存取實例的各個不同組成部分的方法，以及用於對 URI 實例進行規範化、解析和相對化的方法。此類別的實例不可變。

URI 語法和組成部分

在最高層級別上，字元串形式的 URI 參考（以下簡寫為 "URI"）語法如下

[scheme:]scheme-specific-part[#fragment]

其中，方括號 [...] 用於描述可選組成部分，字元 : 和 # 代表它們自身。

絕對 URI 指定了方案 (scheme)；非絕對的 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 還要按照下面的語法進行進一步的解析

[scheme:][//authority][path][?query][#fragment]

其中，:、/、? 和 # 代表它們自身。分層 URI 的特定於方案的部分包含方案和片段部分之間的字元。

分層 URI 的授權組成部分（如果指定）為基於伺服器的 或基於註冊表的。基於伺服器的授權按照如下眾所周知的語法進行解析：

[user-info@]host[:port]

其中，字元 @ 和 : 代表它們自身。幾乎當前使用的所有 URI 方案都是基於伺服器的。不能採用這種方式解析的授權組成部分被視為基於註冊表的。

如果分層 URI 的路徑組成部分以斜線字元 ('/') 開始，則稱此 URI 本身為絕對的；否則它為相對的。分層 URI 或者為絕對的，或者指定了授權的路徑，它始終為絕對的。

如上所述，URI 實例具有以下九個組成部分：

組成部分 型別

方案 String

特定於方案的部分 String

授權 String

使用者資訊 String

主機 String

埠號 int

路徑 String

查詢 String

片段 String

組成部分	型別
方案	`String`
特定於方案的部分	`String`
授權	`String`
使用者資訊	`String`
主機	`String`
埠號	`int`
路徑	`String`
查詢	`String`
片段	`String`

在給定實例中，任何特殊組成部分都或者為未定義的，或者為已定義的，並且有不同的值。未定義的字元串組成部分由 null 表示，未定義的整陣列成部分由 -1 表示。已定義的字元串組成部分的值可以為空字元串；這與未定義的組成部分不等效。

實例中特定的組成部分是已定義的還是未定義的取決於所代表的 URI 型別。絕對 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 對 URI file:///~calendar 進行解析只能產生原始的 URI，因為它是絕對路徑。根據相對基礎 URI (1) 解析相對 URI (2) 將產生規範的但依然是相對的 URI

demo/jfc/SwingSet2/src/SwingSet2.java

最後，相對化 是解析的逆過程：對於任何兩個規範的 URI u 和 v，

u.relativize(u.resolve(v)).equals(v) 和
u.resolve(u.relativize(v)).equals(v)。

此運算在下面的場合非常有用：建構一個套件含 URI 的文檔，該 URI 必須盡可能是根據文檔的基本 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。

字元分類別

RFC 2396 精確指出 URI 參考中的各個不同組成部分允許使用的字元。以下分類別大部分取自該規範，這些約束的用法描述如下：

alpha US-ASCII 字母字元，'A' 到 'Z' 以及 'a' 到 'z'

digit US-ASCII 十進制數字元，'0' 到 '9'

alphanum 所有 alpha 和 digit 字元

unreserved 所有 alphanum 字元及字元串 "_-!.~'()*" 中包含的字元

punct 字元串 ",;:$&+=" 中包含的字元

reserved 所有 punct 字元及字元串 "?/[]@" 中包含的字元

escaped 轉義八位組，即三部分組合：百分號 ('%') 後跟兩個十六進制數（'0'-'9'、'A'-'F' 和 'a'-'f'）

other 未包含在 US-ASCII 字元集中的 Unicode 字元不是控制字元（根據 Character.isISOControl 方法），並且不是空格字元（根據 Character.isSpaceChar 方法）（與 RFC 2396 有些出入，RFC 2396 限制為 US-ASCII）

alpha	US-ASCII 字母字元，`'A'` 到 `'Z'` 以及 `'a'` 到 `'z'`
digit	US-ASCII 十進制數字元，`'0'` 到 `'9'`
alphanum	所有 alpha 和 digit 字元
unreserved	所有 alphanum 字元及字元串 `"_-!.~'()*"` 中包含的字元
punct	字元串 `",;:$&+="` 中包含的字元
reserved	所有 punct 字元及字元串 `"?/[]@"` 中包含的字元
escaped	轉義八位組，即三部分組合：百分號 (`'%'`) 後跟兩個十六進制數（`'0'`-`'9'`、`'A'`-`'F'` 和 `'a'`-`'f'`）
other	未包含在 US-ASCII 字元集中的 Unicode 字元不是控制字元（根據 `Character.isISOControl` 方法），並且不是空格字元（根據 `Character.isSpaceChar` 方法）（與 RFC 2396 有些出入，RFC 2396 限制為 US-ASCII）

全部合法 URI 字元集包含 unreserved、reserved、escaped 和 other 字元。

轉義八位組、參考、編碼和解碼

RFC 2396 允許使用者資訊、路徑、查詢和片段組成部分中包含轉義八位組。轉義在 URI 中實作兩個目的：

當要求 URI 不能包含任何 other 字元以嚴格遵守 RFC 2396 時，需要對非 US-ASCII 字元進行編碼。
要參考組成部分中的非法字元。使用者資訊、路徑、查詢和片段組成部分在判斷哪些字元合法哪些字元非法上稍有不同。

在此類別中由三個相關的運算實作了這兩個目的：

字元的編碼方式是，用代表該字元在 UTF-8 字元集中的字元的轉義八位組序列取代該字元。例如，歐元符號 ('\u20AC') 編碼後為 "%E2%82%AC"。（與 RFC 2396 有些出入，RFC 2396 未指定任何特殊字元集）。
非法字元通過簡單地對它進行編碼來參考。例如，空格字元，用 "%20" 取代它來進行參考。UTF-8 套件含 US-ASCII，因此對於 US-ASCII 字元，此轉換具有的效果與 RFC 2396 的要求相同。
對轉義八位組序列進行解碼的方法是，用它所代表的 UTF-8 字元集中的字元的序列將它取代。UTF-8 套件含 US-ASCII，因此解碼具有對參考的任何 US-ASCII 字元取消參考的效果，以及對任何編碼的非 US-ASCII 字元進行解碼的效果。如果在對轉義八位組進行解碼時出現解碼錯誤，則出錯的八位組用 Unicode 替換字元 '\uFFFD' 取代。

這些運算在此類別的建構子和方法中公開，如下所示：

單參數建構子要求對參數中的任何非法字元都必須參考，並保留出現的任何轉義八位組和 other 字元。
多參數建構子根據其中出現的組成部分的需要對非法字元進行參考。百分號字元 ('%') 始終通過這些建構子參考。任何 other 字元都將被保留。
getRawUserInfo、getRawPath、getRawQuery、getRawFragment、getRawAuthority 和 getRawSchemeSpecificPart 方法以原始形式返回它們的相應組成部分的值，不解釋任何轉義八位組。由這些方法返回的字元串有可能包含轉義八位組和 other 字元，但不包含任何非法字元。
getUserInfo、getPath、getQuery、getFragment、getAuthority 和 getSchemeSpecificPart 方法解碼相應的組成部分中的任何轉義八位組。由這些方法返回的字元串有可能包含 other 字元和非法字元，但不包含任何轉義八位組。
toString 返回帶所有必要參考的 URI 字元串，但它可能包含 other 字元。
toASCIIString 方法返回不包含任何 other 字元的、完全參考的和經過編碼的 URI 字元串。

標識

對於任何 URI u，下面的標識有效

new URI(u.toString()).equals(u) .

對於不包含冗余語法的任何 URI u，比如在一個空授權前面有兩根斜線（如 file:///tmp/）和主機名後面跟一個冒號但沒有埠號（如 http://java.sun.com:），以及除必須參考的字元之外不對字元編碼的情況，下面的標識也有效：

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 是統一資源標識符，而 URL 是統一資源定位符。因此，籠統地說，每個 URL 都是 URI，但不一定每個 URI 都是 URL。這是因為 URI 還包括一個子類別，即統一資源名稱 (URN)，它命名資源但不指定如何定位資源。上面的 mailto、news 和 isbn URI 都是 URN 的範例。

URI 和 URL 概念上的不同反映在此類別和 URL 類別的不同中。

此類別的實例代表由 RFC 2396 定義的語法意義上的一個 URI 參考。URI 可以是絕對的，也可以是相對的。對 URI 字元串按照一般語法進行解析，不考慮它所指定的方案（如果有）不對主機（如果有）執行尋找，也不建構依賴於方案的串流處理程序。相等性、雜湊計算以及比較都嚴格地根據實例的字元內容進行定義。換句話說，一個 URI 實例和一個支持語法意義上的、依賴於方案的比較、規範化、解析和相對化計算的結構化字元串差不多。

作為對照，URL 類別的實例代表了 URL 的語法組成部分以及存取它描述的資源所需的資訊。URL 必須是絕對的，即它必須始終指定一個方案。URL 字元串按照其方案進行解析。通常會為 URL 建立一個串流處理程序，實際上無法為未提供處理程序的方案創建一個 URL 實例。相等性和雜湊計算依賴於方案和主機的 Internet 位址（如果有）；沒有定義比較。換句話說，URL 是一個結構化字元串，它支持解析的語法運算以及尋找主機和打開到指定資源的連接之類別的網路 I/O 操作。

從以下版本開始：: 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()` 以 US-ASCII 字元串形式返回此 URI 的內容。
`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 中指定的語法非常相似，除了以下細微不同：

只要空的授權組成部分後面帶一個非空(null)路徑、一個查詢組成部分，或一個片段組成部分，就允許使用該空授權組成部分。這樣就可以對類似 "file:///foo/bar" 的 URI 進行解析，這樣做似乎是 RFC 2396 的意願，儘管其語法不允許這樣。如果授權組成部分為空，則使用者資訊、主機和埠號組成部分都是未定義的。
允許空的相對路徑；這似乎是 RFC 2396 的意願，儘管語法不允許這樣。此細微不同帶來的主要後果是，單獨的片段（如 "#foo"）將作為帶空路徑和給定片段的相對 URI 進行解析，並可根據基本 URI 進行有效的解析。
對主機組成部分中的 IPv4 位址進行嚴格的解析，正如 RFC 2732 指定的一樣：點號分隔的由四部分組成的位址的每個元素都必須包含不超過三個十進制數字。每個元素被約束為值不能大於 255。
主機組成部分中的主機名如果只包含一個單獨的域標籤，則允許其以 alphanum 字元開始。這似乎是 RFC 2396 的 3.2.2 節的意願，儘管其語法不允許這樣。此細微不同帶來的結果是，分層 URI 的授權組成部分（比如 s://123）將作為基於伺服器的授權進行解析。
主機組成部分允許使用 IPv6 位址。IPv6 位址必須括在方括號 ('[' 和 ']') 中，正如 RFC 2732 指定的一樣。IPv6 位址本身必須按照 RFC 2373 進行解析。IPv6 位址進一步約束為只能描述不超過十六個位元組的位址資訊，該約束在 RFC 2373 隱式給出，沒有在語法中明確說明。
只要 RFC 2396 允許轉義八位組，就允許使用其他類別別中的字元，即使用者資訊、路徑、查詢和片段組成部分以及授權組成部分（如果授權是基於註冊表的）中的內容。這樣，除了 US-ASCII 字元集中的字元，URI 中還可以包含 Unicode 字元。

參數：: 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。

如果給定了方案，則路徑（如果也給定）必須為空或以斜線字元 ('/') 開始。否則通過為相應的參數傳入 null，或者在 port 參數的情況下，傳入 -1，新 URI 的組成部分可能保留為未定義。

此建構子首先根據 RFC 2396 中的 5.2 節的步驟 7 指定的規則從給定的組成部分建構一個 URI 字元串：

起初，結果字元串為空。
如果給定了方案，則將方案添加到結果後面，後面再加一個冒號 (':') 字元。
如果給定了使用者資訊、主機或埠號，則添加 "//" 字元串。
如果給定了使用者資訊，則添加該資訊，之後是「商用 at」字元 ('@')。任何不屬於 unreserved、punct、escaped 或 other 類別別的字元都應該進行參考。
如果給定了主機，則添加該主機。如果主機為文字值 IPv6 位址但未括在方括號 ('[' 和 ']') 中，則添加方括號。
如果給定了埠號名，則添加一個冒號字元 (':')，之後是十進制形式的埠號號。
如果給定了路徑，則添加該路徑。任何不屬於 unreserved、punct、escaped 或 other 類別別的字元，以及不等於斜線字元 ('/') 或「商用 at」字元 ('@') 的字元都應該進行參考。
如果給定了查詢，則添加一個問號字元 ('?')，之後是查詢。任何不是合法 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。

如果給定了方案，則路徑（如果也給定）必須為空或以斜線字元 ('/') 開始。否則，通過為相應的參數傳入 null，新 URI 的組成部分可能保留為未定義。

該建構子首先根據 RFC 2396 的 5.2 節的步驟 7 指定的規則從給定組成部分建構一個 URI 字元串：

起初，結果字元串為空。
如果給定了方案，則將方案添加到結果後面，後面再加一個冒號 (':')字元。
如果給定了授權，則添加 "//" 字元串，之後是授權。如果授權包含一個文字值 IPv6 位址，則該位址必須括在方括號 ('[' 和 ']') 中。任何不屬於 unreserved、punct、escaped 或 other 類別別的字元，以及不等於「商用 at」字元 ('@') 的字元都應該進行參考。
如果給定了路徑，則添加該路徑。任何不屬於 unreserved、punct、escaped 或 other 類別別的字元，以及不等於斜線字元 ('/') 或「商用 at」字元 ('@') 的字元都應該進行參考。
如果給定了查詢，則添加一個問號字元 ('?')，之後是查詢。任何不是合法 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，組成部分可保留未定義。

此便捷建構子的工作方式類似於調用帶七個參數的建構子，如下所示：

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

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" 中的授權組成部分，並不是一個合法的基於伺服器的授權，但卻是一個合法的基於註冊表的授權。

在許多一般情況下，例如，當已知正常的 URI 為 URN 或 URL 時，所使用的分層 URI 總是基於伺服器的。因此，它們要麼同樣被解析，要麼同樣被視為錯誤。在這種情況下，類似如下語句

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

可用於確保 u 在以下情況始終參考一個 URI：它有一個授權組成部分、一個基於伺服器的授權以及適當的使用者資訊、主機和埠號組成部分。調用此方法還可確保授權無法用相應的方法解析時，能夠根據拋出的異常發出適當的診斷訊息。

返回：: 其授權欄位已作為基於伺服器的授權解析的 URI
拋出：: URISyntaxException - 如果此 URI 的授權部分已定義，但是按照 RFC2396 不能解析為基於伺服器的授權

normalize

public URI normalize()

規範化此 URI 的路徑。

如果此 URI 為不透明的，或者其路徑已經是規範形式，則返回此 URI。否則，將建構一個新的 URI，它與此 URI 基本相同，只有路徑是通過規範化此 URI 的路徑計算得出的，規範化的方式與 RFC 2396 的 5.2 節的步驟 6 的子步驟 c 到 f 一致；即：

移除所有 "." 部分。
如果 ".." 部分的前面有一個非 ".." 部分，則這兩個部分都被移除。重複此步驟，直至不適合以上條件。
如果路徑為相對的，並且如果它的第一個部分包含一個冒號字元 (':')，則預先考慮一個 "." 部分。這防止具有諸如 "a:b/c/d" 這樣的路徑的相對 URI 在後續被重新解析為具有方案 "a" 和特定於方案的部分 "b/c/d" 的不透明 URI。（與 RFC 2396 有些出入)

如果 ".." 前面沒有足夠的非 ".." 部分以允許移除 ".."，則規範化路徑將以一個或多個 ".." 部分開頭。如果已按照上述步驟 3 插入了一個路徑，規範化路徑將以一個 "." 部分開頭。否則，規範化路徑將不包含任何 "." 或 ".." 部分。

返回：: 一個與此 URI 相等的 URI，但其路徑為規範形式

resolve

public URI resolve(URI uri)

根據此 URI 解析給定的 URI。

如果給定的 URI 已經是絕對的，或如果此 URI 是不透明的，則返回給定的 URI。

如果給定 URI 的片段組成部分已定義，其路徑組成部分為空，並且其方案、授權及查詢組成部分未定義，則返回一個 URL，它是由一個給定的片段及本 URL 的所有其他組成部分構成。這允許表示單獨片段參考的 URI（比如 "#foo"）根據基本 URI 進行有效的解析。

否則，此方法以與 RFC 2396 的 5.2 節一致的方式建構新的分層 URI；即：

用此 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

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 相對化按以下方式計算：

如果此 URI 或給定 URI 是不透明的，或者如果兩個 URI 的方案和授權組成部分不相同，或者如果此 URI 的路徑不是給定 URI 的路徑前綴，則返回給定的 URI。
否則，使用從給定 URI 獲取的查詢和片段組成部分，以及通過把此 URI 的路徑從給定 URL 的路徑開頭處移除而得到的路徑組成部分，建構新的相對分層 URL。

參數：: 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 的方案組成部分（如果定義了）只包含 alphanum 類別別和字元串 "-.+" 中的字元。方案始終以 alpha 字元開始。

URI 的方案組成部分不能包含轉義八位組，因此此方法不執行任何解碼操作。

返回：: 此 URI 的方案組成部分，或者如果方案未定義，則返回 null

isAbsolute

public boolean isAbsolute()

判斷此 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 的授權組成部分（如果定義了）只包含「商用 at」字元 ('@') 和 unreserved、punct、escaped 和 other 類別別中的字元。如果授權是基於伺服器的，則它被進一步約束為具有有效的使用者資訊、主機和埠號組成部分。

返回：: 此 URI 的原始授權組成部分，如果授權未定義，則返回 null

getAuthority

public String getAuthority()

返回此 URI 的已解碼的授權組成部分。

除了轉義八位組的所有序列都已解碼之外，此方法返回的字元串與 getRawAuthority 方法返回的字元串相等。

返回：: 此 URI 的已解碼的授權組成部分，如果授權未定義，則返回 null

getRawUserInfo

public String getRawUserInfo()

返回此 URI 的原始使用者資訊組成部分。

URI 的使用者資訊組成部分（如果定義了）只包含 unreserved、punct、escaped 和 other 類別別中的字元。

返回：: 此 URI 的原始使用者資訊組成部分，如果使用者資訊未定義，則返回 null

getUserInfo

public String getUserInfo()

返回此 URI 的已解碼的使用者資訊組成部分。

除了轉義八位組的所有序列都已解碼之外，此方法返回的字元串與 getRawUserInfo 方法返回的字元串相等。

返回：: 此 URI 的已解碼的使用者資訊組成部分，如果使用者資訊未定義，則返回 null

getHost

public String getHost()

返回此 URI 的主機組成部分。

URI 的主機組成部分（如果定義了）將具有以下形式之一：

由一個或多個由句點字元 ('.') 分隔的標籤組成的域名，後面可以跟隨一個句點字元。每個標籤由 alphanum 字元及連字元 ('-') 組成，但是連字元從不會出現在標籤的第一個或最後一個字元位置。由兩個或多個標籤組成的域名中最右邊的標籤以 alpha 字元開始。
點號分隔的由四部分組成的 IPv4 位址，其形式為數字+.數字+.數字+.數字+，其中，數字序列不超過三個字元，任何序列都不能大於 255。
套件含在方括號 ('[' 和 ']') 中的 IPv6 位址，由十六進制數、冒號字元 (':') 和可能會有的一個嵌入式 IPv4 位址組成。IPv6 位址的完整語法在 RFC 2373:IPv6 Addressing Architecture 中指定。

URI 的主機組成部分不能包含轉義八位組，因此此方法不執行任何解碼操作。

返回：: 此 URI 的主機組成部分，如果主機未定義，則返回 null

getPort

public int getPort()

返回此 URI 的埠號號。

URI 的埠號組成部分（如果定義了）是一個非負整數。

返回：: 此 URI 的埠號組成部分，如果埠號未定義，則返回 -1

getRawPath

public String getRawPath()

返回此 URI 的原始路徑組成部分。

URI 的路徑組成部分（如果定義了）只包含斜線字元 ('/')、「商用 at」字元 ('@') 以及 unreserved、punct、escaped 和 other 類別別中的字元。

返回：: 此 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。

如果要使兩個 URI 相等，則要求兩者都是不透明的或都是分層的。兩者的方案必須都是未定義的或相等（不區分大小寫）。兩者的片段必須都是未定義的或相等。

如果要使兩個不透明的 URI 相等，則其特定於方案的部分必須相等。

如果要使兩個分層 URI 相等，則其路徑必須相等，並且其查詢必須都是未定義的或相等。兩者的授權必須都是未定義的，或者都是基於註冊表的，或者都是基於伺服器的。如果其授權是定義的且都是基於註冊表的，則它們一定是相等的。如果其授權是定義的且都是基於伺服器的，則其主機一定是相等的（不區分大小寫），其埠號號一定是相等的，並且其使用者資訊組成部分也一定相等。

測試兩個 URI 的使用者資訊、路徑、查詢、片段、授權或特定於方案的部分是否相等時，比較的是這些組成部分的原始形式，而不是編碼後的形式，並且在比較轉義八位組的十六進制數字時，不區分大小寫。

此方法滿足 Object.equals 方法的常規協定。

覆寫：: 類別 Object 中的 equals

參數：: ob - 此物件將與之比較的物件
返回：: 當且僅當給定的物件是一個與此 URI 相同的 URI 時，返回 true
另請參見：: Object.hashCode(), Hashtable

hashCode

public int hashCode()

返回此 URI 的雜湊碼值。雜湊碼基於所有的 URI 組成部分，且滿足 Object.hashCode 方法的常規協定。

覆寫：: 類別 Object 中的 hashCode

返回：: 此 URI 的雜湊碼值
另請參見：: Object.equals(java.lang.Object), Hashtable

compareTo

public int compareTo(URI that)

將此 URI 與另一個物件（也必須是 URI）進行比較。

比較兩個 URI 的相應組成部分時，如果其中一個組成部分是未定義的，而另一個是定義的，則認為第一個小於第二個。除非另外說明，字元串組成部分按照其自然的、區分大小寫的順序進行排序，正如在 String.compareTo 方法中定義的一樣。比較經過編碼的字元串組成部分時，應按照其原始形式進行比較，而不是經過編碼的形式。

URI 的排序定義如下：

兩個具有不同方案的 URI 按照其方案的順序進行排序，不區分大小寫。
分層 URI 視為小於具有相同方案的不透明 URI。
兩個具有相同方案的不透明 URI 按照其特定於方案的部分的順序進行排序。
兩個具有相同方案和特定於方案的部分的不透明 URI 按照其段的順序進行排序。
兩個具有相同方案的分層 URI 按照其授權組成部分的順序進行排序：

如果兩個授權組成部分都是基於伺服器的，則 URI 按其使用者資訊組成部分進行排序；如果這些組成部分都相同，則 URI 按其主機的順序進行排序，不區分大小寫；如果主機相同，則 URI 按其埠號的順序進行排序。
如果授權組成部分中有一個或兩個都是基於註冊表的，則 URI 按照其授權組成部分的順序進行排序。

最後，具有相同方案和授權組成部分的兩個分層 URI 按照其路徑的順序進行排序；如果其路徑相同，則按照其查詢的順序進行排序；如果查詢相同，則按照其段的順序進行排序。

此方法滿足 Comparable.compareTo 方法的常規協定。

指定者：: 介面 Comparable<URI> 中的 compareTo

參數：: that - 此 URI 將與之比較的物件
返回：: 當此 URI 小於、等於或大於給定 URI 時，返回負整數、零或正整數
拋出：: ClassCastException - 如果給定物件不是一個 URI

toString

public String toString()

以字元串形式返回此 URI 的內容。

如果此 URI 通過調用此類別的建構子之一創建，則視情況返回一個與原始輸入字元串，或與從原始給定組成部分計算得出的字元串相等的字元串。否則，將通過規範化、解析或相對化創建此 URI，並根據 RFC 2396 的 5.2 節第 7 步指定的規則從此 URI 組成部分建構一個字元串。

覆寫：: 類別 Object 中的 toString

返回：: 此 URI 的字元串形式

toASCIIString

public String toASCIIString()

以 US-ASCII 字元串形式返回此 URI 的內容。

如果此 URI 未包含 other 類別別的任何字元，則調用此方法將返回的值與調用 toString 方法返回的值相同。否則，此方法的工作方式類似於調用該方法，然後對結果進行編碼。

返回：: 此 URI 的字元串形式，根據需要進行編碼以保證它只包含 US-ASCII 字元集中的字元

概觀

軟體套件

類別

使用

階層樹

已過時

索引

說明

Java^TM 2 Platform
Standard Ed. 6

上一個類別 下一個類別

框架 無框架

摘要：巢狀 | 欄位 | 建構子 | 方法

詳細資訊：欄位 | 建構子 | 方法

提交錯誤或意見

`mailto:java-net@java.sun.com`
`news:comp.lang.java`
`urn:isbn:096139210x`

java.net 類別 URI

URI 語法和組成部分

針對 URI 實例的運算

字元分類別

轉義八位組、參考、編碼和解碼

標識

URI、URL 和 URN

URI

URI

URI

URI

URI

create

parseServerAuthority

normalize

resolve

resolve

relativize

toURL

getScheme

isAbsolute

isOpaque

getRawSchemeSpecificPart

getSchemeSpecificPart

getRawAuthority

getAuthority

getRawUserInfo

getUserInfo

getHost

getPort

getRawPath

getPath

getRawQuery

getQuery

getRawFragment

getFragment

equals

hashCode

compareTo

toString

toASCIIString

java.net
類別 URI