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で、先頭行よりも１つ手前にあります。
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は許可されません。
以上です。