borland.jbcl Packages borland.jbcl Class Hierarchy borland.jbcl.dataset
java.lang.Object +----borland.jbcl.dataset.ReadRow +----borland.jbcl.dataset.ReadWriteRow +----borland.jbcl.dataset.DataSet +----borland.jbcl.dataset.StorageDataSet +----borland.jbcl.dataset.DataSetView
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.
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.
public final boolean isDisplayErrors() public final void setDisplayErrors(boolean displayErrors)Determines whether the ExceptionDialog displays or not when an Exception is generated.
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 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.
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.
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.
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 differ with rows in associated DataSet.
public final RowFilterListener getRowFilterListener()Read-only property that returns the registered RowFilterListener of the DataSet.
public final String getSchemaName()
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.
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.
public final StorageDataSet getStorageDataSet()Write-only property that specifies the StorageDataSet object that is the data storage implementation for the DataSet.
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.
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:
public final boolean atFirst()Returns true if the current position is the first visible row of DataSet, otherwise, this method returns false.
public final boolean atLast()Returns true if the current position is the last visible row of DataSet, otherwise, this method returns false.
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:
public final boolean canSet(borland.jbcl.dataset.Column column)Can edit values at column and row.
public final void cancel()Cancels the edits to a new or existing record. On error, this method throws a DataSetException.
public final void cancelLoading()Cancels the loading of data into the DataSet.
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()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.
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:
public final void dataChangeListenersDispatch(borland.jbcl.dataset.DataChangeEvent event)
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.
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 or if the current row is an exising row.
public final void editRow()Edits the existing row of the DataSet. On failure, this method throws a DataSetException.
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.
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.
public final void getDataRow(borland.jbcl.dataset.DataRow dataRow)Returns all the values at the current row.
Parameters:
public final void getDataRow(int row, borland.jbcl.dataset.DataRow dataRow)Returns all the values at row.
Parameters:
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:
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:
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:
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:
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:
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:
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.
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:
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:
public final boolean isNew(int row)Returns whether the row indicated by the row parameter is new (true). Otherwise, this method returns false.
Parameters:
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.
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:
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:
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).
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.
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).
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:
public final boolean post()Saves the current row to the DataSet. On error, this method throws a DataSetException
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 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.
public void refetchRow(borland.jbcl.dataset.ReadWriteRow row)Refetches the specified row.
Parameters:
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. On error, this method throws a DataSetException.
public boolean refreshSupported()Returns whether a refresh operation is supported.
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 final void resolvePending(boolean resolved)Method used internally when resolving changes.
public final int row()Returns the unique row identifier for the current row position.
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.
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.
public void setDefaultValues()Sets all values in the current row of the DataSet to its default values.
Overrides: borland.jbcl.dataset.ReadWriteRow.setDefaultValues()
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.
public synchronized void toggleViewOrder(java.lang.String columnName)
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.
public final void addAccessListener(borland.jbcl.dataset.AccessListener listener) public final void removeAccessListener(borland.jbcl.dataset.AccessListener listener)
public final void addDataChangeListener(borland.jbcl.dataset.DataChangeListener listener) public final void removeDataChangeListener(borland.jbcl.dataset.DataChangeListener listener)
public final void addMasterNavigateListener(borland.jbcl.dataset.MasterNavigateListener listener) public final void removeMasterNavigateListener(borland.jbcl.dataset.MasterNavigateListener listener)
public final void addNavigationListener(borland.jbcl.dataset.NavigationListener listener) public final void removeNavigationListener(borland.jbcl.dataset.NavigationListener listener)
public final void addOpenListener(borland.jbcl.dataset.OpenListener listener) public final void removeOpenListener(borland.jbcl.dataset.OpenListener listener)
public final void addRowFilterListener(borland.jbcl.dataset.RowFilterListener listener) public final void removeRowFilterListener(borland.jbcl.dataset.RowFilterListener listener)
public final void addStatusListener(borland.jbcl.dataset.StatusListener listener) public final void removeStatusListener(borland.jbcl.dataset.StatusListener listener)