2012/03/04

Android:CursorのAPIまとめ


Cursorについてjavadocの翻訳とメモ。
※誤訳あったらすみません

getColumnIndexとgetColumnIndexOrThrowは面白いですね。
片方はエラーコード(-1)を返すメソッドで、もう片方は例外をスローするメソッドです。

参考:http://developer.android.com/reference/android/database/Cursor.html

●Class 概要
このインタフェースは、データベースへのクエリによって返される結果セットへのランダ
ムアクセスを提供します。

カーソルの実装において同期保証は必須ではありません。
複数スレッドからカーソルを使用する側が同期を保証する必要があります。


●public abstract void close () 
Cursorのクローズは、全てのリソースを解放しこれを完全に無効とします。
deactivate()→requery()とは異なり、Cursorが再び有効(activate)となることはありません。


●public abstract void copyStringToBuffer (int columnIndex, CharArrayBuffer buffer) 
引数のバッファに参照列の内容をテキストで格納します。
バッファサイズが不十分である場合は、新たなcharバッファが割り当てられます。
参照列がnullの場合はバッファをそのまま返します。


●public abstract void deactivate () 
カーソルを無効にします。requery()が呼ばれるまでの間、すべての操作は失敗します。
非アクティブ(deactivate状態)のカーソルは、アクティブなカーソルよりも消費するリソ
ース量が少なくなります。


●public abstract int getColumnCount () 
参照列のカラム総数を取得します。


●public abstract int getColumnIndex (String columnName) 
指定した列名が何列目にあるのかを、0から始まるインデックスを返します。
列が存在しない場合は-1を返します。
もし、列が存在することを期待する場合は-1かどうかではなく、getColumnIndexOrThrow()
を使用したほうがより明確なコードになるでしょう。


●public abstract int getColumnIndexOrThrow (String columnName) 
指定した列名が何列目にあるのかを、0から始まるインデックスを返します。
列が存在しない場合はIllegalArgumentExceptionをスローします。
もし、列が存在するかしないのか不明確な場合はgetColumnIndex()を使用して戻り値-1を
判定したほうが効率的でしょう。


●public abstract String getColumnName (int columnIndex) 
与えられたインデックスにあたる列名を返します。
インデックスは0ベースである必要があります。


●public abstract String[] getColumnNames () 
結果セットにある全列名をString配列で返します。


●public abstract int getCount () 
Cursor内の行数を返します。


●public abstract byte[] getBlob (int columnIndex) 
取得要求のあったカラムのデータをバイト配列として返します。
対象カラムがnullであったり、Blobタイプでない場合の動作は実装依存です。


●public abstract double getDouble (int columnIndex)
取得要求のあったカラムのデータをdoubleとして返します。
対象カラムがnullであったり、doubleではない、またはdoubleで表現不可能な場合の動作
は実装依存です。


●public abstract float getFloat (int columnIndex) 
取得要求のあったカラムのデータをfloatとして返します。
対象カラムがnullであったり、floatではない、またはfloatで表現不可能な場合の動作は
実装依存です。


●public abstract int getInt (int columnIndex) 
取得要求のあったカラムのデータをintとして返します。
対象カラムがnullであったり、intではない、または有効範囲外な場合の動作は実装依存
です。


●public abstract long getLong (int columnIndex) 
取得要求のあったカラムのデータをlongとして返します。
対象カラムがnullであったり、longではない、または有効範囲外な場合の動作は実装依存
です。


●public abstract short getShort (int columnIndex) 
取得要求のあったカラムのデータをshortとして返します。
対象カラムがnullであったり、shortではない、または有効範囲外な場合の動作は実装依存
です。


●public abstract String getString (int columnIndex) 
取得要求のあったカラムのデータをStringとして返します。
対象カラムがnullであったり、Stringではない場合の動作は実装依存です。


●public abstract Bundle getExtras () 
Extra値であるBundleを返します。
これはユーザへメタ情報を提供するためのオプション機能です。
使用例としては、Cursorデータをフェッチして、ネットワーク要求の進捗を表示するよう
なケースがあります。
もし返却値がなければCursor定義値かBundle.EMPTYを返却します。
nullを返すことはありません。


●public abstract int getPosition () 
行セット上のCursor位置を返します(Cursorの位置は0から始まる)。
行セット上のCursor初期位置は-1で、先頭行よりも1つ手前にあります。
moveToNext()等により行末のカーソルが返された後のpositionは、最後の行セットを行き
過ぎ、count()と等しい値となります。


●public abstract int getType (int columnIndex) 
与えられたインデックスにあたる列の型を返します。
返される型は下記です。
  • FIELD_TYPE_NULL
  • FIELD_TYPE_INTEGER
  • FIELD_TYPE_FLOAT
  • FIELD_TYPE_STRING
  • FIELD_TYPE_BLOB


●public abstract boolean getWantsAllOnMoveCalls () 
onMove()がプロセス間でのみ呼ばれる場合はtrueを返します。
全てのCursorの移動が、onMove()の呼び出して発生するかどうかを返します。


●public abstract boolean isAfterLast () 
Cursorの位置が末尾行よりも後ろを指しているかどうかを返します。


●public abstract boolean isBeforeFirst () 
Cursorの位置が先頭行よりも前を指しているかどうかを返します。


●public abstract boolean isClosed () 
Cursorが閉じているかどうかを返します。


●public abstract boolean isFirst () 
Cursorの位置が先頭行を指しているかどうかを返します。


●public abstract boolean isLast () 
Cursorの位置が末尾行を指しているかどうかを返します。


●public abstract boolean isNull (int columnIndex)
指定したカラムの値がnullであるかどうかを返します。


●public abstract boolean move (int offset) 
Cursor位置をoffset分、前方あるいは後方に移動させます。
offsetは現在のCursor位置から見た相対的な値を指します。
1以上のオフセットは前方、-1以下のオフセットは後方への移動を意味します。
オフセットがCursor移動範囲の境界外への移動となる場合、前方あるいは後方への移動か
に応じてCursor位置が-1あるいはcount()の値に設定されます。

要求されたoffsetが移動可能な範囲内である場合、このメソッドはtrueを返し、そうでな
い場合はfalseを返します。
例えば、Cursorのpositionが2の状態でmove(-5)とした場合はfalseを返し、positionは-1
に更新されます。


●public abstract boolean moveToFirst () 
Cursorを先頭行に移動させます。


●public abstract boolean moveToLast () 
Cursorを末尾行に移動させます。


●public abstract boolean moveToNext () 
Cursorを次の行に移動させます。
Cursorが既に末尾行を過ぎている状態(isAfterLast)でコールするとfalseを返します。


●public abstract boolean moveToPrevious () 
Cursorを前の行に移動させます。
Cursorが先頭行よりも前(isBeforeFirst)の状態でコールするとfalseを返します。


●public abstract boolean moveToPosition (int position) 
Cursor位置をpositionが示す絶対位置へ移動させます。
有効範囲は -1<=position<=count() です。


●public abstract void registerContentObserver (ContentObserver observer)
Cursorを監視するためのオブサーバを登録します。
通常、データセットはrequeryが呼び出されるまで変化しません。


●public abstract void registerDataSetObserver (DataSetObserver observer) 
Cursorのデータセットを監視するためのオブサーバを登録します。
requery(), deactivate(), close()が呼ばれたときにこのデータセットは変更されます。


●public abstract void unregisterContentObserver (ContentObserver observer)
registerContentObserverで登録されたオブサーバを解除します。
参考:registerContentObserver(DataSetObserver)


●public abstract void unregisterDataSetObserver (DataSetObserver observer) 
registerDataSetObserverで登録されたオブサーバを解除します。
参考:registerDataSetObserver(DataSetObserver)


●public abstract void setNotificationUri (ContentResolver cr, Uri uri) 
変更を監視するコンテンツURIを登録します。
URIは特定のデータ行("content://my_provider_type/23")や、一般的な形式のURIを指定
することが可能です。
参考:registerContentObserver(ContentObserver)


●public abstract boolean requery () 
このメソッドは非推奨です。
deactive状態のCursorなど、クエリを再実行したい時に使用できるメソッドですが、
再実行にはいくらか時間のかかる可能性があるため、UIスレッドでこれをコールすると、
ANRを引き起こす可能性があります。


●public abstract Bundle respond (Bundle extras) 
ユーザがカーソルと通信するために用意されたオプション機能です。
Bundleの構造はCursor側で定義されます。
使用例としては、エラーを報告した後、ネットワークリクエストを再試行する必要がある
ことをCursorに伝えたい場合などが挙げられます。
引数・返却値はCursor定義値かBundle.EMPTYである必要があり、nullは許可されません。

以上です。