Spec-Zone .ru
спецификации, руководства, описания, API
|
public interface CachedRowSet extends RowSet, Joinable
CachedRowSet
должен реализовать. Ссылочная реализация CachedRowSet
интерфейс, обеспеченный Oracle Corporation, является стандартной реализацией. Разработчики могут использовать эту реализацию, как это, они могут расширить это, или они могут хотеть писать свои собственные реализации этого интерфейса.
A CachedRowSet
объект является контейнером для строк данных, которые кэшируют его строки в памяти, которая позволяет работать, всегда не будучи соединенным с его источником данных. Далее, это - компонент JavaBeansTM и с возможностью прокрутки, обновляемо, и сериализуемо. A CachedRowSet
объект обычно содержит строки от набора результатов, но он может также содержать строки от любого файла с табличным форматом, такие как электронная таблица. Ссылочная реализация поддерживает получение данных только от a ResultSet
объект, но разработчики может расшириться SyncProvider
реализации, чтобы обеспечить доступ к другим источникам табличных данных.
Приложение может изменить данные в a CachedRowSet
объект, и те модификации могут тогда быть распространены назад к источнику данных.
A CachedRowSet
объект является разъединенным набором строк, что означает, что он использует соединение со своим источником данных только кратко. Это соединяется с его источником данных, в то время как это читает данные, чтобы заполнить себя со строками и снова в то время как это распространяет, возвращается к его базовому источнику данных. Остальная часть времени, a CachedRowSet
объект разъединяется, включая то, в то время как его данные изменяются. Быть разъединенным делает a RowSet
возразите намного более скудный и поэтому намного легче передать к другому компоненту. Например, разъединенный RowSet
объект может быть сериализирован и передан по проводу к тонкому клиенту, такому как персональный цифровой секретарь (PDA).
CachedRowSet
ОбъектCachedRowSet
предоставленный в ссылочной реализации (RI), чтобы создать значение по умолчанию CachedRowSet
объект. CachedRowSetImpl crs = new CachedRowSetImpl();Это новое
CachedRowSet
объекту установят его свойства в свойства значения по умолчанию a BaseRowSet
объект, и, кроме того, это будет иметь RIOptimisticProvider
возразите как его провайдер синхронизации. RIOptimisticProvider
, один из два SyncProvider
реализации, включенные в RI, являются провайдером значения по умолчанию что SyncFactory
одиночный элемент предоставит, когда никакой провайдер синхронизации не будет определен. A SyncProvider
объект обеспечивает a CachedRowSet
объект с читателем (a RowSetReader
объект) для того, чтобы считать данные из источника данных, чтобы заполнить себя с данными. Читатель может быть реализован, чтобы считать данные из a ResultSet
возразите или от файла с табличным форматом. A SyncProvider
объект также предоставляет писателю (a RowSetWriter
объект) для того, чтобы синхронизировать любые модификации с CachedRowSet
данные объекта, сделанные, в то время как это было разъединено с данными в базовом источнике данных.
Писатель может быть реализован, чтобы осуществить различные степени заботы в проверке конфликты и в уходе от них. (Конфликт происходит, когда значение в источнике данных было изменено после набора строк, заполненного непосредственно с тем значением.) RIOptimisticProvider
реализация предполагает, что будут немногие или никакие конфликты и поэтому не устанавливают блокировок. Это обновляет источник данных со значениями от CachedRowSet
возразите, только если нет никаких конфликтов. Другие писатели могут быть реализованы так, чтобы они всегда записали измененные данные в источник данных, который может быть выполнен или не проверяя на конфликты или, на другом конце спектра, устанавливая блокировки, достаточные, чтобы предотвратить данные в источнике данных от того, чтобы быть измененным. Тем не менее другие реализации писателя могут быть где-нибудь промежуточными.
A CachedRowSet
объект может использовать любого SyncProvider
реализация, которая была зарегистрирована в SyncFactory
одиночный элемент. Приложение может узнать который SyncProvider
реализации были зарегистрированы, вызывая следующую строку кода.
java.util.Enumeration providers = SyncFactory.getRegisteredProviders();
Есть два пути к a CachedRowSet
объект определить, который SyncProvider
объект это будет использовать.
CachedRowSet
возразите crs2, который инициализируется со значениями по умолчанию за исключением того, что SyncProvider
объект является определенным тем. CachedRowSetImpl crs2 = new CachedRowSetImpl( "com.fred.providers.HighAvailabilityProvider");
SyncProvider
использование CachedRowSet
метод setSyncProvider
SyncProvider
объект для crs, CachedRowSet
объект создается с конструктором по умолчанию. crs.setSyncProvider("com.fred.providers.HighAvailabilityProvider");SyncFactory и
SyncProvider
для большего количества деталей.
CachedRowSet
ОбъектCachedRowSet
объект при использовании методов метода get, наследованных от ResultSet
интерфейс. Следующие примеры те, в который crs
a CachedRowSet
возразите, демонстрируйте, как выполнить итерации через строки, получая значения столбцов в каждой строке. Первый пример использует версию методов метода get, которые берут номер столбца; второй пример использует версию, которая берет имя столбца. Номера столбца обычно используются когда RowSet
команда объекта имеет форму SELECT * FROM TABLENAME
; имена столбцов обычно используются, когда команда определяет столбцы по имени. while (crs.next()) { String name = crs.getString(1); int id = crs.getInt(2); Clob comment = crs.getClob(3); short dept = crs.getShort(4); System.out.println(name + " " + id + " " + comment + " " + dept); }
while (crs.next()) { String name = crs.getString("NAME"); int id = crs.getInt("ID"); Clob comment = crs.getClob("COM"); short dept = crs.getShort("DEPT"); System.out.println(name + " " + id + " " + comment + " " + dept); }
RowSetMetaData
CachedRowSet
объект, вызывая ResultSetMetaData
и RowSetMetaData
методы на a RowSetMetaData
объект. Следующий фрагмент кода, в котором crs является a CachedRowSet
возразите, иллюстрирует процесс. Первая строка создает a RowSetMetaData
объект с информацией о столбцах в crs. Метод getMetaData
, наследованный от ResultSet
интерфейс, a возвратов ResultSetMetaData
объект, который бросается к a RowSetMetaData
объект прежде, чем быть присвоенным переменной rsmd. Вторая строка узнает, сколько столбцов jrs имеет, и третья строка получает тип JDBC значений, сохраненных во втором столбце jrs
. RowSetMetaData rsmd = (RowSetMetaData)crs.getMetaData(); int count = rsmd.getColumnCount(); int type = rsmd.getColumnType(2);
RowSetMetaData
интерфейс отличается от ResultSetMetaData
интерфейс двумя способами. setter
методы: A RowSet
возразите использует эти методы внутренне, когда это заполняется с данными от различного ResultSet
объект.
getter
методы: Некоторые ResultSetMetaData
методы, чтобы не примениться к a RowSet
объект. Например, получение методов, перезаписываемо ли значение столбца или только для чтения, не применяется потому что все a RowSet
столбцы объекта будут перезаписываемы или только для чтения, в зависимости от того, обновляем ли набор строк или нет. RowSetMetaData
объект, реализации должны переопределить getMetaData()
метод, определенный в java.sql.ResultSet
и возвратите a RowSetMetaData
объект. CachedRowSet
ОбъектCachedRowSet
объект подобен обновлению a ResultSet
объект, но потому что набор строк не соединяется с его источником данных, в то время как это обновляется, это должно сделать дополнительный шаг, чтобы вызвать изменения в его базовом источнике данных. После вызова метода updateRow
или insertRow
, a CachedRowSet
объект должен также вызвать метод acceptChanges
иметь обновления, записанные источнику данных. Следующий пример, в котором курсор находится на строке в CachedRowSet
возразите crs, показывает код, требуемый обновить два значения столбцов в текущей строке и также обновить RowSet
базовый источник данных объекта. crs.updateShort(3, 58); crs.updateInt(4, 150000); crs.updateRow(); crs.acceptChanges();
Следующий пример демонстрирует, как перемещаться в строку вставки, создавая новую строку на строке вставки, вставляя это в набор строк, и затем вызывая метод acceptChanges
добавить новую строку к базовому источнику данных. Отметьте, что как с методами метода get, updater методы могут взять или столбец, индексируют или имя столбца, чтобы назвать столбец действовавшим.
crs.moveToInsertRow(); crs.updateString("Name", "Shakespeare"); crs.updateInt("ID", 10098347); crs.updateShort("Age", 58); crs.updateInt("Sal", 150000); crs.insertRow(); crs.moveToCurrentRow(); crs.acceptChanges();
ОТМЕТЬТЕ: Где insertRow()
метод вставляет содержание a CachedRowSet
строка вставки объекта определяется с помощью реализации. Ссылочная реализация для CachedRowSet
интерфейс сразу вставляет новую строку после текущей строки, но это могло быть реализовано, чтобы вставить новые строки в любое число других мест.
Другая вещь отметить об этих примерах состоит в том, как они используют метод acceptChanges
. Именно этот метод распространяет изменения в a CachedRowSet
возразите назад против базового источника данных, обращаясь RowSet
писатель объекта внутренне, чтобы записать изменения в источник данных. Чтобы сделать это, писатель должен подвергнуться расходу установления соединения с тем источником данных. Предшествование двум фрагментам кода вызывает метод acceptChanges
сразу после вызова updateRow
или insertRow
. Однако, когда есть многократные изменяемые строки, более эффективно вызвать acceptChanges
после всех звонков updateRow
и insertRow
были сделаны. Если acceptChanges
вызывается только однажды, только одно соединение должно быть установлено.
acceptChanges
выполняется, CachedRowSet
писатель объекта, a RowSetWriterImpl
возразите, вызывается негласно, чтобы записать изменения, произведенные в наборе строк к базовому источнику данных. Писатель реализуется, чтобы сделать соединение с источником данных и обновления записи к нему. Писатель делается доступным посредством реализации SyncProvider
интерфейс, как обсуждено в разделе 1, "Создавая a CachedRowSet
Объект." Ссылочный провайдер реализации значения по умолчанию, RIOptimisticProvider
, реализовывали его писателя, чтобы использовать механизм управления оптимистичного параллелизма. Таким образом, это поддерживает, не привязывает базовую базу данных, в то время как набор строк разъединяется от базы данных и просто проверяет, чтобы видеть, есть ли какие-либо конфликты перед писанием данных к источнику данных. Если есть какие-либо конфликты, это ничего не пишет в источник данных.
Услуга читателя/писателя, предоставленная SyncProvider
class является сменным, учитывая настройку поиска данных и обновления. Если различный механизм управления совместным выполнением требуется, различная реализация SyncProvider
может быть включен в использовании метода setSyncProvider
.
Чтобы использовать подпрограмму управления оптимистичным параллелизмом, RIOptismisticProvider
поддерживает и его текущую стоимость и его исходное значение (значение, у него было сразу предшествование текущей стоимости). Отметьте это, если никакие изменения не были произведены в данных в a RowSet
объект, его текущая стоимость и его исходные значения являются тем же самым, оба являющийся значениями с который RowSet
объект был первоначально заполнен. Однако, однажды любые значения в RowSet
объект был изменен, текущая стоимость и исходные значения будут отличаться, хотя на данном этапе, исходные значения являются все еще начальными значениями. С любыми последующими изменениями к данным в a RowSet
объект, его исходные значения и текущая стоимость будут все еще отличаться, но его исходные значения будут значениями, которые были ранее текущей стоимостью.
Отслеживание исходных значений позволяет писателю сравниваться RowSet
исходное значение объекта со значением в базе данных. Если значения в базе данных отличаются от RowSet
исходные значения объекта, что означает, что значения в базе данных были изменены, есть конфликт. Проверяет ли писатель на конфликты, какой степень проверки это делает, и как это обрабатывает конфликты, все зависят от того, как это реализуется.
BaseRowSet
class. Слушатель для a CachedRowSet
объект является компонентом, который хочет быть уведомленным всякий раз, когда есть изменение в наборе строк. Например, если a CachedRowSet
объект содержит результаты запроса, и те результаты выводятся на экран в, скажем, таблице и гистограмме, таблица и гистограмма могли быть зарегистрированы как слушатели с набором строк так, чтобы они могли обновить себя, чтобы отразить изменения. Чтобы стать слушателями, таблица и классы гистограммы должны реализовать RowSetListener
интерфейс. Затем они могут быть добавлены к CachedRowSet
список объекта слушателей, как иллюстрируется в следующих строках кода. crs.addRowSetListener(table); crs.addRowSetListener(barGraph);Каждый
CachedRowSet
метод, который перемещает курсор или изменяет данные также, уведомляет зарегистрированных слушателей изменений, таким образом, table
и barGraph
будет уведомлен, когда есть изменение в crs
.
CachedRowSet
объект состоит в том, чтобы передать данные между различными компонентами приложения. Поскольку это сериализуемо, a CachedRowSet
объект может использоваться, например, чтобы отправить результат запроса, выполняемого предприятием компонент JavaBeans, работающий в серверной среде по сети клиенту, работающему в веб-браузере. В то время как a CachedRowSet
объект разъединяется, это может быть намного более скудно чем a ResultSet
объект с теми же самыми данными. В результате это может быть особенно подходящим для того, чтобы отправить данные тонкому клиенту, такому как PDA, где было бы неуместно использовать драйвер JDBC из-за ограничений ресурса или соображений безопасности. Таким образом, a CachedRowSet
объект обеспечивает средство "вложить строки" без потребности реализовать полный API JDBC.
CachedRowSet
объекты состоят в том, чтобы обеспечить прокрутку и обновление для ResultSet
объекты, которые не обеспечивают эти возможности непосредственно. Другими словами, a CachedRowSet
объект может использоваться, чтобы увеличить возможности поддерживающего технологию драйвера JDBC (после этого названный "драйвером JDBC"), когда DBMS не обеспечивает полную поддержку прокрутки и обновления. Достигнуть эффекта создания non-scrollble и только для чтения ResultSet
возразите с возможностью прокрутки и обновляемый, программист просто должен создать a CachedRowSet
объект заполняется с этим ResultSet
данные объекта. Это демонстрируется в следующем фрагменте кода, где stmt
a Statement
объект. ResultSet rs = stmt.executeQuery("SELECT * FROM EMPLOYEES"); CachedRowSetImpl crs = new CachedRowSetImpl(); crs.populate(rs);
Объект crs
теперь содержит данные от таблицы EMPLOYEES
, так же, как объект rs
делает. Различие то, что курсор для crs
может быть продвинут, назад, или к определенной строке даже если курсор для rs
может переместиться только вперед. Кроме того, crs
обновляемо даже если rs
то, не потому что по умолчанию, a CachedRowSet
объект и с возможностью прокрутки и обновляем.
В сводке, a CachedRowSet
объект может думаться как просто разъединенный набор строк, которые кэшируются за пределами источника данных. Будучи тонким и сериализуемым, это может легко быть отправлено через провод, и это хорошо подходит для передающих данных к тонкому клиенту. Однако, a CachedRowSet
у объекта действительно есть ограничение: Это ограничивается в размере объемом данных, который это может сохранить в памяти когда-то.
CachedRowSet
class - то, что это позволяет получить и хранить данные из источников кроме реляционной базы данных. Читатель для набора строк может быть реализован, чтобы считать и заполнить его набор строк с данными из любого источника табличных данных, включая электронную таблицу или плоский файл. Поскольку оба a CachedRowSet
возразите и его метаданные могут быть созданы с нуля, компонент, который действует, поскольку фабрика для наборов строк может использовать эту возможность создать набор строк, содержащий данные от источников данных не-SQL. Однако, это ожидается это большую часть времени, CachedRowSet
объекты будут содержать данные, которые были выбраны от базы данных SQL, используя API JDBC.
ResultSet
возразите должен установить свойства, которые требуются для того, чтобы сделать соединение с базой данных. Если набор строк использует DriverManager
средство, чтобы сделать соединение, это должно установить свойство для URL JDBC, который идентифицирует соответствующий драйвер, и это должно установить свойства, которые дают имя пользователя и пароль. Если с другой стороны набор строк использует a DataSource
объект сделать соединение, которое является привилегированным методом, он не должен установить свойство для URL JDBC. Вместо этого это должно установить свойства для логического имени источника данных для имени пользователя, и для пароля. ОТМЕТЬТЕ: Чтобы использовать a DataSource
объект для того, чтобы сделать соединение, DataSource
объект, должно быть, был зарегистрирован в службе именования, которая использует Именование Java и Каталог InterfaceTM (JNDI) API. Эта регистрация обычно делается человеком, действующим от лица системного администратора.
Чтобы быть в состоянии заполнить себя с данными от базы данных, набор строк должен установить свойство команды. Это свойство является запросом, который является a PreparedStatement
объект, который позволяет запросу иметь заполнителей параметра, которые устанавливаются во время выполнения, в противоположность времени проектирования. Чтобы установить эти параметры заполнителя со значениями, набор строк обеспечивает методы метода set для того, чтобы они установили значения каждого типа данных, подобного методам метода set, обеспеченным PreparedStatement
интерфейс.
Следующий фрагмент кода иллюстрирует как CachedRowSet
объект crs
мог бы иметь его набор свойств команды. Отметьте, что, если бы инструмент используется, чтобы установить свойства, это - код, который использовал бы инструмент.
crs.setCommand("SELECT FIRST_NAME, LAST_NAME, ADDRESS FROM CUSTOMERS " + "WHERE CREDIT_LIMIT > ? AND REGION = ?");
Значения, которые будут использоваться, чтобы установить параметры заполнителя команды, содержатся в RowSet
объект params
поле, которое является a Vector
объект. CachedRowSet
class обеспечивает ряд методов метода set для того, чтобы он установил элементы в params
поле. Следующий фрагмент кода демонстрирует, как устанавливать эти два параметров в запросе от предыдущего примера.
crs.setInt(1, 5000); crs.setString(2, "West");
params
поле теперь содержит два элемента, каждый из которых является массивом два элемента долго. Первый элемент является числом параметра; вторым является значение, которое будет установлено. В этом случае, первый элемент params
1
, 5000
, и второй элемент 2
, "West"
. Когда приложение вызывает метод execute
, это поочередно обратится к этому RowSet
читатель объекта, который поочередно вызовет readData
метод. Как часть его реализации, readData
вложит значения params
и используйте их, чтобы установить параметры заполнителя команды. Следующий фрагмент кода дает общее представление о том, как читатель делает это после получения Connection
объект con
.
PreparedStatement pstmt = con.prepareStatement(crs.getCommand()); reader.decodeParams(); // decodeParams figures out which setter methods to use and does something // like the following: // for (i = 0; i < params.length; i++) { // pstmt.setObject(i + 1, params[i]); // }
At this point, the command for crs
is the query "SELECT
FIRST_NAME, LAST_NAME, ADDRESS FROM CUSTOMERS WHERE CREDIT_LIMIT > 5000
AND REGION = "West"
. After the readData
method executes
this command with the following line of code, it will have the data from
rs
with which to populate crs
.
ResultSet rs = pstmt.executeQuery();
The preceding code fragments give an idea of what goes on behind the
scenes; they would not appear in an application, which would not invoke
methods like readData
and decodeParams
.
In contrast, the following code fragment shows what an application might do.
It sets the rowset's command, sets the command's parameters, and executes
the command. Simply by calling the execute
method,
crs
populates itself with the requested data from the
table CUSTOMERS
.
crs.setCommand("SELECT FIRST_NAME, LAST_NAME, ADDRESS FROM CUSTOMERS" + "WHERE CREDIT_LIMIT > ? AND REGION = ?"); crs.setInt(1, 5000); crs.setString(2, "West"); crs.execute();
CachedRowSet
object stores data in memory,
the amount of data that it can contain at any one
time is determined by the amount of memory available. To get around this limitation,
a CachedRowSet
object can retrieve data from a ResultSet
object in chunks of data, called pages. To take advantage of this mechanism,
an application sets the number of rows to be included in a page using the method
setPageSize
. In other words, if the page size is set to five, a chunk
of five rows of
data will be fetched from the data source at one time. An application can also
optionally set the maximum number of rows that may be fetched at one time. If the
maximum number of rows is set to zero, or no maximum number of rows is set, there is
no limit to the number of rows that may be fetched at a time.
After properties have been set,
the CachedRowSet
object must be populated with data
using either the method populate
or the method execute
.
The following lines of code demonstrate using the method populate
.
Note that this version of the method takes two parameters, a ResultSet
handle and the row in the ResultSet
object from which to start
retrieving rows.
CachedRowSet crs = new CachedRowSetImpl(); crs.setMaxRows(20); crs.setPageSize(4); crs.populate(rsHandle, 10);When this code runs, crs will be populated with four rows from rsHandle starting with the tenth row.
The next code fragment shows populating a CachedRowSet
object using the
method execute
, which may or may not take a Connection
object as a parameter. This code passes execute
the Connection
object conHandle.
Note that there are two differences between the following code
fragment and the previous one. First, the method setMaxRows
is not
called, so there is no limit set for the number of rows that crs may contain.
(Remember that crs always has the overriding limit of how much data it can
store in memory.) The second difference is that the you cannot pass the method
execute
the number of the row in the ResultSet
object
from which to start retrieving rows. This method always starts with the first row.
CachedRowSet crs = new CachedRowSetImpl(); crs.setPageSize(5); crs.execute(conHandle);After this code has run, crs will contain five rows of data from the
ResultSet
object produced by the command for crs. The writer
for crs will use conHandle to connect to the data source and
execute the command for crs. An application is then able to operate on the
data in crs in the same way that it would operate on data in any other
CachedRowSet
object.
To access the next page (chunk of data), an application calls the method
nextPage
. This method creates a new CachedRowSet
object
and fills it with the next page of data. For example, assume that the
CachedRowSet
object's command returns a ResultSet
object
rs with 1000 rows of data. If the page size has been set to 100, the first
call to the method nextPage
will create a CachedRowSet
object
containing the first 100 rows of rs. After doing what it needs to do with the
data in these first 100 rows, the application can again call the method
nextPage
to create another CachedRowSet
object
with the second 100 rows from rs. The data from the first CachedRowSet
object will no longer be in memory because it is replaced with the data from the
second CachedRowSet
object. After the tenth call to the method nextPage
,
the tenth CachedRowSet
object will contain the last 100 rows of data from
rs, which are stored in memory. At any given time, the data from only one
CachedRowSet
object is stored in memory.
The method nextPage
returns true
as long as the current
page is not the last page of rows and false
when there are no more pages.
It can therefore be used in a while
loop to retrieve all of the pages,
as is demonstrated in the following lines of code.
CachedRowSet crs = CachedRowSetImpl(); crs.setPageSize(100); crs.execute(conHandle); while(crs.nextPage()) { while(crs.next()) { . . . // operate on chunks (of 100 rows each) in crs, // row by row } }After this code fragment has been run, the application will have traversed all 1000 rows, but it will have had no more than 100 rows in memory at a time.
The CachedRowSet
interface also defines the method previousPage
.
Just as the method nextPage
is analogous to the ResultSet
method next
, the method previousPage
is analogous to
the ResultSet
method previous
. Similar to the method
nextPage
, previousPage
creates a CachedRowSet
object containing the number of rows set as the page size. So, for instance, the
method previousPage
could be used in a while
loop at
the end of the preceding code fragment to navigate back through the pages from the last
page to the first page.
The method previousPage
is also similar to nextPage
in that it can be used in a while
loop, except that it returns true
as long as there is another page
preceding it and false
when there are no more pages ahead of it.
By positioning the cursor after the last row for each page,
as is done in the following code fragment, the method previous
navigates from the last row to the first row in each page.
The code could also have left the cursor before the first row on each page and then
used the method next
in a while
loop to navigate each page
from the first row to the last row.
The following code fragment assumes a continuation from the previous code fragment,
meaning that the cursor for the tenth CachedRowSet
object is on the
last row. The code moves the cursor to after the last row so that the first
call to the method previous
will put the cursor back on the last row.
After going through all of the rows in the last page (the CachedRowSet
object crs), the code then enters
the while
loop to get to the ninth page, go through the rows backwards,
go to the eighth page, go through the rows backwards, and so on to the first row
of the first page.
crs.afterLast(); while(crs.previous()) { . . . // navigate through the rows, last to first { while(crs.previousPage()) { crs.afterLast(); while(crs.previous()) { . . . // go from the last row to the first row of each page } }
Modifier and Type | Field and Description |
---|---|
static boolean |
COMMIT_ON_ACCEPT_CHANGES
Deprecated.
Because this field is final (it is part of an interface),
its value cannot be changed.
|
CLOSE_CURSORS_AT_COMMIT, CONCUR_READ_ONLY, CONCUR_UPDATABLE, FETCH_FORWARD, FETCH_REVERSE, FETCH_UNKNOWN, HOLD_CURSORS_OVER_COMMIT, TYPE_FORWARD_ONLY, TYPE_SCROLL_INSENSITIVE, TYPE_SCROLL_SENSITIVE
Modifier and Type | Method and Description |
---|---|
void |
acceptChanges()
Propagates row update, insert and delete changes made to this
CachedRowSet object to the underlying data source. |
void |
acceptChanges(Connection con)
Propagates all row update, insert and delete changes to the
data source backing this
CachedRowSet object
using the specified Connection object to establish a
connection to the data source. |
boolean |
columnUpdated(int idx)
Indicates whether the designated column in the current row of this
CachedRowSet object has been updated. |
boolean |
columnUpdated(String columnName)
Indicates whether the designated column in the current row of this
CachedRowSet object has been updated. |
void |
commit()
Each
CachedRowSet object's SyncProvider contains
a Connection object from the ResultSet or JDBC
properties passed to it's constructors. |
CachedRowSet |
createCopy()
Creates a
RowSet object that is a deep copy of the data in
this CachedRowSet object. |
CachedRowSet |
createCopyNoConstraints()
Creates a
CachedRowSet object that is a deep copy of
this CachedRowSet object's data but is independent of it. |
CachedRowSet |
createCopySchema()
Creates a
CachedRowSet object that is an empty copy of this
CachedRowSet object. |
RowSet |
createShared()
Returns a new
RowSet object backed by the same data as
that of this CachedRowSet object. |
void |
execute(Connection conn)
Populates this
CachedRowSet object with data, using the
given connection to produce the result set from which the data will be read. |
int[] |
getKeyColumns()
Returns an array containing one or more column numbers indicating the columns
that form a key that uniquely
identifies a row in this
CachedRowSet object. |
ResultSet |
getOriginal()
Returns a
ResultSet object containing the original value of this
CachedRowSet object. |
ResultSet |
getOriginalRow()
Returns a
ResultSet object containing the original value for the
current row only of this CachedRowSet object. |
int |
getPageSize()
Returns the page-size for the
CachedRowSet object |
RowSetWarning |
getRowSetWarnings()
Retrieves the first warning reported by calls on this
RowSet object. |
boolean |
getShowDeleted()
Retrieves a
boolean indicating whether rows marked
for deletion appear in the set of current rows. |
SyncProvider |
getSyncProvider()
Retrieves the
SyncProvider implementation for this
CachedRowSet object. |
Строка |
getTableName()
Returns an identifier for the object (table) that was used to
create this
CachedRowSet object. |
boolean |
nextPage()
Increments the current page of the
CachedRowSet . |
void |
populate(ResultSet data)
Populates this
CachedRowSet object with data from
the given ResultSet object. |
void |
populate(ResultSet rs,
int startRow)
Populates this
CachedRowSet object with data from
the given ResultSet object. |
boolean |
previousPage()
Decrements the current page of the
CachedRowSet . |
void |
release()
Releases the current contents of this
CachedRowSet
object and sends a rowSetChanged event to all
registered listeners. |
void |
restoreOriginal()
Restores this
CachedRowSet object to its original
value, that is, its value before the last set of changes. |
void |
rollback()
Each
CachedRowSet object's SyncProvider contains
a Connection object from the original ResultSet
or JDBC properties passed to it. |
void |
rollback(Savepoint s)
Each
CachedRowSet object's SyncProvider contains
a Connection object from the original ResultSet
or JDBC properties passed to it. |
void |
rowSetPopulated(RowSetEvent event,
int numRows)
Notifies registered listeners that a RowSet object in the given RowSetEvent
object has populated a number of additional rows.
|
void |
setKeyColumns(int[] keys)
Sets this
CachedRowSet object's keyCols
field with the given array of column numbers, which forms a key
for uniquely identifying a row in this CachedRowSet object. |
void |
setMetaData(RowSetMetaData md)
Sets the metadata for this
CachedRowSet object with
the given RowSetMetaData object. |
void |
setOriginalRow()
Sets the current row in this
CachedRowSet object as the original
row. |
void |
setPageSize(int size)
Sets the
CachedRowSet object's page-size. |
void |
setShowDeleted(boolean b)
Sets the property
showDeleted to the given
boolean value, which determines whether
rows marked for deletion appear in the set of current rows. |
void |
setSyncProvider(String provider)
Sets the
SyncProvider objec for this CachedRowSet
object to the one specified. |
void |
setTableName(String tabName)
Sets the identifier for the table from which this
CachedRowSet
object was derived to the given table name. |
int |
size()
Returns the number of rows in this
CachedRowSet
object. |
Collection<?> |
toCollection()
Converts this
CachedRowSet object to a Collection
object that contains all of this CachedRowSet object's data. |
Collection<?> |
toCollection(int column)
Converts the designated column in this
CachedRowSet object
to a Collection object. |
Collection<?> |
toCollection(String column)
Converts the designated column in this
CachedRowSet object
to a Collection object. |
void |
undoDelete()
Cancels the deletion of the current row and notifies listeners that
a row has changed.
|
void |
undoInsert()
Immediately removes the current row from this
CachedRowSet
object if the row has been inserted, and also notifies listeners that a
row has changed. |
void |
undoUpdate()
Immediately reverses the last update operation if the
row has been modified.
|
addRowSetListener, clearParameters, execute, getCommand, getDataSourceName, getEscapeProcessing, getMaxFieldSize, getMaxRows, getPassword, getQueryTimeout, getTransactionIsolation, getTypeMap, getUrl, getUsername, isReadOnly, removeRowSetListener, setArray, setAsciiStream, setAsciiStream, setAsciiStream, setAsciiStream, setBigDecimal, setBigDecimal, setBinaryStream, setBinaryStream, setBinaryStream, setBinaryStream, setBlob, setBlob, setBlob, setBlob, setBlob, setBlob, setBoolean, setBoolean, setByte, setByte, setBytes, setBytes, setCharacterStream, setCharacterStream, setCharacterStream, setCharacterStream, setClob, setClob, setClob, setClob, setClob, setClob, setCommand, setConcurrency, setDataSourceName, setDate, setDate, setDate, setDate, setDouble, setDouble, setEscapeProcessing, setFloat, setFloat, setInt, setInt, setLong, setLong, setMaxFieldSize, setMaxRows, setNCharacterStream, setNCharacterStream, setNCharacterStream, setNCharacterStream, setNClob, setNClob, setNClob, setNClob, setNClob, setNClob, setNString, setNString, setNull, setNull, setNull, setNull, setObject, setObject, setObject, setObject, setObject, setObject, setPassword, setQueryTimeout, setReadOnly, setRef, setRowId, setRowId, setShort, setShort, setSQLXML, setSQLXML, setString, setString, setTime, setTime, setTime, setTime, setTimestamp, setTimestamp, setTimestamp, setTimestamp, setTransactionIsolation, setType, setTypeMap, setURL, setUrl, setUsername
absolute, afterLast, beforeFirst, cancelRowUpdates, clearWarnings, close, deleteRow, findColumn, first, getArray, getArray, getAsciiStream, getAsciiStream, getBigDecimal, getBigDecimal, getBigDecimal, getBigDecimal, getBinaryStream, getBinaryStream, getBlob, getBlob, getBoolean, getBoolean, getByte, getByte, getBytes, getBytes, getCharacterStream, getCharacterStream, getClob, getClob, getConcurrency, getCursorName, getDate, getDate, getDate, getDate, getDouble, getDouble, getFetchDirection, getFetchSize, getFloat, getFloat, getHoldability, getInt, getInt, getLong, getLong, getMetaData, getNCharacterStream, getNCharacterStream, getNClob, getNClob, getNString, getNString, getObject, getObject, getObject, getObject, getObject, getObject, getRef, getRef, getRow, getRowId, getRowId, getShort, getShort, getSQLXML, getSQLXML, getStatement, getString, getString, getTime, getTime, getTime, getTime, getTimestamp, getTimestamp, getTimestamp, getTimestamp, getType, getUnicodeStream, getUnicodeStream, getURL, getURL, getWarnings, insertRow, isAfterLast, isBeforeFirst, isClosed, isFirst, isLast, last, moveToCurrentRow, moveToInsertRow, next, previous, refreshRow, relative, rowDeleted, rowInserted, rowUpdated, setFetchDirection, setFetchSize, updateArray, updateArray, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateBigDecimal, updateBigDecimal, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBlob, updateBlob, updateBlob, updateBlob, updateBlob, updateBlob, updateBoolean, updateBoolean, updateByte, updateByte, updateBytes, updateBytes, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateClob, updateClob, updateClob, updateClob, updateClob, updateClob, updateDate, updateDate, updateDouble, updateDouble, updateFloat, updateFloat, updateInt, updateInt, updateLong, updateLong, updateNCharacterStream, updateNCharacterStream, updateNCharacterStream, updateNCharacterStream, updateNClob, updateNClob, updateNClob, updateNClob, updateNClob, updateNClob, updateNString, updateNString, updateNull, updateNull, updateObject, updateObject, updateObject, updateObject, updateObject, updateObject, updateObject, updateObject, updateRef, updateRef, updateRow, updateRowId, updateRowId, updateShort, updateShort, updateSQLXML, updateSQLXML, updateString, updateString, updateTime, updateTime, updateTimestamp, updateTimestamp, wasNull
isWrapperFor, unwrap
getMatchColumnIndexes, getMatchColumnNames, setMatchColumn, setMatchColumn, setMatchColumn, setMatchColumn, unsetMatchColumn, unsetMatchColumn, unsetMatchColumn, unsetMatchColumn
@Deprecated static final boolean COMMIT_ON_ACCEPT_CHANGES
CachedRowSet
object's SyncProvider
to commit the changes when acceptChanges()
is called. If
set to false, the changes will not be committed until one of the
CachedRowSet
interface transaction methods is called.commit()
,
rollback()
,
Constant Field Valuesvoid populate(ResultSet data) throws SQLException
CachedRowSet
object with data from
the given ResultSet
object.
This method can be used as an alternative to the execute
method when an
application has a connection to an open ResultSet
object.
Using the method populate
can be more efficient than using
the version of the execute
method that takes no parameters
because it does not open a new connection and re-execute this
CachedRowSet
object's command. Using the populate
method is more a matter of convenience when compared to using the version
of execute
that takes a ResultSet
object.
data
- the ResultSet
object containing the data
to be read into this CachedRowSet
objectSQLException
- if a null ResultSet
object is supplied
or this CachedRowSet
object cannot
retrieve the associated ResultSetMetaData
objectexecute(java.sql.Connection)
,
ResultSet
,
ResultSetMetaData
void execute(Connection conn) throws SQLException
CachedRowSet
object with data, using the
given connection to produce the result set from which the data will be read.
This method should close any database connections that it creates to
ensure that this CachedRowSet
object is disconnected except when
it is reading data from its data source or writing data to its data source.
The reader for this CachedRowSet
object
will use conn to establish a connection to the data source
so that it can execute the rowset's command and read data from the
the resulting ResultSet
object into this
CachedRowSet
object. This method also closes conn
after it has populated this CachedRowSet
object.
If this method is called when an implementation has already been
populated, the contents and the metadata are (re)set. Also, if this method is
called before the method acceptChanges
has been called
to commit outstanding updates, those updates are lost.
conn
- a standard JDBC Connection
object with valid
propertiesSQLException
- if an invalid Connection
object is supplied
or an error occurs in establishing the connection to the
data sourcepopulate(java.sql.ResultSet)
,
Connection
void acceptChanges() throws SyncProviderException
CachedRowSet
object to the underlying data source.
This method calls on this CachedRowSet
object's writer
to do the work behind the scenes.
Standard CachedRowSet
implementations should use the
SyncFactory
singleton
to obtain a SyncProvider
instance providing a
RowSetWriter
object (writer). The writer will attempt
to propagate changes made in this CachedRowSet
object
back to the data source.
When the method acceptChanges
executes successfully, in
addition to writing changes to the data source, it
makes the values in the current row be the values in the original row.
Depending on the synchronization level of the SyncProvider
implementation being used, the writer will compare the original values
with those in the data source to check for conflicts. When there is a conflict,
the RIOptimisticProvider
implementation, for example, throws a
SyncProviderException
and does not write anything to the
data source.
An application may choose to catch the SyncProviderException
object and retrieve the SyncResolver
object it contains.
The SyncResolver
object lists the conflicts row by row and
sets a lock on the data source to avoid further conflicts while the
current conflicts are being resolved.
Further, for each conflict, it provides methods for examining the conflict
and setting the value that should be persisted in the data source.
After all conflicts have been resolved, an application must call the
acceptChanges
method again to write resolved values to the
data source. If all of the values in the data source are already the
values to be persisted, the method acceptChanges
does nothing.
Some provider implementations may use locks to ensure that there are no
conflicts. In such cases, it is guaranteed that the writer will succeed in
writing changes to the data source when the method acceptChanges
is called. This method may be called immediately after the methods
updateRow
, insertRow
, or deleteRow
have been called, but it is more efficient to call it only once after
all changes have been made so that only one connection needs to be
established.
Note: The acceptChanges()
method will determine if the
COMMIT_ON_ACCEPT_CHANGES
is set to true or not. If it is set
to true, all updates in the synchronization are committed to the data
source. Otherwise, the application must explicity call the
commit()
or rollback()
methods as appropriate.
SQLException
- if the cursor is on the insert rowSyncProviderException
- if the underlying
synchronization provider's writer fails to write the updates
back to the data sourceacceptChanges(java.sql.Connection)
,
RowSetWriter
,
SyncFactory
,
SyncProvider
,
SyncProviderException
,
SyncResolver
void acceptChanges(Connection con) throws SyncProviderException
CachedRowSet
object
using the specified Connection
object to establish a
connection to the data source.
The other version of the acceptChanges
method is not passed
a connection because it uses
the Connection
object already defined within the RowSet
object, which is the connection used for populating it initially.
This form of the method acceptChanges
is similar to the
form that takes no arguments; however, unlike the other form, this form
can be used only when the underlying data source is a JDBC data source.
The updated Connection
properties must be used by the
SyncProvider
to reset the RowSetWriter
configuration to ensure that the contents of the CachedRowSet
object are synchronized correctly.
When the method acceptChanges
executes successfully, in
addition to writing changes to the data source, it
makes the values in the current row be the values in the original row.
Depending on the synchronization level of the SyncProvider
implementation being used, the writer will compare the original values
with those in the data source to check for conflicts. When there is a conflict,
the RIOptimisticProvider
implementation, for example, throws a
SyncProviderException
and does not write anything to the
data source.
An application may choose to catch the SyncProviderException
object and retrieve the SyncResolver
object it contains.
The SyncResolver
object lists the conflicts row by row and
sets a lock on the data source to avoid further conflicts while the
current conflicts are being resolved.
Further, for each conflict, it provides methods for examining the conflict
and setting the value that should be persisted in the data source.
After all conflicts have been resolved, an application must call the
acceptChanges
method again to write resolved values to the
data source. If all of the values in the data source are already the
values to be persisted, the method acceptChanges
does nothing.
Some provider implementations may use locks to ensure that there are no
conflicts. In such cases, it is guaranteed that the writer will succeed in
writing changes to the data source when the method acceptChanges
is called. This method may be called immediately after the methods
updateRow
, insertRow
, or deleteRow
have been called, but it is more efficient to call it only once after
all changes have been made so that only one connection needs to be
established.
Note: The acceptChanges()
method will determine if the
COMMIT_ON_ACCEPT_CHANGES
is set to true or not. If it is set
to true, all updates in the synchronization are committed to the data
source. Otherwise, the application must explicity call the
commit
or rollback
methods as appropriate.
con
- a standard JDBC Connection
objectSQLException
- if the cursor is on the insert rowSyncProviderException
- if the underlying
synchronization provider's writer fails to write the updates
back to the data sourceacceptChanges()
,
RowSetWriter
,
SyncFactory
,
SyncProvider
,
SyncProviderException
,
SyncResolver
void restoreOriginal() throws SQLException
CachedRowSet
object to its original
value, that is, its value before the last set of changes. If there
have been no changes to the rowset or only one set of changes,
the original value is the value with which this CachedRowSet
object
was populated; otherwise, the original value is
the value it had immediately before its current value.
When this method is called, a CachedRowSet
implementation
must ensure that all updates, inserts, and deletes to the current
rowset instance are replaced by the previous values. In addition,
the cursor should be
reset to the first row and a rowSetChanged
event
should be fired to notify all registered listeners.
SQLException
- if an error occurs rolling back the current value of
this CachedRowSet
object to its previous valueRowSetListener.rowSetChanged(javax.sql.RowSetEvent)
void release() throws SQLException
CachedRowSet
object and sends a rowSetChanged
event to all
registered listeners. Any outstanding updates are discarded and
the rowset contains no rows after this method is called. There
are no interactions with the underlying data source, and any rowset
content, metadata, and content updates should be non-recoverable.
This CachedRowSet
object should lock until its contents and
associated updates are fully cleared, thus preventing 'dirty' reads by
other components that hold a reference to this RowSet
object.
In addition, the contents cannot be released
until all all components reading this CachedRowSet
object
have completed their reads. This CachedRowSet
object
should be returned to normal behavior after firing the
rowSetChanged
event.
The metadata, including JDBC properties and Synchronization SPI
properties, are maintained for future use. It is important that
properties such as the command
property be
relevant to the originating data source from which this CachedRowSet
object was originally established.
This method empties a rowset, as opposed to the close
method,
which marks the entire rowset as recoverable to allow the garbage collector
the rowset's Java VM resources.
SQLException
- if an error occurs flushing the contents of this
CachedRowSet
objectRowSetListener.rowSetChanged(javax.sql.RowSetEvent)
,
ResultSet.close()
void undoDelete() throws SQLException
In addition, multiple cancellations of row deletions can be made by adjusting the position of the cursor using any of the cursor position control methods such as:
CachedRowSet.absolute
CachedRowSet.first
CachedRowSet.last
SQLException
- if (1) the current row has not been deleted or
(2) the cursor is on the insert row, before the first row, or
after the last rowundoInsert()
,
ResultSet.cancelRowUpdates()
void undoInsert() throws SQLException
CachedRowSet
object if the row has been inserted, and also notifies listeners that a
row has changed. This method can be called at any time during the
lifetime of a rowset and assuming the current row is within
the exception limitations (see below), it cancels the row insertion
of the current row.
In addition, multiple cancellations of row insertions can be made by adjusting the position of the cursor using any of the cursor position control methods such as:
CachedRowSet.absolute
CachedRowSet.first
CachedRowSet.last
SQLException
- if (1) the current row has not been inserted or (2)
the cursor is before the first row, after the last row, or on the
insert rowundoDelete()
,
ResultSet.cancelRowUpdates()
void undoUpdate() throws SQLException
acceptChanges
) or population. This method may also be called
while performing updates to the insert row.
undoUpdate
may be called at any time during the lifetime of a
rowset; however, after a synchronization has occurred, this method has no
effect until further modification to the rowset data has occurred.
SQLException
- if the cursor is before the first row or after the last
row in in this CachedRowSet
objectundoDelete()
,
undoInsert()
,
ResultSet.cancelRowUpdates()
boolean columnUpdated(int idx) throws SQLException
CachedRowSet
object has been updated.idx
- an int
identifying the column to be checked for updatestrue
if the designated column has been visibly updated;
false
otherwiseSQLException
- if the cursor is on the insert row, before the first row,
or after the last rowDatabaseMetaData.updatesAreDetected(int)
boolean columnUpdated(String columnName) throws SQLException
CachedRowSet
object has been updated.columnName
- a String
object giving the name of the
column to be checked for updatestrue
if the column has been visibly updated;
false
otherwiseSQLException
- if the cursor is on the insert row, before the first row,
or after the last rowDatabaseMetaData.updatesAreDetected(int)
Collection<?> toCollection() throws SQLException
CachedRowSet
object to a Collection
object that contains all of this CachedRowSet
object's data.
Implementations have some latitude in
how they can represent this Collection
object because of the
abstract nature of the Collection
framework.
Each row must be fully represented in either a
general purpose Collection
implementation or a specialized
Collection
implementation, such as a TreeMap
object or a Vector
object.
An SQL NULL
column value must be represented as a null
in the Java programming language.
The standard reference implementation for the CachedRowSet
interface uses a TreeMap
object for the rowset, with the
values in each row being contained in Vector
objects. It is
expected that most implementations will do the same.
The TreeMap
type of collection guarantees that the map will be in
ascending key order, sorted according to the natural order for the
key's class.
Each key references a Vector
object that corresponds to one
row of a RowSet
object. Therefore, the size of each
Vector
object must be exactly equal to the number of
columns in the RowSet
object.
The key used by the TreeMap
collection is determined by the
implementation, which may choose to leverage a set key that is
available within the internal RowSet
tabular structure by
virtue of a key already set either on the RowSet
object
itself or on the underlying SQL data.
Collection
object that contains the values in
each row in this CachedRowSet
objectSQLException
- if an error occurs generating the collectiontoCollection(int)
,
toCollection(String)
Collection<?> toCollection(int column) throws SQLException
CachedRowSet
object
to a Collection
object. Implementations have some latitude in
how they can represent this Collection
object because of the
abstract nature of the Collection
framework.
Each column value should be fully represented in either a
general purpose Collection
implementation or a specialized
Collection
implementation, such as a Vector
object.
An SQL NULL
column value must be represented as a null
in the Java programming language.
The standard reference implementation uses a Vector
object
to contain the column values, and it is expected
that most implementations will do the same. If a Vector
object
is used, it size must be exactly equal to the number of rows
in this CachedRowSet
object.
column
- an int
indicating the column whose values
are to be represented in a Collection
objectCollection
object that contains the values
stored in the specified column of this CachedRowSet
objectSQLException
- if an error occurs generating the collection or
an invalid column id is providedtoCollection()
,
toCollection(String)
Collection<?> toCollection(String column) throws SQLException
CachedRowSet
object
to a Collection
object. Implementations have some latitude in
how they can represent this Collection
object because of the
abstract nature of the Collection
framework.
Each column value should be fully represented in either a
general purpose Collection
implementation or a specialized
Collection
implementation, such as a Vector
object.
An SQL NULL
column value must be represented as a null
in the Java programming language.
The standard reference implementation uses a Vector
object
to contain the column values, and it is expected
that most implementations will do the same. If a Vector
object
is used, it size must be exactly equal to the number of rows
in this CachedRowSet
object.
column
- a String
object giving the name of the
column whose values are to be represented in a collectionCollection
object that contains the values
stored in the specified column of this CachedRowSet
objectSQLException
- if an error occurs generating the collection or
an invalid column id is providedtoCollection()
,
toCollection(int)
SyncProvider getSyncProvider() throws SQLException
SyncProvider
implementation for this
CachedRowSet
object. Internally, this method is used by a rowset
to trigger read or write actions between the rowset
and the data source. For example, a rowset may need to get a handle
on the the rowset reader (RowSetReader
object) from the
SyncProvider
to allow the rowset to be populated.
RowSetReader rowsetReader = null; SyncProvider provider = SyncFactory.getInstance("javax.sql.rowset.provider.RIOptimisticProvider"); if (provider instanceof RIOptimisticProvider) { rowsetReader = provider.getRowSetReader(); }Assuming rowsetReader is a private, accessible field within the rowset implementation, when an application calls the
execute
method, it in turn calls on the reader's readData
method
to populate the RowSet
object.
rowsetReader.readData((RowSetInternal)this);
In addition, an application can use the SyncProvider
object
returned by this method to call methods that return information about the
SyncProvider
object, including information about the
vendor, version, provider identification, synchronization grade, and locks
it currently has set.
SyncProvider
object that was set when the rowset
was instantiated, or if none was was set, the default providerSQLException
- if an error occurs while returning the
SyncProvider
objectsetSyncProvider(java.lang.String)
void setSyncProvider(String provider) throws SQLException
SyncProvider
objec for this CachedRowSet
object to the one specified. This method
allows the SyncProvider
object to be reset.
A CachedRowSet
implementation should always be instantiated
with an available SyncProvider
mechanism, but there are
cases where resetting the SyncProvider
object is desirable
or necessary. For example, an application might want to use the default
SyncProvider
object for a time and then choose to use a provider
that has more recently become available and better fits its needs.
Resetting the SyncProvider
object causes the
RowSet
object to request a new SyncProvider
implementation
from the SyncFactory
. This has the effect of resetting
all previous connections and relationships with the originating
data source and can potentially drastically change the synchronization
behavior of a disconnected rowset.
provider
- a String
object giving the fully qualified class
name of a SyncProvider
implementationSQLException
- if an error occurs while attempting to reset the
SyncProvider
implementationgetSyncProvider()
int size()
CachedRowSet
object.void setMetaData(RowSetMetaData md) throws SQLException
CachedRowSet
object with
the given RowSetMetaData
object. When a
RowSetReader
object is reading the contents of a rowset,
it creates a RowSetMetaData
object and initializes
it using the methods in the RowSetMetaData
implementation.
The reference implementation uses the RowSetMetaDataImpl
class. When the reader has completed reading the rowset contents,
this method is called internally to pass the RowSetMetaData
object to the rowset.md
- a RowSetMetaData
object containing
metadata about the columns in this CachedRowSet
objectSQLException
- if invalid metadata is supplied to the
rowsetResultSet getOriginal() throws SQLException
ResultSet
object containing the original value of this
CachedRowSet
object.
The cursor for the ResultSet
object should be positioned before the first row.
In addition, the returned ResultSet
object should have the following
properties:
The original value for a RowSet
object is the value it had before
the last synchronization with the underlying data source. If there have been
no synchronizations, the original value will be the value with which the
RowSet
object was populated. This method is called internally
when an aplication calls the method acceptChanges
and the
SyncProvider
object has been implemented to check for conflicts.
If this is the case, the writer compares the original value with the value
currently in the data source to check for conflicts.
ResultSet
object that contains the original value for
this CachedRowSet
objectSQLException
- if an error occurs producing the
ResultSet
objectResultSet getOriginalRow() throws SQLException
ResultSet
object containing the original value for the
current row only of this CachedRowSet
object.
The cursor for the ResultSet
object should be positioned before the first row.
In addition, the returned ResultSet
object should have the following
properties:
SQLException
- if there is no current rowsetOriginalRow()
void setOriginalRow() throws SQLException
CachedRowSet
object as the original
row.
This method is called internally after the any modified values in the current row have been synchronized with the data source. The current row must be tagged as no longer inserted, deleted or updated.
A call to setOriginalRow
is irreversible.
SQLException
- if there is no current row or an error is
encountered resetting the contents of the original rowgetOriginalRow()
String getTableName() throws SQLException
CachedRowSet
object. This name may be set on multiple occasions,
and the specification imposes no limits on how many times this
may occur or whether standard implementations should keep track
of previous table names.String
object giving the name of the table that is the
source of data for this CachedRowSet
object or null
if no name has been set for the tableSQLException
- if an error is encountered returning the table nameResultSetMetaData.getTableName(int)
void setTableName(String tabName) throws SQLException
CachedRowSet
object was derived to the given table name. The writer uses this name to
determine which table to use when comparing the values in the data source with the
CachedRowSet
object's values during a synchronization attempt.
The table identifier also indicates where modified values from this
CachedRowSet
object should be written.
The implementation of this CachedRowSet
object may obtain the
the name internally from the RowSetMetaDataImpl
object.
tabName
- a String
object identifying the table from which this
CachedRowSet
object was derived; cannot be null
but may be an empty stringSQLException
- if an error is encountered naming the table or
tabName is null
RowSetMetaData.setTableName(int, java.lang.String)
,
RowSetWriter
,
SyncProvider
int[] getKeyColumns() throws SQLException
CachedRowSet
object.CachedRowSet
object. This array should be
empty if no columns are representative of a primary key.SQLException
- if this CachedRowSet
object is emptysetKeyColumns(int[])
,
Joinable.getMatchColumnIndexes()
,
Joinable.getMatchColumnNames()
void setKeyColumns(int[] keys) throws SQLException
CachedRowSet
object's keyCols
field with the given array of column numbers, which forms a key
for uniquely identifying a row in this CachedRowSet
object.
If a CachedRowSet
object becomes part of a JoinRowSet
object, the keys defined by this method and the resulting constraints are
maintained if the columns designated as key columns also become match
columns.
keys
- an array of int
indicating the columns that form
a primary key for this CachedRowSet
object; every
element in the array must be greater than 0
and
less than or equal to the number of columns in this rowsetSQLException
- if any of the numbers in the given array
are not valid for this rowsetgetKeyColumns()
,
Joinable.setMatchColumn(String)
,
Joinable.setMatchColumn(int)
RowSet createShared() throws SQLException
RowSet
object backed by the same data as
that of this CachedRowSet
object. In effect, both
CachedRowSet
objects have a cursor over the same data.
As a result, any changes made by a duplicate are visible to the original
and to any other duplicates, just as a change made by the original is visible
to all of its duplicates. If a duplicate calls a method that changes the
underlying data, the method it calls notifies all registered listeners
just as it would when it is called by the original CachedRowSet
object.
In addition, any RowSet
object
created by this method will have the same properties as this
CachedRowSet
object. For example, if this CachedRowSet
object is read-only, all of its duplicates will also be read-only. If it is
changed to be updatable, the duplicates also become updatable.
NOTE: If multiple threads access RowSet
objects created from
the createShared()
method, the following behavior is specified
to preserve shared data integrity: reads and writes of all
shared RowSet
objects should be made serially between each
object and the single underlying tabular structure.
RowSet
object that has the same properties
as this CachedRowSet
object and that has a cursor over
the same dataSQLException
- if an error occurs or cloning is not
supported in the underlying platformRowSetEvent
,
RowSetListener
CachedRowSet createCopy() throws SQLException
RowSet
object that is a deep copy of the data in
this CachedRowSet
object. In contrast to
the RowSet
object generated from a createShared
call, updates made to the copy of the original RowSet
object
must not be visible to the original RowSet
object. Also, any
event listeners that are registered with the original
RowSet
must not have scope over the new
RowSet
copies. In addition, any constraint restrictions
established must be maintained.RowSet
object that is a deep copy
of this CachedRowSet
object and is
completely independent of this CachedRowSet
objectSQLException
- if an error occurs in generating the copy of
the of this CachedRowSet
objectcreateShared()
,
createCopySchema()
,
createCopyNoConstraints()
,
RowSetEvent
,
RowSetListener
CachedRowSet createCopySchema() throws SQLException
CachedRowSet
object that is an empty copy of this
CachedRowSet
object. The copy
must not contain any contents but only represent the table
structure of the original CachedRowSet
object. In addition, primary
or foreign key constraints set in the originating CachedRowSet
object must
be equally enforced in the new empty CachedRowSet
object.
In contrast to
the RowSet
object generated from a createShared
method
call, updates made to a copy of this CachedRowSet
object with the
createCopySchema
method must not be visible to it.
Applications can form a WebRowSet
object from the CachedRowSet
object returned by this method in order
to export the RowSet
schema definition to XML for future use.
SQLException
- if an error occurs in cloning the structure of this
CachedRowSet
objectcreateShared()
,
createCopySchema()
,
createCopyNoConstraints()
,
RowSetEvent
,
RowSetListener
CachedRowSet createCopyNoConstraints() throws SQLException
CachedRowSet
object that is a deep copy of
this CachedRowSet
object's data but is independent of it.
In contrast to
the RowSet
object generated from a createShared
method call, updates made to a copy of this CachedRowSet
object
must not be visible to it. Also, any
event listeners that are registered with this
CachedRowSet
object must not have scope over the new
RowSet
object. In addition, any constraint restrictions
established for this CachedRowSet
object must not be maintained
in the copy.CachedRowSet
object that is a deep copy
of this CachedRowSet
object and is
completely independent of this CachedRowSet
objectSQLException
- if an error occurs in generating the copy of
the of this CachedRowSet
objectcreateCopy()
,
createShared()
,
createCopySchema()
,
RowSetEvent
,
RowSetListener
RowSetWarning getRowSetWarnings() throws SQLException
RowSet
object.
Subsequent warnings on this RowSet
object will be chained to the
RowSetWarning
object that this method returns.
The warning chain is automatically cleared each time a new row is read.
This method may not be called on a RowSet object that has been closed;
doing so will cause a SQLException
to be thrown.RowSetWarning
object reported or null if there are noneSQLException
- if this method is called on a closed RowSetRowSetWarning
boolean getShowDeleted() throws SQLException
boolean
indicating whether rows marked
for deletion appear in the set of current rows. If true
is
returned, deleted rows are visible with the current rows. If
false
is returned, rows are not visible with the set of
current rows. The default value is false
.
Standard rowset implementations may choose to restrict this behavior due to security considerations or to better fit certain deployment scenarios. This is left as implementation defined and does not represent standard behavior.
Note: Allowing deleted rows to remain visible complicates the behavior
of some standard JDBC RowSet
Implementations methods.
However, most rowset users can simply ignore this extra detail because
only very specialized applications will likely want to take advantage of
this feature.
true
if deleted rows are visible;
false
otherwiseSQLException
- if a rowset implementation is unable to
to determine whether rows marked for deletion are visiblesetShowDeleted(boolean)
void setShowDeleted(boolean b) throws SQLException
showDeleted
to the given
boolean
value, which determines whether
rows marked for deletion appear in the set of current rows.
If the value is set to true
, deleted rows are immediately
visible with the set of current rows. If the value is set to
false
, the deleted rows are set as invisible with the
current set of rows.
Standard rowset implementations may choose to restrict this behavior due to security considerations or to better fit certain deployment scenarios. This is left as implementations defined and does not represent standard behavior.
b
- true
if deleted rows should be shown;
false
otherwiseSQLException
- if a rowset implementation is unable to
to reset whether deleted rows should be visiblegetShowDeleted()
void commit() throws SQLException
CachedRowSet
object's SyncProvider
contains
a Connection
object from the ResultSet
or JDBC
properties passed to it's constructors. This method wraps the
Connection
commit method to allow flexible
auto commit or non auto commit transactional control support.
Makes all changes that are performed by the acceptChanges()
method since the previous commit/rollback permanent. This method should
be used only when auto-commit mode has been disabled.
SQLException
- if a database access error occurs or this
Connection object within this CachedRowSet
is in auto-commit modeConnection.setAutoCommit(boolean)
void rollback() throws SQLException
CachedRowSet
object's SyncProvider
contains
a Connection
object from the original ResultSet
or JDBC properties passed to it.
Undoes all changes made in the current transaction. This method should be used only when auto-commit mode has been disabled.
SQLException
- if a database access error occurs or this Connection
object within this CachedRowSet
is in auto-commit mode.void rollback(Savepoint s) throws SQLException
CachedRowSet
object's SyncProvider
contains
a Connection
object from the original ResultSet
or JDBC properties passed to it.
Undoes all changes made in the current transaction back to the last
Savepoint
transaction marker. This method should be used only
when auto-commit mode has been disabled.
s
- A Savepoint
transaction markerSQLException
- if a database access error occurs or this Connection
object within this CachedRowSet
is in auto-commit mode.void rowSetPopulated(RowSetEvent event, int numRows) throws SQLException
numRows
parameter
ensures that this event will only be fired every numRow
.
The source of the event can be retrieved with the method event.getSource.
event
- a RowSetEvent
object that contains the
RowSet
object that is the source of the eventsnumRows
- when populating, the number of rows interval on which the
CachedRowSet
populated should fire; the default value
is zero; cannot be less than fetchSize
or zeroSQLException
void populate(ResultSet rs, int startRow) throws SQLException
CachedRowSet
object with data from
the given ResultSet
object. While related to the populate(ResultSet)
method, an additional parameter is provided to allow starting position within
the ResultSet
from where to populate the CachedRowSet
instance.
This method can be used as an alternative to the execute
method when an
application has a connection to an open ResultSet
object.
Using the method populate
can be more efficient than using
the version of the execute
method that takes no parameters
because it does not open a new connection and re-execute this
CachedRowSet
object's command. Using the populate
method is more a matter of convenience when compared to using the version
of execute
that takes a ResultSet
object.
startRow
- the position in the ResultSet
from where to start
populating the records in this CachedRowSet
rs
- the ResultSet
object containing the data
to be read into this CachedRowSet
objectSQLException
- if a null ResultSet
object is supplied
or this CachedRowSet
object cannot
retrieve the associated ResultSetMetaData
objectexecute(java.sql.Connection)
,
populate(ResultSet)
,
ResultSet
,
ResultSetMetaData
void setPageSize(int size) throws SQLException
CachedRowSet
object's page-size. A CachedRowSet
may be configured to populate itself in page-size sized batches of rows. When
either populate()
or execute()
are called, the
CachedRowSet
fetches an additional page according to the
original SQL query used to populate the RowSet.size
- the page-size of the CachedRowSet
SQLException
- if an error occurs setting the CachedRowSet
page size or if the page size is less than 0.int getPageSize()
CachedRowSet
objectint
page sizeboolean nextPage() throws SQLException
CachedRowSet
. This causes
the CachedRowSet
implementation to fetch the next page-size
rows and populate the RowSet, if remaining rows remain within scope of the
original SQL query used to populated the RowSet.SQLException
- if an error occurs fetching the next page, or if this
method is called prematurely before populate or execute.boolean previousPage() throws SQLException
CachedRowSet
. This causes
the CachedRowSet
implementation to fetch the previous page-size
rows and populate the RowSet. The amount of rows returned in the previous
page must always remain within scope of the original SQL query used to
populate the RowSet.SQLException
- if an error occurs fetching the previous page, or if
this method is called prematurely before populate or execute.
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2013, Oracle and/or its affiliates. All rights reserved.
DRAFT ea-b92