borland Packages Class Hierarchy dx.dataset Package
java.lang.Object +----com.borland.dx.dataset.ReadRow +----com.borland.dx.dataset.ReadWriteRow +----com.borland.dx.dataset.DataSet +----com.borland.dx.dataset.DataSetView +----com.borland.dx.dataset.StorageDataSet
Properties Methods Event Listeners
Implements AccessListener, Designable, MasterNavigateListener, StatusListener, Serializable, EventListener
The DataSet class is an abstract class that provides basic editing, view, and 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 DataSet. 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.
The data in a DataSet can be modified programmatically or through a data-aware control. To connect a DataSet to a data-aware control, set the control's dataSet property to the DataSet you want to use as the data source. 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 DataSet. 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 visual components bound to it are shown. 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.
You can navigate through the data in a DataSet using a UI control or programmatically. To navigate programmatically, use the first(), last(), next(), and prior() methods. To verify if such a navigation is valid use the inBounds() method. Similarly, to perform tests for the "end of file" or "beginning of file" conditions, use the atLast() or atFirst() methods.
The DataSet has an associated SortDescriptor object that defines properties which affect the sort order of the data in the DataSet.
JDataStore 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 is extended by DataSetView and StorageDataSet. The DataSetView component allows for an alternate view (sort order, navigation, and filter criteria) for the data contained in the DataSet. A StorageDataSet, and any class that extends StorageDataSet, manages the storage aspects of the data operated on by the DataSet.
public void setDefaultValues(DataRow row)Initializes the current row to the default values of all columns. If the DataSet is a detail DataSet of a master-detail relationship, this method also initializes the detail linking columns.
public final boolean isDetailDataSetWithFetchAsNeeded()Read-only property that returns true if a MasterLinkDescriptor has been set and its isFetchAsNeeded property is true. Otherwise, it returns false.
public final synchronized DataSet[] getDetails()Read-only property that returns an array of all detail DataSets associated with this master DataSet.
public final boolean isDisplayErrors() public final void setDisplayErrors(boolean displayErrors)Determines whether the DBExceptionDialog displays or not when an Exception is generated.
public final boolean isEditable() public final void setEditable(boolean editable)If true, edits to this DataSet from a UI control are not allowed; if false, edits from a UI control are allowed. If an edit is attempted when this property is set to true, a ValidationException is thrown. UI controls have default error handling that display this in a StatusControl or JdbStatusLabel, if one is present. If there is no status control, the error is displayed in an error dialog. If this property is set on a DataSetView, only that view is affected by this setting.
public final boolean isEditing()Read-only property that returns whether the DataSet is being edited or not.
public final boolean isEditingNewRow()Read-only property that returns whether data is being added to a new row in the DataSet or not.
public final boolean isEmpty()Read-only property that returns whether the DataSet is empty or contains data.
public final boolean isEnableDelete() public final void setEnableDelete(boolean enable)Enables/disables row deletions. If a delete is attempted, a ValidationException is thrown. UI controls have default error handling that display this in a StatusControl, if one is present. If there is no StatusControl, the error is displayed in an error dialog. If this property is set on a DataSetView, only that view is affected by this setting.
public final boolean isEnableInsert() public final void setEnableInsert(boolean enable)Enables/disables row insertions. If a row insertion is attempted, a ValidationException is thrown. UI controls have default error handling that display this in a StatusControl, if one is present. If there is no StatusControl, the error is displayed in an error dialog. If this property is set on a DataSetView, only that view is affected by this setting.
public final boolean isEnableUpdate() public final void setEnableUpdate(boolean enable)Enables/disables row updates. If a row update is attempted, a ValidationException is thrown. UI controls have default error handling that display this in a StatusControl, if one is present. If there is no StatusControl, the error is displayed in an error dialog. If this property is set on a DataSetView, only that view is affected by this setting.
public final long getInternalRow()Returns a unique identifier for the current row. Can be used by the goToInternalRow method to reposition the current row position. The internalRow assignment for a row never changes, and is never reused by another row. Setting this property is the fastest way to navigate to an arbitrary row.
public final String getLastColumnVisited() public final void setLastColumnVisited(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.
public MasterLinkDescriptor getMasterLink() public synchronized void setMasterLink(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 and is applicable for any StorageDataSet implementation, for example, QueryDataSet. This property can be used with a DataSetView component only if the fetchAsNeeded property of the MasterLinkDescriptor if false.
public boolean isOpen()Read-only property that returns whether the DataSet is open or not.
public final int getRow()Returns current row position.
public final int getRowCount()Returns the number of rows visible with this DataSet. This number may be different than the number of rows in the associated StorageDataSet if a RowFilterListener is being used to filter out some rows of the DataSet.
Also, when a Provider, such as the QueryProvider used by QueryDataSet, is loading rows asynchronously, attempting to access the DataSet data or rowCount property may lead to unexpected results. This is due to the way the rows are being loaded. The rowCount will continue to increase as 0 or more rows are loaded, until the asynchronous load operation is completed.
public final RowFilterListener getRowFilterListener()Read-only property that returns the registered RowFilterListener of the DataSet.
public String getSchemaName()Read-only property that returns the schema name.
public final SortDescriptor getSort() public final void setSort(SortDescriptor descriptor)Specifies the SortDescriptor object where properties that define the sort order of the data in a DataSet are stored.
Setting the sort descriptor generates a dispatch to the registered AccessListener object. On error, setSort() generates a DataSetException.
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 com.borland.dx.dataset.RowStatus variables.
// Code checks whether the row has been newly inserted or the
// inserted row resolved back to the data source. If so, processing code is executed.
if ( (queryDataSet1.getStatus() & (RowStatus.INSERTED) ) != 0)
{
// processing code here
}
public final StorageDataSet getStorageDataSet()Read-only property that specifies the name of the StorageDataSet object that manages the storage of the rows operated on by the DataSet.
public String getTableName()Read-only property that 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 the setTableName() property of StorageDataSet 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.
public final void addRow(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 new row is validated against data constraints (if any) to ensure that only valid data is added.
This method adds a new, unposted "pseudo" row into the DataSet. Until post() is called, this row will not be visible to DataSetView components that are sharing the same StorageDataSet. After addRow() has been called, values can be set in the pseudo row by calling DataSet set methods.
When the post() method is called, the unposted row is stored in the StorageDataSet and becomes visible by DataSetViews sharing the same StorageDataSet. When the row is posted, and the sort property is not set, the current row in the DataSet will change to the newly-posted row at the end of the DataSet. If the DataSet sort property is set, the current row of the DataSet will be the newly-posted row, displayed in its sorted position within the DataSet.
Many navigating methods will cause an unposted row to be automatically posted. In this case, the new row appears to "fly away" to its proper position, which may be at the end of current rows if the sort property is null, or to its sorted position if the sort property is not null. In these cases, the current row is not necessarily (and is not likely to be) the newly-posted row. Instead the cursor is positioned according to the navigating request. For example, if the prior() method is called while an unposted row exists, the new row will be posted into the StorageDataSet according to the sort property setting, but the current row position will be one row up.
public final Variant[] allocateValues()Allocates an array of Variants for all the Columns in the DataSet.
public final boolean atFirst()Returns true if the current position is the first visible row of DataSet, otherwise, this method returns false. This method is the equivalent of the BOF() (beginning of file) function that is available in many programming languages.
public final boolean atLast()Returns true if the current position is the last visible row of DataSet, otherwise, this method returns false. This method is the equivalent of the EOF() (end-of-file) function available in many programming languages.
public final void cancel()Cancels the edits to a new or existing record. On error, this method throws a DataSetException.
public void cancelLoading()Cancels the loading of data into the DataSet. This method can be used to terminate a long running asynchronous provider operation. The QueryProvider used by QueryDataSet has Load options that allow it to load query results into a StorageDataSet asynchronously on a separate thread. Calling this method will cause such an operation to terminate.
public void cancelOperation()Cancels any long running operation currently active on this DataSet. This includes loading a query result, restructure operations, and index building operations. For this have an effect, the long running operation must be executing on a different thread than the thread that calls this method.
public final boolean canNavigate(Column column, int row)Returns whether the specified column can be navigated to (true) or not (false). This method returns false if a Column's readOnly property is set to true. This method is typically used by visual components.
public final boolean canSet(Column column)Returns whether the values at the current row and specified Column can be edited.
public final void clearStatus()Instructs all status listeners (for example, the StatusBar control) to clear their status messages.
public final DataSetView cloneDataSetView()Copies the DataSetView and returns the copied object. On error, this method throws a DataSetException.
public boolean close()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 be to garbage-collected. Otherwise, the instantiated DataSetView remains allocated in memory as long as its associated StorageDataSet cannot be garbage-collected.
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.
public boolean columnIsVisible(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.
public final void deleteAllRows()Deletes all rows of data visible in the DataSet. If called on a detail DataSet, only the rows in the current group are deleted. Deletion status information is tracked for resolution back to the original data source. If all rows of the DataSet cannot be deleted, this method throws a DataSetException.
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.
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. If the current row is an existing row, and you want to copy the contents of the previous row to it, set dittoExisting to true. By default, dittoExisting is false, as copying over the contents of an existing row could cause data loss.
public void dittoRow(boolean dittoExisting, boolean autoInsert)Copies the contents of the previous row to the current row. Does nothing if the current row is the first row.
public synchronized boolean dropIndex()Deletes the index (if applicable) that maintains the sort order created according to the sort property and the rowFilter event of the DataSet.
public final void editRow()Edits the existing row of the DataSet. When the edits are posted, the row's status flag is set to UPDATED. On failure, this method throws a DataSetException.
public final void emptyAllRows()This method calls the emptyRow() method for all rows visible in the DataSet. If called on a detail DataSet, only the rows in the current group are emptied.
The emptied rows are not marked as deleted rows. However, they are completely forgotten and cannot be resolved back to a data source.
public final void emptyRow()Empty the current DataSet row. The emptied row is not marked as deleted. However, it is completely forgotten and cannot be resolved back to a data source.
public void enableDataSetEvents(boolean enable)Affects whether data-aware controls ignore changes or repaint as a result of programmatic changes to the position and general state of a DataSet. A control cannot repaint properly while the DataSet events 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. You may also want to execute this method to propagate changes made to a DataSet object's structure to a control that is bound to the DataSet.
public final void first()Moves the row position to the first row visible to the DataSet and sends a NavigationEvent to registered NavigationListeners if the move was successful. This may cause the inBounds() method to return true if more than one row exists.
public final void getDataRow(DataRow dataRow)Returns all the values at the current row.
public final void getDataRow(int row, DataRow dataRow)Returns all the values at row.
public final synchronized DataSet getDetail(String tableName)Returns the detail DataSet with given tableName property setting. This method throws a DataSetException.UNKNOWN_DETAIL_NAME if there is no detail with tableName. It is possible (but not likely) that more than one detail has the same tableName.
public final void getDisplayVariant(int ordinal, int row, Variant value)Called by data-aware controls. Sets the value parameter to the value that should be displayed in the visual control. Normally this is the same as what getVariant(int, int, com.borland.dx.dataset.Variant) returns. If the column at the ordinal position has its pickList property set, the value parameter may be initialized to the value from another column in a separate pick list DataSet. This provides the capability to store a compact "code" value, but display a more "descriptive" value. This behavior is enabled when the column at position ordinal has its calcType property set to LOOKUP and it has a defined PickListDescriptor with its lookupDisplayColumn property set to a column name in the pick list DataSet. On error, this method throws a DataSetException.
public final void getVariant(int ordinal, int row, Variant value)Assigns the value stored at the intersection of the specified Column and row to value.
public final void getVariant(String columnName, int row, Variant value)Assigns the value stored at the intersection of the specified columnName and row to value.
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.
public final boolean goToInternalRow(long newInternalRow)Attempts to navigate to newInternalRow. If newInternalRow no longer exists, position remains unchanged. Returns true for success.
public void goToRow(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.
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.
public final synchronized DataSet hasDetail(String tableName)Returns the detail DataSet with given tableName property setting or null if there is no detail with tableName.
public final boolean hasValidations()Returns true if validation constraints are in affect for this row.
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
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.public final void insertRow(boolean before)
Start editing a new row. The before parameter indicates whether to insert before or after the current row.
This method adds a new, unposted "pseudo" row into the DataSet. Until post() is called, this row will not be visible to DataSetView components that are sharing the same StorageDataSet. After insertRow() has been called, values can be set in the pseudo row by calling DataSet set methods. The insertRow() method provides the functionality of row inserting in data aware visual components.
When the post() method is called, the unposted row is stored in the StorageDataSet and becomes visible by DataSetViews sharing the same StorageDataSet. When the row is posted, and the sort property is not set, the current row in the DataSet will change to the newly-posted row at the end of the DataSet. If the DataSet sort property is set, the current row of the DataSet will be the newly-posted row, displayed in its sorted position within the DataSet.
Many navigating methods will cause an unposted row to be automatically posted. In this case, the new row appears to "fly away" to its proper position, which may be at the end of current rows if the sort property is null, or to its sorted position if the sort property is not null. In these cases, the current row is not necessarily (and is not likely to be) the newly-posted row. Instead the cursor is positioned according to the navigating request. For example, if the prior() method is called while an unposted row exists, the new row will be posted into the StorageDataSet according to the sort property setting, but the current row position will be one row up.
public void interactiveLocate(String text, String locateColumnName, int locateOptions, boolean enterPressed)Searches the specified Column of the DataSet for the value specified in text.
public final boolean isModified(int ordinal)Returns true if the value at the specified ordinal has been modified.
public final boolean isModified(String columnName)Returns true if the value at the specified columnName has been modified.
public final boolean isNew(int row)Returns whether the row indicated by the row parameter is new (true). Otherwise, this method returns false.
public final void last()Moves the current position to the last row visible to the DataSet and sends a NavigationEvent notification to registered NavigationListeners if the move was successful. This may cause the inBounds() to return true if more than one row exists.
If an edit is in progress, the changes are posted prior to performing the move operation. On failure, this method throws a DataSetException.
public final boolean locate(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 DataRow. If the row is scoped to a specific set of columns, only those columns are used for the locate.
public final boolean lookup(ReadRow locateRow, 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" DataRow that includes only the columns of interest.
public final int moveRow(int delta)For DataSets that have the Sort.SortAsInserted property set to true, this method can be used to move the row.
public final boolean next()Moves the row position to the next row visible to the DataSet and sends a NavigationEvent notification of rowChanged to its registered NavigationListeners if the move was successful. The inBounds() method returns false if next() is called when the DataSet is positioned at the last visible row.
On failure, this method throws a DataSetException.
public boolean open()If the DataSet is not open, this method attempts to open the DataSet. The method returns true if the DataSet can be successfully opened. If the DataSet is already open, the method returns false. If an error was encountered opening the DataSet, a DataSetException is thrown.
public final synchronized void openDetails()Call this method on a master DataSet to force all details to open. By default, a detail will ask its master DataSet to open, but a master DataSet does not ask the detail DataSet to open.
public final boolean post()If a new or existing record is being edited, calling post() force the record to be posted. If this method is called for an unposted row, the row will be posted in the StorageDataSet with a RowStatus of INSERTED. If the sort property is not set, the new row will be positioned at the end of the StorageDataSet. If the sort property is set, the row will be positioned according to the sort property setting.
If called for an existing row, the RowStatus for that row is UPDATED, if it does not already have the RowStatus of INSERTED. As with new rows, it will be positioned according to the sort property setting.
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.
public final boolean prior()Moves the row position to the previous row visible to the DataSet and sends a NavigationEvent notification of rowChanged to its registered NavigationListeners if the move was successful. This will cause the inBounds() method to return false if prior() is called when the DataSet is positioned at the first visible row. On error, this method throws a DataSetException.
public void refetchRow(ReadWriteRow row)Refetches the specified row if the DataSet has a data provider (for example, QueryDataSet and ProcedureDataSet) that supports this operation.
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.
public void refresh()Refreshes the data from the DataSet if the data provider supports this operation (for example, QueryDataSet and ProcedureDataSet). On error, this method throws a DataSetException.
public boolean refreshSupported()Returns whether a refresh operation is supported. For example, QueryDataSet and ProcedureDataSet components return true.
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.
public void resetPendingStatus(boolean resolved)Reset the status bits of the rows marked pending during resolution.
public void resetPendingStatus(long internalRow, boolean resolved)Reset the status bits of a specific row.
public void saveChanges()Saves changes made to the data in the DataSet back to the data source using default QueryResolver behavior.
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 if the resolver property is not set.
public void setDefaultValues()Initializes the current row to default values of all columns. If the DataSet is a detail DataSet of a master-detail relationship, this method also initializes the detail linking columns.
public final void setDisplayVariant(int ordinal, Variant value)Called by data aware controls. Sets the value parameter to the value that should be displayed in the visual control. Normally this is the same as what getVariant(int, int, com.borland.dx.dataset.Variant) returns.
If the column at the ordinal position has its pickList property set, the value parameter may be initialized to the value from another column in a separate pick list DataSet. This provides the capability to store a compact "code" value, but display a more "descriptive" value. This behavior is enabled when the column at position ordinal has its calcType property set to LOOKUP and it has a defined PickListDescriptor with its lookupDisplayColumn property set to a column name in the pick list DataSet.
On error, this method throws a DataSetException.
public final void startEdit(Column column)Calls editRow() if the column can be edited. Throws a DataSetException if editing of the column is not allowed.
public final void startEditCheck(Column column)Throws an exception that has informative error message if editing of column cannot be allowed.
public void statusMessage(int code, String message)
public synchronized void toggleViewOrder(String columnName)Toggles the view order of the DataSet from ascending to descending (and vice versa) given the values in the specified columnName.
public final void updateRow(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.
public final void validate()Applies min, max, required, and precision checks. Calls Column.validate() method if it is set. Note that these checks will be made as data is edited in the DataSet, and when the changes are saved back to the database.
public void validate(ReadRow readRow)Applies min, max, required, precision checks. Calls the Column.validate() method if it is set. These checks will be made as data is edited in the DataSet, and when the changes are saved back to the database.
public final void addAccessListener(AccessListener listener) public final void removeAccessListener(AccessListener listener)
public final void addDataChangeListener(DataChangeListener listener) public final void removeDataChangeListener(DataChangeListener listener)
public final void addMasterNavigateListener(MasterNavigateListener listener) public final void removeMasterNavigateListener(MasterNavigateListener listener)
public final void addNavigationListener(NavigationListener listener) public final void removeNavigationListener(NavigationListener listener)
public final void addOpenListener(OpenListener listener) public final void removeOpenListener(OpenListener listener)
public final void addRowFilterListener(RowFilterListener listener) public final void removeRowFilterListener(RowFilterListener listener)
public final void addStatusListener(StatusListener listener) public final void removeStatusListener(StatusListener listener)