borland.jbcl Packages  borland.jbcl Class Hierarchy  borland.jbcl.dataset 

DataSet class (abstract)

java.lang.Object
   +----borland.jbcl.dataset.ReadRow
           +----borland.jbcl.dataset.ReadWriteRow
                   +----borland.jbcl.dataset.DataSet
                           +----borland.jbcl.dataset.StorageDataSet
                           +----borland.jbcl.dataset.DataSetView

About the DataSet class

Variables  Properties  Methods  Event Listeners

Implements AccessListener, MasterNavigateListener, StatusListener, EventListener

The DataSet class is an abstract class that provides basic cursor functionality for access to two-dimensional data. It supports the concept of a current row position which allows for navigation of the data in the cursor. The DataSet also manages a "pseudo" record -- an area in memory where a newly inserted row or changes to the current row are temporarily stored.

Several data-aware controls can be associated with the same DataSet. In such cases, the controls navigate together and when you move the row position of a control, the row position changes for all controls that share the same cursor. This synchronization of controls that share a common DataSet can greatly ease the development of the user-interface portion of your application.

Controls which share the same DataSet as their data source share also the same "pseudo" record. This allows updates to be visible as soon as entry at the field level is complete, for example, by navigating off the field.

The DataSet component is opened implicitly (by default) when components bound to it are opened. For example, launching an application that includes a data-aware control that is bound to a DataSet automatically opens the DataSet so you seldom have to open the DataSet explicitly. No code is generated for this implicit open.

The DataSet has an associated SortDescriptor object that defines properties which affect the sort order of the data in the DataSet. This is accessed from the sort property in the JBuilder Component Inspector.

JBuilder DataSet objects have relational capability and can be linked to form master-detail relationships. The MasterLinkDescriptor holds the properties required for relational capability between DataSet objects.

The DataSet class extended by DataSetView and StorageDataSet. The DataSetView component allows for an alternate view (sort order and filter criteria) for the data contained in the DataSet while the StorageDataSet class (an abstract class) is extended by components such as the QueryDataSet that you instantiate and work with in your application.


DataSet variables

Variables implemented in borland.jbcl.dataset.ReadRow

DataSet properties

*Read-only properties **Write-only properties

Properties implemented in this class

Properties implemented in borland.jbcl.dataset.ReadRow

Properties implemented in borland.jbcl.dataset.ReadWriteRow

Properties implemented in java.lang.Object

DataSet methods

Methods implemented in this class

Methods implemented in borland.jbcl.dataset.ReadRow

Methods implemented in borland.jbcl.dataset.ReadWriteRow

Methods implemented in java.lang.Object

DataSet event listeners


DataSet properties

defaultValues

 public void setDefaultValues(borland.jbcl.dataset.DataRow row)
Initializes the row. If the DataSet is a detail DataSet of a master-detail relationship, this method also initializes the detail linking columns.

displayErrors

 public final boolean isDisplayErrors()
 public final void setDisplayErrors(boolean displayErrors)
Determines whether the ExceptionDialog displays or not when an Exception is generated.

editing

 public final boolean isEditing()
Read-only property that returns whether the DataSet is being edited or not.

editingNewRow

 public final boolean isEditingNewRow()
Read-only property that returns whether data is being added to a new row in the DataSet or not.

empty

 public final boolean isEmpty()
Read-only property that returns whether the DataSet is empty or contains data.

internalRow

 public final int getInternalRow()
Returns a unique identifier for the current row, often called rowId. Can be used by the goToInternalRow() method to reposition the current row position.

lastColumnVisited

 public final void setLastColumnVisited(java.lang.String columnName)
Specifies the most recent Column that was navigated to in a data-aware control. This method is used by the interactiveLocate() method as the default Column to locate on if its parameter of a target Column for the locate is not specified.

masterLink

 public final MasterLinkDescriptor getMasterLink()
 public synchronized void setMasterLink(borland.jbcl.dataset.MasterLinkDescriptor descriptor)
Stores the MasterLinkDescriptor object that contains the properties of a master-detail relationship. This property is set for the detail DataSet of a master-detail relationship.

open

 public boolean isOpen()
Read-only property that returns whether the DataSet is open or not.

row

 public final int getRow()
Returns current row position.

rowCount

 public final int getRowCount()
Returns the number of rows visible with this DataSet. This number may differ with rows in associated DataSet.

rowFilterListener

 public final RowFilterListener getRowFilterListener()
Read-only property that returns the registered RowFilterListener of the DataSet.

schemaName

 public final String getSchemaName()

sort

 public final SortDescriptor getSort()
 public final synchronized void setSort(borland.jbcl.dataset.SortDescriptor descriptor)
Specifies the SortDescriptor object where properties that define the sort order of the data in a DataSet are stored. This property is accessed in the JBuilder Component Inspector from the sort property.

Setting the sort descriptor generates a dispatch to the registered AccessListener object. On error, setSort() generates a DataSetException.

status

 public final int getStatus()
Read-only property that returns the status for the current row of the DataSet. Valid values for the returned int are defined in borland.jbcl.dataset.RowStatus Variables.

storageDataSet

 public final StorageDataSet getStorageDataSet()
Write-only property that specifies the StorageDataSet object that is the data storage implementation for the DataSet.

tableName

 public final String getTableName()
Specifies the name of a table from which the DataSet obtains its data. This property must be set for DataSet objects that have updateable columns.

The tableName property is normally retrieved automatically from the data source. Some stored procedures and queries however will not return the table name. If it doesn't, use setTableName() to specify the table so that changes made to the DataSet can be resolved back to the data source. The table name is also useful as a String identifier of the data source.


DataSet methods

addRow(borland.jbcl.dataset.DataRow)

  public final void addRow(borland.jbcl.dataset.DataRow dataRow)
Adds a new row to the DataSet at the end of existing rows and sets the new row's RowStatus to INSERTED. The current row position does not move to the newly added row. To move to the newly added row, perform a locate with the DataRow object with which the addRow() operation was effected. If the DataSet has an associated SortDescriptor, the new row displays according to the specified sort order. On error, this method throws a DataSetException.

Default values (set using the default property) are automatically filled in when a new row is inserted. If no other updates are made to the row, it is considered untouched and is not posted.

Parameters:

dataRow
The DataRow to add to the current DataSet.

atFirst()

  public final boolean atFirst()
Returns true if the current position is the first visible row of DataSet, otherwise, this method returns false.

atLast()

  public final boolean atLast()
Returns true if the current position is the last visible row of DataSet, otherwise, this method returns false.

canNavigate(borland.jbcl.dataset.Column, int)

  public final boolean canNavigate(borland.jbcl.dataset.Column column, int row)
Returns whether the specified column can be navigated to (true) or not (false).

Parameters:

column
The Column component.
row
The unique row identifier for the row.

canSet(borland.jbcl.dataset.Column)

  public final boolean canSet(borland.jbcl.dataset.Column column)
Can edit values at column and row.

cancel()

  public final void cancel()
Cancels the edits to a new or existing record. On error, this method throws a DataSetException.

cancelLoading()

  public final void cancelLoading()
Cancels the loading of data into the DataSet.

clearStatus()

  public final void clearStatus()
Instructs all status listeners (for example, the StatusBar control) to clear their status messages.

cloneDataSetView()

  public final DataSetView cloneDataSetView()
Copies the DataSetView and returns the copied object. On error, this method throws a DataSetException.

close()

  public boolean close()
Returns whether the DataSet is closed as a result of this method. This method returns true if the DataSet is closed by executing this method and false if the DataSet does not need closing (for example, it is already closed).

Closing a DataSet allows for structural changes to be made to the DataSet, such as adding a new Column or changing the sort order, and so on. All changes are applied to the data currently in the DataSet. The close() method does not discard any inserted, edited or deleted rows in the DataSet.

For the DataSetView subclass of DataSet, the close() method must be called when explicitly removing an instantiated DataSetView from memory and preparing it for garbage collection. Otherwise, the instantiated DataSetView remains active in memory as long as its associated StorageDataSet is active.

If you connect to your data source using a QueryDataSet and its query statement contains parameters, you need to call DataSet.close() before providing for another QueryDataSet.

columnIsVisible(java.lang.String)

  public boolean columnIsVisible(java.lang.String columnName)
Indicates true if the Column should be displayed in UI controls. This method returns true for Columns that have their visible property set. Aggregate calculated columns and master-detail link columns are hidden by default and return false.

Parameters:

columnName
The String name of the Column component.

dataChangeListenersDispatch(borland.jbcl.dataset.DataChangeEvent)

  public final void dataChangeListenersDispatch(borland.jbcl.dataset.DataChangeEvent event)

deleteAllRows()

  public final void deleteAllRows()
Deletes all rows of data in the DataSet, leaving an empty DataSet. Deletion status information is tracked for resolution back to the data source. If all rows of the DataSet cannot be deleted, this method throws a DataSetException.

deleteRow()

  public final void deleteRow()
Deletes the current row of the DataSet. If the current row is new or being edited, the edit state is canceled and the new or edited row is deleted. On failure, this method throws a DataSetException.

dittoRow(boolean)

  public void dittoRow(boolean dittoExisting)
Copies the contents of the previous row to the current (new) row. Does nothing if the current row is the first row or if the current row is an exising row.

editRow()

  public final void editRow()
Edits the existing row of the DataSet. On failure, this method throws a DataSetException.

enableDataSetEvents(boolean)

  public void enableDataSetEvents(boolean enable)
Makes data-aware controls ignore programmatic changes to the position and general state of a DataSet. A control cannot repaint properly while the dataSetEvents are disabled. When performing lengthy DataSet operations, you may want to set this property to false prior to initiating such operations. If you do, you must set this property back to true to allow UI controls to repaint properly.

first()

  public final void first()
Moves the row position to the first row visible to the DataSet and sends a DataChangeEvent notification of rowChanged to its registered listeners. This method sets flags that are used by the inBounds() method to detect if the navigation was valid. On failure, this method throws a DataSetException.

getDataRow(borland.jbcl.dataset.DataRow)

  public final void getDataRow(borland.jbcl.dataset.DataRow dataRow)
Returns all the values at the current row.

Parameters:

dataRow
The DataRow object that gets its values from the current row position when this method is executed.

getDataRow(int, borland.jbcl.dataset.DataRow)

  public final void getDataRow(int row, borland.jbcl.dataset.DataRow dataRow)
Returns all the values at row.

Parameters:

row
The unique rowId for a row in the DataSet.
dataRow
The DataRow object that gets its values from the row indicated by the row parameter when this method is executed.

getVariant(int, int, borland.jbcl.util.Variant)

  public final void getVariant(int ordinal, int row, borland.jbcl.util.Variant value)
Assigns the value stored at the intersection of the specified Column and row to value.

Parameters:

ordinal
An integer value that represents the nth Column in the DataSet where the Variant value is located.
row
A integer value representing the unique row identifier for the row.
value
The value that is assigned by executing this method.

getVariant(java.lang.String, int, borland.jbcl.util.Variant)

  public final void getVariant(java.lang.String columnName, int row, borland.jbcl.util.Variant value)
Assigns the value stored at the intersection of the specified columnName and row to value.

Parameters:

columnName
The String name of the Column.
row
The unique row identifier for the row.
value
The value that is assigned by executing this method.

goToClosestRow(int)

  public final boolean goToClosestRow(int row)
Moves the row position to the closest row indicated by the row parameter. This method returns true if the move is successful, otherwise, it returns false.

Parameters:

row
The unique row identifier for the row of the DataSet that this method should attempt to move to.
On error, this method throws a DataSetException.

goToInternalRow(int)

  public final boolean goToInternalRow(int newInternalRow)
Attempts to navigate to the specified row. If the row identified by newInternalRow no longer exists, position remains unchanged. Returns true when successful, false otherwise.

Parameters:

newInternalRow
The unique row identifier of the row to move to.

goToRow(borland.jbcl.dataset.ReadRow)

  public void goToRow(borland.jbcl.dataset.ReadRow row)
Forces this DataSet to move to the same position as row if row is of the same StorageDataSet as this DataSet. If row is not from the same StorageDataSet, this method throws a DataSetException of INCOMPATIBLE_DATA_ROW. If this DataSet object's current view is filtered and does not include row, the current position of this DataSet moves to the closest row that is in its view.

Parameters:

row
The unique row identifier of the row to move to.

goToRow(int)

  public final boolean goToRow(int row)
Moves to the specified row position, where row represents the unique row identifier for the row. Returns true if the move is successful, otherwise, it returns false. On error, this method throws a DataSetException.

Parameters:

row
The unique row identifier of the row to move to.

inBounds()

  public final boolean inBounds()
Returns true if the most recent navigation was "in bounds", otherwise, this method returns false. A navigation is in bounds if it falls between the first and last records (inclusive) that are visible to the cursor. This method allows you to test whether either condition of beginning or end of file is encountered with a single method call.

Methods that set the "in bounds" flag include: first(), last(), next(), and prior(). If you prefer or if your application requires it, you can call any of these methods to reset the inBounds flag. Any navigation effected through the user-interface also sets inBounds() flag.

insertRow(boolean)

  public final void insertRow(boolean before)
Inserts a new row at the end of existing rows in the DataSet and sends a DataChangeEvent notification of rowAdded and a MasterNavigateEvent to its registered listeners. The RowStatus of the new row is set to INSERTED and the current row position is moved to the new row. The before parameter specifies whether the new row should be added before the current row (true) or at the end of existing rows in the DataSet (false). On failure, this method throws a DataSetException.

Note: While editing an inserted row, the return value of the row() method is equal to the row that it was inserted before, or one greater than the row it was inserted after.

Parameters:

before
Whether the new record should be inserted before (true)or after (false) the current row. This property defaults to false.

interactiveLocate(java.lang.String, java.lang.String, int, boolean)

  public void interactiveLocate(java.lang.String text, java.lang.String locateColumnName, int locateOptions, boolean enterPressed)
Searches the specified Column of the DataSet for the value specified in text. This method is used by the borland.jbcl.control.LocatorControl for its interactive search capabilty and is not intended for programatic use.

Parameters:

text
The String representation of the value to search for.
locateColumnName
The String name of the Column in which to perform the search. If null, this method attempts to use the last column visited (as returned by getLastColumnVisited()). If the last column visited was not set, the first Column in the StorageDataSet is used.
locateOptions
An integer value representing the locate options to use. See borland.jbcl.dataset.Locate for valid values for this parameter.
enterPressed
Specifies whether the Enter key should be pressed prior to initiating the search or if each key press should be used to perform an incremental search. Incremental searches are available only for String searches.

isNew(int)

  public final boolean isNew(int row)
Returns whether the row indicated by the row parameter is new (true). Otherwise, this method returns false.

Parameters:

row
The row parameter represents the unique row identifier for the row.
On failure, this method throws a DataSetException.

last()

  public final void last()
Moves the current position to the last row visible to the DataSet and sends a notification to registered NavigationListeners if the move was successful. This method sets flags that are used by the inBounds() method to detect if the navigation was valid.

If an edit is in progress, the changes are posted prior to performing the move operation. On failure, this method throws a DataSetException.

locate(borland.jbcl.dataset.ReadRow, int)

  public final boolean locate(borland.jbcl.dataset.ReadRow rowLocate, int locateOptions)
Locates the row of data with the specified row of values and moves the current row position to that row. The locate operation includes all columns of the ReadRow; to limit the locate to specific columns of interest, use a "scoped" ReadRow. If the row is scoped to a specific set of columns, only those columns are used for the locate.

Parameters:

rowLocate
The ReadRow that contains values to use in for the locate operation.
locateOptions
Options that are applicable when locating data. Valid values for the locateOptions are defined in borland.jbcl.dataset.Locate variables. The Locate variables may be combined using the Java OR operator of a vertical pipe symbol (|) between each variable where it makes sense to do so. For example, you can search using partial strings and specifying case insensitivity.

lookup(borland.jbcl.dataset.ReadRow, borland.jbcl.dataset.DataRow, int)

  public final boolean lookup(borland.jbcl.dataset.ReadRow rowLocate, borland.jbcl.dataset.DataRow resultRow, int locateOptions)
Performs a lookup for the row with the specified values. If a match is found, this method returns the data from the matching row as resultRow, and returns true but does not navigate to the matching row. If no match is found, this method returns false. This method includes all columns of the ReadRow; to limit the lookup to specific columns, use a "scoped" row that includes only the columns of interest.

Parameters:

rowLocate
The ReadRow that contains values to use in for the lookup operation.
resultRow
The data in the row where the match with the rowLocate values is found.
locateOptions
Options that are applicable when locating data. Valid values for the locateOptions are defined in borland.jbcl.dataset.Locate variables. The Locate variables may be combined using a vertical pipe symbol ( | ) between each variable where it makes sense to do so. For example, you can search using partial strings and specifying case insensitivity.

markPending(boolean)

  public final void markPending(boolean on)
Marks a row as pending resolution. Used internally when saving changes from a DataSet to a remote data provider that supports transactions (for example, JDBC connections).

next()

  public final boolean next()
Moves the row position to the next row visible to the DataSet and sends a DataChangeEvent notification of rowChanged to its registered listeners. This method sets flags that are used by the inBounds() method to detect if the navigation was valid. On failure, this method throws a DataSetException.

open()

  public boolean open()
Returns whether the DataSet is opened as a result of this method. This method returns true if the DataSet is opened by executing this method and false if the DataSet does not need opening (for example, it is already open).

persistentColumn(java.lang.String)

  public synchronized Column persistentColumn(java.lang.String columnName)
Adds or retrieves a Column object of the DataSet and marks the given Column as "persistent". If the Column specified by columnName already exists, this method returns it. If it does not yet exist, this method creates and returns it. The main use of this method is to simplify code generation for setting Column properties in the JBuilder UI designer.

If you do not want the Column to be specified as persistent, use the getColumns() method of the StorageDataSet class.

For more information on working with persistent Column components, see the Working with Columns topic in the Database Application Developer's Guide.

Parameters:

columnName
The String name of the Column component you want to set as persistent.

post()

  public final boolean post()
Saves the current row to the DataSet. On error, this method throws a DataSetException

postAllDataSets()

  public void postAllDataSets()
Posts all unposted rows for all DataSet and DataSetView components that share the same StorageDataSet property. On error, this method throws a DataSetException.

prior()

  public final boolean prior()
Moves the row position to the previous row visible to the DataSet and sends a DataChangeEvent notification of rowChanged to its registered listeners. This method sets flags that are used by the inBounds() method to detect if the navigation was valid. On error, this method throws a DataSetException.

refetchRow(borland.jbcl.dataset.ReadWriteRow)

  public void refetchRow(borland.jbcl.dataset.ReadWriteRow row)
Refetches the specified row.

Parameters:

row
The ReadWriteRow implementation that you want refetched.

refilter()

  public void refilter()
Forces the filter for this DataSet to be recomputed on all rows.

Closing and re-opening a DataSet with a filter will not always cause the filter code to be re-executed. Similarly, if your filter is based on the value of a global variable, changing the global variable will not change the set of rows displayed. In both cases, use the refilter() method to ensure that the filter is re-executed.

refresh()

  public void refresh()
Refreshes the data from the DataSet. On error, this method throws a DataSetException.

refreshSupported()

  public boolean refreshSupported()
Returns whether a refresh operation is supported.

resetInBounds()

  public final void resetInBounds()
Sets the "in bounds" state to true. This method is not normally used in an application's code since any successful navigation sets this to true.

resolvePending(boolean)

  public final void resolvePending(boolean resolved)
Method used internally when resolving changes.

row()

  public final int row()
Returns the unique row identifier for the current row position.

rowCount()

  public final int rowCount()
Returns the number of rows visible in this DataSet. This count includes the pseudo record for a record currently being added (if applicable). If a filter criteria is set, this may differ with the number of rows visible in associated DataSet objects. On error, this method throws a DataSetException.

saveChanges()

  public void saveChanges()
Saves changes made to the data in the DataSet back to the data source using default QueryResolver behavior.

saveChangesSupported()

  public boolean saveChangesSupported()
Returns whether the data source supports the saving of data changes (true) or not (false). For TableDataSet components, this method returns false.

setDefaultValues()

  public void setDefaultValues()
Sets all values in the current row of the DataSet to its default values.

Overrides: borland.jbcl.dataset.ReadWriteRow.setDefaultValues()

startEdit(borland.jbcl.dataset.Column)

  public final void startEdit(borland.jbcl.dataset.Column column)
Calls editRow() if the column can be edited. Throws a DataSetException if editing of the column is not allowed.

toggleViewOrder(java.lang.String)

  public synchronized void toggleViewOrder(java.lang.String columnName)

updateRow(borland.jbcl.dataset.DataRow)

  public final void updateRow(borland.jbcl.dataset.DataRow dataRow)
Updates all values in the current row with those in the dataRow. If the DataSet is not open, a DataSetException of DataSetNotOpen is generated. This method can also throw a ValidationException if applicable.

DataSet event listeners

This class is a source for the following event sets. For information on the JBCL event sets, see Events in JBCL.

access

 public final void addAccessListener(borland.jbcl.dataset.AccessListener listener)
 public final void removeAccessListener(borland.jbcl.dataset.AccessListener listener)

dataChange

 public final void addDataChangeListener(borland.jbcl.dataset.DataChangeListener listener)
 public final void removeDataChangeListener(borland.jbcl.dataset.DataChangeListener listener)

masterNavigate

 public final void addMasterNavigateListener(borland.jbcl.dataset.MasterNavigateListener listener)
 public final void removeMasterNavigateListener(borland.jbcl.dataset.MasterNavigateListener listener)

navigation

 public final void addNavigationListener(borland.jbcl.dataset.NavigationListener listener)
 public final void removeNavigationListener(borland.jbcl.dataset.NavigationListener listener)

open

 public final void addOpenListener(borland.jbcl.dataset.OpenListener listener)
 public final void removeOpenListener(borland.jbcl.dataset.OpenListener listener)

rowFilter

 public final void addRowFilterListener(borland.jbcl.dataset.RowFilterListener listener)
 public final void removeRowFilterListener(borland.jbcl.dataset.RowFilterListener listener)

status

 public final void addStatusListener(borland.jbcl.dataset.StatusListener listener)
 public final void removeStatusListener(borland.jbcl.dataset.StatusListener listener)