Курсор Android, что это такое

Обновлено: 30.09.2022

Некоторая информация относится к предварительной версии продукта, которая может быть существенно изменена до ее выпуска. Microsoft не дает никаких явных или подразумеваемых гарантий в отношении представленной здесь информации.

Реализация Cursor, предоставляющая результаты запроса к базе данных SQLiteDatabase.

Примечания

Части этой страницы представляют собой модификации, основанные на работе, созданной и предоставленной Android Open Source Project, и используются в соответствии с условиями, описанными в лицензии Creative Commons 2.5 Attribution.

Конструкторы

Конструктор, используемый при создании управляемых представлений объектов JNI; вызывается средой выполнения.

Выполнить запрос и предоставить доступ к его набору результатов через интерфейс Cursor.

Выполнить запрос и предоставить доступ к его набору результатов через интерфейс Cursor.

Свойства

Возвращает класс среды выполнения этого объекта.

Возвращает общее количество столбцов

Возвращает количество строк в курсоре.

Получить базу данных, с которой связан этот курсор.

Возвращает набор дополнительных значений.

Дескриптор базового экземпляра Android.

Возвращает значение true, если с курсором связано окно курсора.

Возвращает значение, указывающее, указывает ли курсор на позицию после последней строки.

Возвращает значение, указывающее, указывает ли курсор на позицию перед первой строкой.

вернуть true, если курсор закрыт

Возвращает значение, указывает ли курсор на первую строку.

Возвращает значение, указывающее, указывает ли курсор на последнюю строку.

Если MRowIdColumnIndex не равен -1, это содержит значение столбца в MRowIdColumnIndex для текущей строки, на которую указывает этот курсор.

Это должно быть установлено на индекс столбца идентификатора строки любым подклассом, который хочет поддерживать обновления.

Окно курсора, принадлежащее этому курсору.

Возвращает URI, по которому будут доставляться уведомления об изменениях в данных этого курсора, как ранее было установлено SetNotificationUri(ContentResolver, Uri).

Возвращает текущую позицию курсора в наборе строк.

Этот API поддерживает инфраструктуру Mono для Android и не предназначен для использования непосредственно из вашего кода.

Этот API поддерживает инфраструктуру Mono для Android и не предназначен для использования непосредственно из вашего кода.

onMove() будет вызываться между процессами только в том случае, если этот метод возвращает значение true.

Если курсор поддерживается CursorWindow , возвращает предварительно заполненное окно с содержимым курсора, иначе null.

Методы

Эта функция генерирует исключение CursorIndexOutOfBoundsException, если позиция курсора выходит за границы.

Создает и возвращает копию этого объекта.

Закрывает курсор, освобождая все его ресурсы и делая его полностью недействительным.

Извлекает запрошенный текст столбца и сохраняет его в предоставленном буфере.

Деактивирует курсор, в результате чего все вызовы к нему завершаются неудачно, пока не будет вызвана функция Requery().

Указывает, равен ли какой-либо другой объект этому объекту.

Копирует данные курсора в окно.

Возвращает значение запрошенного столбца в виде массива байтов.

Возвращает отсчитываемый от нуля индекс для заданного имени столбца или -1, если столбец не существует.

Возвращает отсчитываемый от нуля индекс для заданного имени столбца или создает исключение IllegalArgumentException, если столбец не существует.

Возвращает имя столбца по заданному индексу столбца, начинающемуся с нуля.

Возвращает массив строк, содержащий имена всех столбцов результирующего набора в том порядке, в котором они были перечислены в результате.

Возвращает значение запрошенного столбца как двойное.

Возвращает значение запрошенного столбца в виде числа с плавающей запятой.

Возвращает значение хэш-кода для объекта.

Возвращает значение запрошенного столбца в виде целого числа.

Возвращает значение запрошенного столбца в формате long.

Возвращает значение запрошенного столбца как короткое.

Возвращает значение запрошенного столбца в виде строки.

Возвращает тип данных значения заданного столбца.

Возвращает значение true, если значение в указанном столбце равно нулю.

Вызывается сборщиком мусора для объекта, когда сборщик мусора определяет, что больше нет ссылок на объект.

Переместить курсор на относительную величину вперед или назад от текущей позиции.

Переместите курсор на первую строку.

Переместите курсор в последнюю строку.

Переместите курсор на следующую строку.

Переместите курсор в абсолютную позицию.

Переместите курсор на предыдущую строку.

Просыпает один поток, ожидающий на мониторе этого объекта.

Просыпает все потоки, ожидающие на мониторе этого объекта.

Подклассы должны вызывать этот метод после завершения фиксации обновлений, чтобы уведомить всех наблюдателей.

Эта функция вызывается каждый раз, когда курсор успешно перемещается в новую позицию, что дает подклассу возможность обновить любое состояние, которое у него может быть.

Зарегистрируйте наблюдатель, который вызывается, когда происходят изменения в содержимом, поддерживающем этот курсор.

Зарегистрируйте наблюдатель, который вызывается при изменении содержимого набора данных курсоров, например, когда набор данных изменяется с помощью Requery(), Deactivate() или Close().

Выполняет запрос, который снова создал курсор, обновляя его содержимое.

Это внеполосный способ связи пользователя курсора с курсором.

Управляет получением строк относительно запрошенной позиции.

Задает свойство Handle.

Указывает URI контента для отслеживания изменений.

Изменяет аргументы выбора.

Устанавливает новое окно курсора для использования курсором.

Возвращает строковое представление объекта.

Отменить регистрацию наблюдателя, который ранее был зарегистрирован с этим курсором, с помощью RegisterContentObserver(ContentObserver).

Отменить регистрацию наблюдателя, который ранее был зарегистрирован с этим курсором, с помощью RegisterContentObserver(ContentObserver).

Архитектор Android Адам Страуд представляет Android API для работы с базами данных и объясняет, как получить данные из приложения в базу данных и обратно.

Эта глава из книги

Эта глава из книги

Эта глава из книги 

В предыдущей главе были представлены классы SQLiteOpenHelper и SQLiteDatabase и обсуждалось, как создавать базы данных. Конечно, это только первый шаг, так как база данных не очень полезна, пока не содержит данные и не позволяет программному обеспечению выполнять запросы к этим данным. В этой главе объясняется, как это делается в Android, путем обсуждения того, какие классы Android SDK можно использовать для управления базой данных, а также для запросов к базе данных.

Управление данными в Android

Android SDK содержит множество классов для поддержки операций с базой данных. Наряду с классами для поддержки операций создания, чтения, обновления и удаления (CRUD) пакет SDK содержит классы, помогающие создавать запросы для чтения базы данных. Ниже приведены классы, представленные в этой главе, и краткое описание того, как они используются для работы с базами данных в Android:

SQLiteDatabase: представляет базу данных в Android. Он содержит методы для выполнения стандартных операций CRUD базы данных, а также для управления файлом базы данных SQLite, используемым приложением.

Курсор: содержит набор результатов запроса к базе данных. Приложение может считывать данные из курсора и отображать их пользователю или выполнять бизнес-логику на основе данных, содержащихся в курсоре.

ContentValues: хранилище ключей и значений, которое вставляет данные в строку таблицы. В большинстве случаев ключи сопоставляются с именами столбцов таблицы, а значения — это данные, которые нужно ввести в таблицу.

CursorLoader: часть платформы загрузчика, которая обрабатывает объекты курсора.

LoaderManager: управляет всеми загрузчиками для действия или фрагмента. LoaderManager содержит API для инициализации и сброса загрузчика, который может использоваться компонентами Android.

Работа с SQL является важной частью работы с базами данных в Android. В главе 2 «Введение в SQL» мы увидели, как SQL используется как для создания, так и для обновления базы данных. SQL также можно использовать для чтения, обновления и удаления информации из базы данных в Android. Android SDK предоставляет полезные классы, помогающие создавать операторы SQL, а также поддерживает использование обработки строк Java для создания операторов SQL.

Работа с SQL в Android включает вызов методов объекта SQLiteDatabase. Этот класс содержит методы для создания операторов SQL, а также удобные методы, облегчающие ввод операторов SQL в базу данных.

В типичном случае использования базы данных вставка данных в базу данных — это шаг, следующий за созданием базы данных. Это имеет смысл, поскольку база данных полезна только после того, как она содержит данные. Шаги по созданию базы данных были рассмотрены в предыдущей главе, поэтому обсуждение начинается с вставки данных в базу данных.

Вставка строк в таблицу

Класс SQLiteDatabase содержит несколько удобных методов, которые можно использовать для выполнения операций вставки. В большинстве случаев для выполнения операции вставки используется один из следующих трех методов:

длинная вставка (таблица String, String nullColumnHack, значения ContentValues)

long insertOrThrow(String table, String nullColumnHack, значения ContentValues)

long insertWithOnConflict(String table, String nullColumnHack, значения ContentValues, int конфликтный алгоритм)

Обратите внимание, что списки параметров для всех вариантов методов вставки содержат (в качестве первых трех параметров) String tableName, String nullColumnHack и Значения ContentValues. SQLiteDatabase.insertWithOnConflict() содержит четвертый параметр, который будет рассмотрен позже. Три общих параметра для методов вставки:

Таблица строк: дает имя таблицы, для которой выполняется операция вставки. Это имя должно совпадать с именем, данным таблице при ее создании.

String nullColumnHack: указывает столбец, которому будет присвоено значение null, если аргумент ContentValues не содержит данных.

Значения ContentValues: Содержит данные, которые будут вставлены в таблицу.

ContentValues — это класс, похожий на карту, который сопоставляет значение с ключом String. Он содержит несколько перегруженных методов put, обеспечивающих безопасность типов. Вот список методов put, поддерживаемых ContentValues:

void put(строковый ключ, байтовое значение)

void put(строковый ключ, целочисленное значение)

void put(строковый ключ, значение с плавающей запятой)

void put(строковый ключ, короткое значение)

void put(строковый ключ, значение byte[])

void put(строковый ключ, строковое значение)

void put(строковый ключ, двойное значение)

void put(строковый ключ, длинное значение)

void put(строковый ключ, логическое значение)

Каждый метод put принимает в качестве параметров строковый ключ и введенное значение. При использовании ContentValues для вставки данных в базу данных параметр key должен совпадать с именем столбца для таблицы, на которую нацелена вставка.

Помимо только что перечисленных перегруженных методов put, существует также метод put(ContentValues ​​other), который можно использовать для добавления всех значений из другого ContentValues и метод putNull(String key), добавляющий значение null в столбец таблицы.

В типичном случае создается новый экземпляр ContentValues, который заполняется всеми значениями, которые необходимо вставить в таблицу. Затем объект ContentValues передается одному из методов вставки из SQLiteDatabase. В листинге 5.1 показано типичное использование ContentValues.

Листинг 5.1. Вставка данных с помощью SQLiteDatabase.insert()

Код в листинге 5.1 передает null для значения nullColumnHack методу SQLiteDatabase.insert(). В первую очередь это связано с тем, что код в листинге 5.1 «знает», какие значения использовались для заполнения параметра values, и может гарантировать, что в объекте ContentValues представлен хотя бы один столбец. . Однако это не всегда так, поэтому существует параметр nullColumnHack.

Чтобы объяснить nullColumnHack, рассмотрим случай, когда объект ContentValues, вставленный в таблицу, не содержит пар ключ/значение. Это равносильно попытке выполнить операцию вставки без указания каких-либо столбцов для вставки данных. Такой оператор вставки недопустим в SQL, поскольку оператор вставки должен указывать по крайней мере один столбец для вставки данных. Параметр nullColumnHack можно использовать для защиты от варианта использования «пустые ContentValues», указав имя столбца, для которого должно быть установлено значение null. в случае, если объект ContentValues не содержит данных. Как и ключи в экземпляре ContentValues, строковое значение для nullColumnHack должно совпадать с именем столбца в таблице, на который нацелен оператор вставки.

В листинге 5.2 показано использование параметра nullColumnHack. После запуска кода в листинге 5.2 столбец last_name будет содержать значение null.

Листинг 5.2. Указание пустых столбцов с помощью nullColumnHack

Все три метода вставки SQLiteDatabase возвращают long. Значение, возвращаемое методами, представляет собой идентификатор вставленной строки или значение –1, если при вставке произошла ошибка.

В программировании для Android хранение данных в базе данных не является обычной практикой, поскольку у нас есть другие и наиболее подходящие методы для хранения наших данных, такие как способ SharedPreferences. Однако у нас есть очень мощный инструмент, который может помочь нашему Android-приложению взаимодействовать с базой данных, и это SQLite. SQLite — это база данных с открытым исходным кодом для структурированных данных в реляционных базах данных. Он встроен в Android, поэтому вам не нужно делать ничего особенного для настройки или администрирования сервера SQLite.

Итак, когда мы хотим взаимодействовать с базой данных внутри приложения Android, мы должны предоставить нашей деятельности право на произвольный доступ для чтения и записи к содержимому этой базы данных.По этой причине в Android есть интерфейс Cursor, который обеспечивает произвольный доступ для чтения и записи к набору результатов, возвращаемому запросом к базе данных.

В этом примере мы увидим очень простое и распространенное использование класса Cursor в примере SQLite.
В нашем примере будут использоваться следующие инструменты на платформе 64-разрядной версии Windows или OS X:

  • JDK 1.7
  • Затмение 4.2 Юнона
  • Android SDK 4.4.2

Давайте посмотрим поближе:

1. Создайте новый проект приложения для Android

Откройте Eclipse IDE и выберите «Файл» → «Создать» → «Проект» → «Проект приложения Android».

Рис. 2. Создание нового проекта Android

Рис. 1. Создание нового проекта Android

Укажите имя приложения, проекта и пакета, а затем нажмите "Далее".

Рис. 2. Создание нового Название проекта Android

Рисунок 2. Создание нового имени проекта Android

В следующем окне необходимо отметить параметр «Создать действие». Новая созданная активность будет основной активностью вашего проекта. Затем нажмите кнопку «Далее».

Создать действие

Рисунок 3. Настройка проекта

В окне «Настроить значок запуска» вы должны выбрать значок, который хотите использовать в своем приложении. Мы будем использовать значок Android по умолчанию, поэтому нажмите «Далее».

Настроить значок запуска

Рисунок 4. Настройка значка панели запуска

Выберите вариант «Пустая активность» и нажмите «Далее».

Пустая активность

Рисунок 5. Создайте действие и выберите его тип

Вы должны указать имя для нового действия и имя для описания макета вашего приложения. Файл макета в формате .xml будет автоматически создан в папке res/layout. Также будет создан XML макет фрагмента, который мы не будем использовать в этом проекте, и вы можете удалить его, если хотите. Затем нажмите Готово.

Рис. 6. Создание нового пустая активность

Рис. 6. Создание нового пустого действия

Здесь вы можете увидеть, какой будет структура проекта после завершения:

Рисунок 7. Дерево проект

Рисунок 7. Дерево проекта

2. Создание макета основного AndroidCursorExample

Мы собираемся создать очень простой макет xml для AndroidCursorExample.class , который состоит только из LinearLayout, содержащего один ListView .

Откройте res/layout/activity_main.xml , перейдите на соответствующую вкладку xml и вставьте следующее:

3. Создание исходного кода основного действия AndroidCursorExample

Откройте файл src/com.javacodegeeks.androidcursorexample/AndroidCursorExample.java и вставьте приведенный ниже код.

Давайте подробно рассмотрим приведенный выше код.

Мы устанавливаем макет activity_main.xml и инициализируем наш основной макет следующим образом:

Здесь мы создаем массив bookTitle, который будет введен в нашу таблицу SQLite и содержит наши данные.

Вот как мы устанавливаем наш ArrayAdapter, который будет заполнять список результатами в нашем макете.

В этом фрагменте кода мы открываем или создаем базу данных sqlite и пытаемся выполнить наш запрос к базе данных. Мы должны вставить каждую книгу из заданного массива в таблицу.

Здесь мы создаем курсор для анализа наших результатов Sqlite, и если наш курсор содержит результаты, мы перемещаем курсор в первую строку и получаем конкретный первый результат. Позже мы добавим эту строку результата в массив, который мы будем отображать в нашем макете. Мы продолжаем итерацию, пока не будут проанализированы все результаты курсора.

4. Манифест Android

AndroidManifest.xml нашего проекта прост и удобен:

5. Сборка, компиляция и запуск

Когда мы собираем, компилируем и запускаем наш проект, основной AndroidCursorExample должен выглядеть так:

Этот интерфейс обеспечивает произвольный доступ для чтения и записи к набору результатов, возвращенному запросом к базе данных.Реализации курсора не требуется синхронизировать, поэтому код, использующий курсор из нескольких потоков, должен выполнять собственную синхронизацию при использовании курсора.

Обзор

Возвращает отсчитываемый от нуля индекс для заданного имени столбца или создает исключение IllegalArgumentException, если столбец не существует.

Возвращает массив строк, содержащий имена всех столбцов результирующего набора в том порядке, в котором они были перечислены в результате.

Зарегистрируйте наблюдателя, который вызывается при изменении содержимого набора данных курсоров, например, когда набор данных изменяется с помощью requery() , deactivate() или close() .

Отменить регистрацию наблюдателя, который ранее был зарегистрирован с этим курсором, с помощью registerContentObserver(ContentObserver) .

Отменить регистрацию наблюдателя, который ранее был зарегистрирован с этим курсором, с помощью registerContentObserver(ContentObserver) .

Общедоступные методы

public abstract void close()

Закрывает курсор, освобождая все его ресурсы и делая его полностью недействительным. В отличие от deactivate() вызов requery() не сделает курсор снова действительным.

public abstract void copyStringToBuffer (int columnIndex, буфер CharArrayBuffer)

Извлекает запрошенный текст столбца и сохраняет его в предоставленном буфере. Если размер буфера недостаточен, будет выделен новый буфер char и назначен CharArrayBuffer.data

Параметры

public abstract void деактивировать ()

Деактивирует курсор, в результате чего все вызовы к нему завершаются неудачно, пока не будет вызвана функция requery(). Неактивные курсоры используют меньше ресурсов, чем активные курсоры. Вызов requery() снова сделает курсор активным.

общедоступный абстрактный байт[] getBlob (int columnIndex)

Возвращает значение запрошенного столбца в виде массива байтов.

Если собственное содержимое этого столбца не является большим двоичным объектом, может возникнуть исключение

Параметры
Возврат

public abstract int getColumnCount()

Возвращает общее количество столбцов

Возврат

public abstract int getColumnIndex (String columnName)

Возвращает отсчитываемый от нуля индекс для заданного имени столбца или -1, если столбец не существует. Если вы ожидаете, что столбец существует, используйте getColumnIndexOrThrow(String) вместо этого, что сделает ошибку более понятной.

Параметры
Возврат
  • отсчитываемый от нуля индекс столбца для заданного имени столбца или -1, если имя столбца не существует.
См. также

public abstract int getColumnIndexOrThrow (String columnName)

Возвращает отсчитываемый от нуля индекс для заданного имени столбца или создает исключение IllegalArgumentException, если столбец не существует. Если вы не уверены, будет ли столбец существовать или нет, используйте getColumnIndex(String) и проверьте наличие -1, что более эффективно, чем перехват исключений.

Параметры
Возврат
  • индекс столбца с отсчетом от нуля для заданного имени столбца
Броски
См. также

общедоступная абстрактная строка getColumnName (int columnIndex)

Возвращает имя столбца по заданному индексу столбца, начинающемуся с нуля.

Параметры
Возврат

общедоступная абстрактная строка[] getColumnNames()

Возвращает массив строк, содержащий имена всех столбцов результирующего набора в том порядке, в котором они были перечислены в результате.

Возврат
  • имена столбцов, возвращенных в этом запросе.

public abstract int getCount()

Возвращает количество строк в курсоре.

Возврат

public abstract double getDouble (int columnIndex)

Возвращает значение запрошенного столбца как двойное.

Если собственное содержимое этого столбца не является числовым, результат будет результатом передачи значения столбца в Double.valueOf(x).

Параметры
Возврат

публичный абстрактный пакет getExtras()

Возвращает набор дополнительных значений. Это необязательный способ для курсоров предоставлять внеполосные метаданные своим пользователям. Одно из применений — отчеты о ходе выполнения сетевых запросов, необходимых для получения данных для курсора.

Эти значения могут изменяться только при вызове requery.

Возврат
  • значения, определяемые курсором, или Bundle.EMTPY, если значений нет. Никогда не нуль.

public abstract float getFloat (int columnIndex)

Возвращает значение запрошенного столбца в виде числа с плавающей запятой.

Если собственное содержимое этого столбца не является числовым, результат будет результатом передачи значения столбца в Float.valueOf(x).

Параметры
Возврат

public abstract int getInt (int columnIndex)

Возвращает значение запрошенного столбца в виде целого числа.

Если собственное содержимое этого столбца не является числовым, результат будет результатом передачи значения столбца в Integer.valueOf(x).

Параметры
Возврат

public abstract long getLong (int columnIndex)

Возвращает значение запрошенного столбца в формате long.

Если собственное содержимое этого столбца не является числовым, результат будет результатом передачи значения столбца в Long.valueOf(x).

Параметры
Возврат

public abstract int getPosition()

Возвращает текущую позицию курсора в наборе строк. Значение отсчитывается от нуля. Когда набор строк возвращается впервые, курсор будет находиться в позиции -1, которая находится перед первой строкой. После возврата последней строки другой вызов next() оставит курсор за последней записью в позиции count().

Возврат

общедоступный абстрактный короткий getShort (int columnIndex)

Возвращает значение запрошенного столбца как короткое.

Если собственное содержимое этого столбца не является числовым, результат будет результатом передачи значения столбца в Short.valueOf(x).

Параметры
Возврат

общедоступная абстрактная строка getString (int columnIndex)

Возвращает значение запрошенного столбца в виде строки.

Если собственное содержимое этого столбца не является текстом, результат будет результатом передачи значения столбца в String.valueOf(x).

Параметры
Возврат

public abstract boolean getWantsAllOnMoveCalls()

onMove() будет вызываться между процессами только в том случае, если этот метод возвращает значение true.

Возврат
  • должны ли все перемещения курсора приводить к вызову onMove().

public abstract boolean isAfterLast()

Возвращает значение, указывающее, указывает ли курсор на позицию после последней строки.

Возврат

public abstract boolean isBeforeFirst()

Возвращает значение, указывающее, указывает ли курсор на позицию перед первой строкой.

Возврат
  • независимо от того, находится ли курсор перед первым результатом.

public abstract boolean isClosed()

вернуть true, если курсор закрыт

Возврат

public abstract boolean isFirst()

Возвращает значение, указывает ли курсор на первую строку.

Возврат
  • указывает ли курсор на первую запись.

public abstract boolean isLast()

Возвращает значение, указывающее, указывает ли курсор на последнюю строку.

Возврат
  • указывает ли курсор на последнюю запись.

public abstract boolean isNull (int columnIndex)

Возвращает значение true, если значение в указанном столбце равно нулю.

Параметры
Возврат

public abstract boolean move (int offset)

Переместить курсор на относительную величину вперед или назад от текущей позиции. Положительные смещения перемещаются вперед, отрицательные смещения перемещаются назад. Если конечная позиция находится за пределами набора результатов, результирующая позиция будет закреплена на -1 или count() в зависимости от того, находится ли значение за пределами начала или конца набора соответственно.

Этот метод возвращает значение true, если запрошенный пункт назначения был достижим, в противном случае он возвращает значение false. Например, если курсор в данный момент находится на второй записи в результирующем наборе и вызывается move(-5), позиция будет закреплена на -1, и будет возвращено значение false.

Читайте также: