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
以上です。