2012/03/29

Android:UriとUri.BuilderのAPI


android.net.UriおよびUri.BuilderクラスのAPIと、URI構文について
調査しました。

調査にあたっては下記javadocを参考としています。
http://developer.android.com/reference/android/net/Uri.html
http://developer.android.com/reference/android/net/Uri.Builder.html
http://e-class.center.yuge.ac.jp/jdk_docs/ja/api/java/net/URI.html


最高位レベルの文字列形式のURI構文は下記の通り([]内は省略可能)

 [scheme:]Scheme-Specific-Part[#fragment]


URIには「絶対URI」と「相対URI」が存在し、schemeの指定がある場合は絶対URI。
そうでない場合は相対URIとなる。

 絶対URI : yuki:android.com
 相対URI : ../../../test/hoge/


不透明URIはScheme-Specific-Part(以降「ssp」とする)部が'/'で始まらない絶対URI。

 tel:090xxxxxxxx


階層URIはssp部が'/'で始まる絶対URI。またはscheme部がない相対URI。

 http://google.com/hoge/foo
 ../../../test/hoge/

階層URIはさらに下記構文に従い解析される。

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

階層URIにおけるssp部はscheme部とfragment部の間の文字で構成される。

階層URIのAuthority部には「サーバベース」と「レジストリベース」が存在する。
「サーバベース」は下記構文に従って解析される。

  [UserInformation@]host[:port] 

「サーバベース」以外の構文は「レジストリベース」として解釈される。

階層URIのpath部が'/'で始まる場合は「絶対」、そうでない場合は「相対」と呼ばれる。


URIでは、下記9つのコンポーネントを持つ。
 scheme(String)
 ssp(String)
 authority(String)
 userInformation(String)
 host(String)
 port(Integer)
 path(String)
 query(String)
 fragment(String)


●android.net.Uri

Class Overview
イミュータブルなURI参照を提供する
URI参照はURIと'#'に続くfragment部を含む。
URIはRFC2396に準拠してURIを解析・構築する。

URIクラスはパフォーマンス向上のため引数が検証されない。
そのため、無効な入力に対する動作定義はない。
このクラスは非常に寛容で、無効な入力に対してゴミデータを返すのではなく、
指定のない限り例外がスローされる。


compareTo (Uri other)
otherとの文字列表現比較


buildUpon ()
このURI内容を引き継ぐ新たなURIビルダーを構築


encode (String s)
encode (String s, String allow)
引数sをUTF-8方式として'%'エスケープエンコードする。
未予約文字セット(英字("A-Z, "a-z")、数字("0-9")、文字("_-!.~'()*"))以外、
および引数指定されたallow以外の全ての文字をエンコードする。
Return:
 sのエンコード結果を返す。sがnullの場合はnullを返す。
Ex)
  a = a
  あ = %E3%81%82
  %E3%81%82 = %25E3%2581%2582


decode (String s)
UTF-8方式で'%'エスケープエンコードされた引数sをデコードする。
無効なオクテットはUnicodeで置き換えられる。
Return:
 sのデコード結果を返す。sがnullの場合はnullを返す。
Ex)
 a = a
 あ = あ
 %E3%81%82 = あ


parse (String uriString)
引数uriStringからURIオブジェクトを生成する。
Params:
 uriString : RFC 2396に準拠した、エンコード済みのURI文字列
Return:
 uriStringから生成したURI。
Throws:
 uriStringがnullの場合NullPointerExceptionをスローする。
Ex)
 http://あいうえお.com/#aaa = http://あいうえお.com/#aaa


fromFile (File file) 
引数fileからURIを生成する。
URIは"file://"から始まり、パスはエンコードされるが、パス区切り文字の'/'は例外とする。
Return:
 fileへのURI値を返す。
Throws:
 fileがnullの場合はNullPointerExceptionをスローする。
Ex)
 "/mnt/sdcard/test.txt = file:///mnt/sdcard/test.txt


getScheme ()
URIからscheme部を抽出する。
Return:
 相対パスの場合はnullを返す。
Ex)
 http://yuki312.blogspot.jp/ = http
 ftp://あいうえお.txt = ftp


getAuthority ()
URIからAuthority部をデコードして抽出する。
Return:
 URIのデコードされたAuthority部。存在しない場合はnullを返す。
Ex)
 http://a = a
 http://%E3%81%82 = あ
 http://%25E3%2581%2582 = %E3%81%82


getEncodedAuthority () 
URIからAuthority部を抽出する。
Return:
 URIのAuthority部。存在しない場合はnullを返す。
Ex)
 http://a = a
 http://%E3%81%82 = %E3%81%82
 http://%25E3%2581%2582 = %25E3%2581%2582


fromParts (String scheme, String ssp, String fragment) 
引数から不透明URIを生成する。
sspはエンコードされるため、このメソッドは階層的なURIを作成することができない。
Return:
 引数scheme, ssp, fragmentから構成されるURI
Throws:
 schemeかsspがnullの場合はNullPointerExceptionをスローする。
Ex)
 fromParts(a, b, c)  = a:b#c
 fromParts(あ, あ, あ)  = あ:%E3%81%82#%E3%81%82
 fromParts(%E3%81%82, %E3%81%82, %E3%81%82)  = %E3%81%82:%25E3%2581%2582#%25E3%2581%2582


getSchemeSpecificPart ()
URIからssp部をデコードして抽出する。
Return:
 デコードされたssp部。
Ex)
 http://a#fragment = //a
 http://あ#fragment = //あ
 http://%E3%81%82#fragment = //あ


getEncodedSchemeSpecificPart ()
URIからssp部を抽出する。
Return:
 ssp部。
Ex)
 http://a#fragment = //a
 http://あ#fragment = //あ
 http://%E3%81%82#fragment = //%E3%81%82


withAppendedPath (Uri baseUri, String pathSegment)
ベースURIにpathSegmentを追加した新たなURIを生成する。
Params:
 baseUri : pathSegmentを追加するURI
 pathSegment : エンコードされたパスセグメント
Return:
 ベースURIにpathSegmentを追加した新たなURIを返す。
Throws:
 baseUriがnullの場合NullPointerExceptionをスローする。
Ex)
 withAppendedPath(http://test, a)  = http://test/a
 withAppendedPath(http://test/, あ)  = http://test/あ
 withAppendedPath(http://test, %E3%81%82)  = http://test/%E3%81%82


getPath () 
URIからpath部をデコードして抽出する。
Return:
 デコードされたpath部。無効なURIや階層的URI("mailto:nobody@google.com")でない場
 合はnullを返す。
Ex)
 http:/a#fragment = /a
 http:/あ#fragment = /あ
 http:/%E3%81%82#fragment = /あ
 http://authority/a#fragment = /a


getEncodedPath ()
URIからpath部を抽出する。
Return:
 無効なURIや階層的URI("mailto:nobody@google.com")でない場合はnullを返す。
Ex)
 http://authority/a#fragment = /a
 http://authority/あ#fragment = /あ
 http://authority/%E3%81%82#fragment = /%E3%81%82


getLastPathSegment () 
URIのpath部から最後のセグメントをデコードして抽出する。
Return:
 デコードされた最後のセグメント。pathがnullの場合はnullを返す。
Ex)
 http://authority/a/b/c#fragment = c
 http://authority/あ/い/う#fragment = う
 http://authority/%E3%81%82/%E3%81%84/%E3%81%86#fragment = う


getPathSegments () 
URIからpathセグメントをデコードして抽出する。
Return:
 先頭と末尾の'/'を除いたpathセグメントを返す。
Ex)
 http://authority/a/b/c#fragment = [a, b, c]
 http://authority/あ/い/う#fragment = [あ, い, う]
 http://authority/%E3%81%82/%E3%81%84/%E3%81%86#fragment = [あ, い, う]


getQuery ()
URIからquery部をデコードして抽出する。
Return:
 デコードされたquery部。存在しない場合はnullを返す。
Ex)
 http://authority/path?q=a#fragment = q=a
 http://authority/path?q=あ#fragment = q=あ
 http://authority/path?q=%E3%81%82#fragment = q=あ
 http://authority/path?あ=あ#fragment = あ=あ
 http://authority/path?%E3%81%82=%E3%81%82#fragment = あ=あ
 http://authority/path?q=a&r=b#fragment = q=a&r=b


getEncodedQuery ()
URIからquery部を抽出する。
Return:
 エンコードされたquery部。存在しない場合はnullを返す。
Ex)
 http://authority/path?q=a#fragment = q=a
 http://authority/path?q=あ#fragment = q=あ
 http://authority/path?q=%E3%81%82#fragment = q=%E3%81%82
 http://authority/path?あ=あ#fragment = あ=あ
 http://authority/path?%E3%81%82=%E3%81%82#fragment = %E3%81%82=%E3%81%82
 http://authority/path?q=a&r=b#fragment = q=a&r=b


getQueryParameter (String key)
引数keyに対応するquery文字列を検索し、ヒットした最初の値を返す。
Params:
 key : エンコードされたkey
Return:
 keyに対応するデコードされたkey値。存在しない場合はnullを返す。
Throws:
 階層的URIで無い場合UnsupportedOperationExceptionをスローする。
 keyがnullの場合はNullPointerExceptionをスローする。
Ex)
 http://authority/path?q=a#fragment search(q) = a
 http://authority/path?q=あ#fragment search(q) = あ
 http://authority/path?q=%E3%81%82#fragment search(q) = あ
 http://authority/path?%E3%81%82=true#fragment search(あ) = null
 http://authority/path?あ=true#fragment search(%E3%81%82) = true
 http://authority/path?q=a&r=b#fragment search(r) = b
 http://authority/path?q=a&r=b#fragment search(s) = null


getBooleanQueryParameter (String key, boolean defaultValue)
引数keyに対応するquery文字列を検索し、ヒットした最初の値を返す。
値はbooleanとして解釈される。
値が"false"と"0"はfalse, それ以外はtrueとして解釈される。
Params:
 key : エンコードされたkey
 defaultValue : keyに対応するクエリがない場合のデフォルト値
Return:
 クエリパラメータkeyに対応するブール値解釈された値
Ex)
 http://authority/path?a=true#fragment search(a) defValue(false) = true
 http://authority/path?あ=true#fragment search(あ) defValue(false) = false
 http://authority/path?%E3%81%82=true#fragment search(あ) defValue(false) = true
 http://authority/path?あ=true#fragment search(%E3%81%82) defValue(false) = false
 http://authority/path?a=hoge#fragment search(a) defValue(false) = true
 http://authority/path?q=true#fragment search(r) defValue(false) = false


getQueryParameters (String key)
引数keyに対応するクエリを検索し、ヒットした値をデコードして返す。
Params:
 key : エンコードされたkey
Return:
 デコードされた値セット
Throws:
 階層的URIでない場合はUnsupportedOperationExceptionをスローする。
 keyがnullの場合はNullPointerExceptionをスローする。
Ex)
 http://authority/path?q=a#fragment search(q) = [a]
 http://authority/path?q=あ#fragment search(q) = [あ]
 http://authority/path?q=%E3%81%82#fragment search(q) = [あ]
 http://authority/path?q=a&q=b#fragment search(q) = [a, b]


getQueryParameterNames ()
クエリパラメータの一意の名前セットをデコードして取得する。
名前セットは出現順となる。
Return:
 デコードされたクエリパラメータ名のセット。
Throws:
 階層URIでない場合UnsupportedOperationExceptionをスローする。
Ex)
 http://authority/path?a=v#fragment search(q) = [a]
 http://authority/path?あ=v#fragment search(q) = [あ]
 http://authority/path?%E3%81%82=v#fragment search(q) = [あ]
 http://authority/path?q=a&r=b#fragment search(q) = [q, r]


getFragment ()
URIからfragment部をデコードして抽出する。
fragment部は'#'以降の全てとなる。
Return:
 URIのデコードされたfragment部。存在しない場合はnullを返す。
Ex)
 http://authority/path#a = a
 http://authority/path#あ = あ
 http://authority/path#%E3%81%82 = あ


getEncodedFragment () 
URIからFragment部を抽出する。
Return:
 '#'以降の全ての値を返す。
Ex)
 http://authority/path#a = a
 http://authority/path#あ = あ
 http://authority/path#%E3%81%82 = %E3%81%82


getUserInfo ()
URIのAuthority部からUserInformation部をデコードして抽出する。
Return:
 URIのUserInformation部。存在しない場合はnullを返す。
Ex)
 http://a@host.com:8080/path = a
 http://あ@host.com:8080/path = あ
 http://%E3%81%82@host.com:8080/path = あ


getEncodedUserInfo ()
URIのAuthority部からUserInformation部を抽出する。
Return:
 URIのUserInformation部。存在しない場合はnullを返す。
Ex)
 http://a@host.com:8080/path = a
 http://あ@host.com:8080/path = あ
 http://%E3%81%82@host.com:8080/path = %E3%81%82


getHost ()
URIのAuthority部からhost部をデコードして抽出する。
Return:
 URIのhost部。存在しない場合はnullを返す。
Ex)
 http://userInfo@a.com:8080/path = a.com
 http://userInfo@あ.com:8080/path = あ.com
 http://userInfo@%E3%81%82.com:8080/path = あ.com


getPort ()
URIのAuthority部からport部を抽出する。
Return:
 URIのport部。無効、あるいは存在しない場合は-1を返す。
Ex)
 http://userInfo@a.com:8080/path = 8080


isAbsolute ()
絶対URIであるかを判定する。
明示的にschemeが含まれている場合などに該当する。
Return:
 絶対URIである場合true. 相対URIの場合等はfalseを返す。
Ex)
 http://hoge/foo/bar = true
 /hoge/foo/bar = false
 ../hoge/foo/bar = false


isRelative ()
相対的URIであるかを判定する。
schemeが含まれていない場合などが該当する。
Return:
 相対URIの場合はtrue。絶対URIの場合等はfalseを返す。
Ex)
 http://hoge/foo/bar = false
 /hoge/foo/bar = true
 ../hoge/foo/bar = true


isHierarchical ()
"http://google.com"のような階層的URIであるかを判定する。
ssp部が'/'で始まる場合、絶対URIは階層的URIとなる。
相対URIは常に階層的URIとなる。
Ex)
 http://hoge/foo/bar = true
 /hoge/foo/bar = true
 tel:090xxxxxxxx = false


isOpaque ()
"mailto:nobody@google.com"のような不透明URIであるかを判定する。
ssp部が'/'で始まらない場合は不透明URIとなる。
Ex)
 http://hoge/foo/bar = false
 /hoge/foo/bar = false
 tel:090xxxxxxxx = true


=================================================

●android.net.Uri.Builder

Class Overview
URI参照を構築・操作するためのヘルパークラス。
このクラスはスレッドセーフではない。

階層的絶対URIは"://?#"パターンに従う。

相対URI(常に階層構造である)は"?#"、"//?# "パターンのいずれかに従う。

不透明URIは":#"パターンに従う。

既存のURIからなるビルダーを取得するにはUri.buildUpon()を使用する。


build ()
ビルダに設定した属性をもつURIを構築する。
Throws:
 不透明URIかつscheme部がnullの場合URIUnsupportedOperationExceptionをスローする。


scheme (String scheme) 
scheme部を設定する。
Params:
 scheme : scheme名、または相対URIの場合null
Ex)
 "scheme://authority/path?queryKey=value#fragment"を基本形として、、、
 a = a://authority/path?queryKey=value#fragment
 あ = あ://authority/path?queryKey=value#fragment
 %E3%81%82 = %E3%81%82://authority/path?queryKey=value#fragment


opaquePart (String opaquePart) 
引数opaquePartをエンコードして不透明ssp部として設定する。
Params:
 opaquePart : デコードされた不透明ssp部
Ex)
 "scheme://authority/path?queryKey=value#fragment"を基本形として、、、
 a = scheme:a#fragment
 あ = scheme:%E3%81%82#fragment
 %E3%81%82 = scheme:%25E3%2581%2582#fragment


encodedOpaquePart (String opaquePart)
引数opaquePartを不透明ssp部に設定する。
Params:
 opaquePart : エンコードされた不透明ssp部
Ex)
 "scheme://authority/path?queryKey=value#fragment"を基本形として、、、
 a = scheme:a#fragment
 あ = scheme:あ#fragment
 %E3%81%82 = scheme:%E3%81%82#fragment


authority (String authority)
引数authorityをAuthority部にエンコードして設定する。
Ex)
 "scheme://authority/path?queryKey=value#fragment"を基本形として、、、
 a = scheme://a/path?queryKey=value#fragment
 あ = scheme://%E3%81%82/path?queryKey=value#fragment
 %E3%81%82 = scheme://%25E3%2581%2582/path?queryKey=value#fragment


encodedAuthority (String authority)
引数authorityをAuthority部に設定する。
Ex)
 "scheme://authority/path?queryKey=value#fragment"を基本形として、、、
 a = scheme://a/path?queryKey=value#fragment
 あ = scheme://あ/path?queryKey=value#fragment
 %E3%81%82 = scheme://%E3%81%82/path?queryKey=value#fragment


path (String path) 
引数pathをpath部にエンコードして設定する。
文字'/'はそのままエンコードされない。
Ex)
 "scheme://authority/path?queryKey=value#fragment"を基本形として、、、
 a = scheme://authority/a?queryKey=value#fragment
 あ = scheme://authority/%E3%81%82?queryKey=value#fragment
 %E3%81%82 = scheme://authority/%25E3%2581%2582?queryKey=value#fragment
 a/b = scheme://authority/a/b?queryKey=value#fragment


encodedPath (String path)
引数pathをpath部に設定する。
パスが非null、かつ'/'で開始していない、かつAuthority or Scheme指定している場合、
ビルダはpathに'/'を付加する。
Ex)
 "scheme://authority/path?queryKey=value#fragment"を基本形として、、、
 a = scheme://authority/a?queryKey=value#fragment
 あ = scheme://authority/あ?queryKey=value#fragment
 %E3%81%82 = scheme://authority/%E3%81%82?queryKey=value#fragment
 a/b = scheme://authority/a/b?queryKey=value#fragment


appendPath (String newSegment)
引数newSegmentをpath部にエンコードして追加する。
Ex)
 "scheme://authority/path?queryKey=value#fragment"を基本形として、、、
 a = scheme://authority/path/a?queryKey=value#fragment
 あ = scheme://authority/path/%E3%81%82?queryKey=value#fragment
 %E3%81%82 = scheme://authority/path/%25E3%2581%2582?queryKey=value#fragment
 a/b = scheme://authority/path/a%2Fb?queryKey=value#fragment


appendEncodedPath (String newSegment)
引数newSegmentをpath部に追加する。
Ex)
 "scheme://authority/path?queryKey=value#fragment"を基本形として、、、
 a = scheme://authority/path/a?queryKey=value#fragment
 あ = scheme://authority/path/あ?queryKey=value#fragment
 %E3%81%82 = scheme://authority/path/%E3%81%82?queryKey=value#fragment
 a/b = scheme://authority/path/a/b?queryKey=value#fragment



query (String query)
引数queryをquery部にエンコードして設定する。
Ex)
 "scheme://authority/path?queryKey=value#fragment"を基本形として、、、
 a = scheme://authority/path?a#fragment
 a=a = scheme://authority/path?a%3Da#fragment
 あ=あ = scheme://authority/path?%E3%81%82%3D%E3%81%82#fragment
 %E3%81%82=%E3%81%82 = scheme://authority/path?%25E3%2581%2582%3D%25E3%2581%2582#fragment


encodedQuery (String query)
引数queryをquery部に設定する。
Ex)
 "scheme://authority/path?queryKey=value#fragment"を基本形として、、、
 a=a = scheme://authority/path?a=a#fragment
 あ=あ = scheme://authority/path?あ=あ#fragment
 %E3%81%82=%E3%81%82 = scheme://authority/path?%E3%81%82=%E3%81%82#fragment
 scheme://authority/path#fragment


appendQueryParameter (String key, String value)
引数keyとvalueをquery部にエンコードして追加する。
Params:
 key : エンコードされるキー
 value : エンコードされる値
Ex)
 "scheme://authority/path?queryKey=value#fragment"を基本形として、、、
 a = scheme://authority/path?queryKey=value&a=a#fragment
 あ = scheme://authority/path?queryKey=value&%E3%81%82=%E3%81%82#fragment
 %E3%81%82 = scheme://authority/path?queryKey=value&%25E3%2581%2582=%25E3%2581%2582#fragment


clearQuery ()
設定したクエリを消去します。
Ex)
 "scheme://authority/path?queryKey=value#fragment"を基本形として、、、


fragment (String fragment) 
引数fragmentをframgnet部に設定する。
Ex)
 "scheme://authority/path?queryKey=value#fragment"を基本形として、、、


encodedFragment (String fragment)
引数fragmentをfragment部にエンコードして設定する。
Ex)
 "scheme://authority/path?queryKey=value#fragment"を基本形として、、、
 a = scheme://authority/path?queryKey=value#a
 あ = scheme://authority/path?queryKey=value#%E3%81%82
 %E3%81%82 = scheme://authority/path?queryKey=value#%25E3%2581%2582

以上です。