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

StorageDataSet class (abstract)

java.lang.Object
   +----borland.jbcl.dataset.ReadRow
           +----borland.jbcl.dataset.ReadWriteRow
                   +----borland.jbcl.dataset.DataSet
                           +----borland.jbcl.dataset.StorageDataSet
                                   +----borland.jbcl.dataset.TableDataSet
                                   +----borland.jbcl.dataset.ProcedureDataSet
                                   +----borland.jbcl.dataset.QueryDataSet
                                   +----borland.jbcl.dataset.HelpDataSet

About the StorageDataSet class

Variables  Properties  Methods  Event Listeners

Implements AccessListener, MasterNavigateListener, StatusListener, EventListener

The StorageDataSet class extends the basic cursor functionality provided by its superclass DataSet with:

The StorageDataSet class is extended by QueryDataSet, ProcedureDataSet, and TableDataSet components. The QueryDataSet and ProcedureDataSet work with a Database component to obtain data from a remote server through the use of a query or stored procedure. You can also load data stored in a text file into a TableDataSet object. Once data is loaded into a StorageDataSet object, you handle the data in a common way regardless of how the data was obtained or which StorageDataSet implementation you use.

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.


StorageDataSet variables

Variables implemented in borland.jbcl.dataset.ReadRow

StorageDataSet properties

*Read-only properties **Write-only properties

Properties implemented in this class

Properties implemented in borland.jbcl.dataset.DataSet

Properties implemented in borland.jbcl.dataset.ReadRow

Properties implemented in borland.jbcl.dataset.ReadWriteRow

Properties implemented in java.lang.Object

StorageDataSet methods

Methods implemented in this class

Methods implemented in borland.jbcl.dataset.DataSet

Methods implemented in borland.jbcl.dataset.ReadRow

Methods implemented in borland.jbcl.dataset.ReadWriteRow

Methods implemented in java.lang.Object

StorageDataSet event listeners


StorageDataSet properties

columns

 public Column[] getColumns()
 public synchronized void setColumns(borland.jbcl.dataset.Column[] columns)
Specifies the Column components in the StorageDataSet where columns is an array of Column components.

dataFile

 public final DataFile getDataFile()
 public void setDataFile(borland.jbcl.dataset.DataFile dataFile)
Specifies the DataFile implementation used for file import and export operations. This property defaults to TextDataFile.

editable

 public final boolean isEditable()
 public final void setEditable(boolean editable)
Determines whether edits to this DataSet are allowed from a UI control (true), or not (false). This property does not prevent programmatic edits to the data in the DataSet. To prevent edits both programmatically and through data-aware controls, set the readOnly property of the DataSet.

locale

 public Locale getLocale()
 public void setLocale(java.util.Locale locale)
The Locale for the StorageDataSet.

matrixData

 public MatrixData getMatrixData()

maxDesignRows

 public final synchronized int getMaxDesignRows()
 public final synchronized void setMaxDesignRows(int maxDesignRows)
Limits the number of rows that can be initially loaded into a DataSet in the UI Designer. The default is to load 50 rows. If the limit is reached, only that number of rows is displayed; no message is displayed nor is any Exception thrown.

maxRows

 public final synchronized int getMaxRows()
 public final synchronized void setMaxRows(int maxRows)
Limits the number of rows that can initially be loaded into the DataSet when running the application or applet. Also called a governor. The setMaxRows() method has no effect on rows added after the initial loading of data, for example, from a query or import specification.

This property defaults to -1 which indicates that there is no limit to the number of rows that can be initially loaded into a DataSet. No message is displayed nor is any Exception thrown when the limit is reached, however, only that number of rows is included in the DataSet when it is loaded with data. With long running queries that can possibly return large result sets, it is advisable to specify the maxRows property since the maximum number of rows defaults to unlimited.

metaDataUpdate

 public final int getMetaDataUpdate()
 public final void setMetaDataUpdate(int metaDataUpdate)

needsRestructure

 public final boolean getNeedsRestructure()
Returns true for StorageDataSet components when structural changes have occurred (add, drop, move, change column) and the store being used requires a restructure. After a successful restructure, getNeedsRestructure() returns false.

readOnly

 public final boolean isReadOnly()
 public final void setReadOnly(boolean readOnly)
Specifies whether updates to the DataSet are permitted. If true, updates to the DataSet are not allowed, otherwise the DataSet can be updated.

The table name is normally retrieved automatically from the data source. Some stored procedures and queries however will not return the table name. If it doesn't, the DataSet will be set to read-only. Also, if the data in the query or stored procedure is the result of a join between two or more tables, the DataSet will be read-only.

If the data in the DataSet is from a single table, you can attempt setting the DataSet to read-write by calling the setReadOnly() method with the false parameter. If the cause of the read-only status is a null value for the tableName property, use the setTableName() method to set the name of the data source, followed by a call to the setUpdatable() method.

To prevent edits to the DataSet through data-aware controls only (permitting programmatic edits), set the editable property.

resolver

 public Resolver getResolver()
 public void setResolver(borland.jbcl.dataset.Resolver resolver)
Specifies the Resolver object to use that defines resolver logic when saving data changes back to the data source.

schemaName

 public synchronized void setSchemaName(java.lang.String schemaName)
Write-only property for the table name of the data source for the Column components of this StorageDataSet. If a DataSet has any updatable Column components, this property must reflect the table name of the data source.

storageOpen

 public final boolean isStorageOpen()

store

 public final Store getStore()
 public final void setStore(borland.jbcl.dataset.Store store)
Sets the storage for the DataSet; the default is memory storage. This property allows for future development of other storage schemes.

storeName

 public final String getStoreName()
 public synchronized void setStoreName(java.lang.String storeName)
If the store property component supports naming of a DataSet components in the Store, this can be set. If this property is null, the tableName property is returned.

The default store is MemoryStore, which does not support naming of DataSet components.

tableName

 public synchronized void setTableName(java.lang.String tableName)
Stores the name of the table from which the DataSet obtains its data. If a DataSet has any updatable columns, the name of the table for these columns is stored as tableName.

The table name 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 name so that changes made to the DataSet can be resolved back to the data source, and follow it by a call to the setUpdatable() method. The table name is also useful as a String identifier of the data source.

updatable

 public final boolean isUpdatable()
 public final void setUpdatable(boolean updatable)
This method is used internally by the JBCL to advise that a DataSet cannot be updated. This can occur if the DataSet has insufficient metadata to resolve changes back to the original datasource. This can also occur if the data in the DataSet is the result set of a join query.

For more information on metadata, see the Working with Columns topic in the Database Application Developer's Guide.


StorageDataSet methods

addColumn(borland.jbcl.dataset.Column)

  public final int addColumn(borland.jbcl.dataset.Column column)
Adds a Column to the end of existing columns in the StorageDataSet. Row values for the added Column are set to null. The return value int indicates the ordinal position of the newly-added Column. On error, this method throws a DataSetException.

Parameters:

column
The Column component to add to the StorageDataSet.

addColumn(java.lang.String, int)

  public final int addColumn(java.lang.String columnName, int datatype)
Adds a Column to a DataSet where columnName indicates the String name of the Column and dataType is the data type of the Column. The Column is added at the end of all existing columns. The return value int indicates the ordinal position of the newly-added Column. On error, this method throws a DataSetException.

Parameters:

columnName
The String name of the Column component to add to the StorageDataSet.
datatype
The data type of the data in the Columm. Valid values for this parameter are defined in borland.jbcl.util.Variant variables.

addColumn(java.lang.String, java.lang.String, int)

  public final int addColumn(java.lang.String columnName, java.lang.String colLabel, int dataType)
Adds a Column to the end of existing columns in a DataSet. Row values for the added Column are set to null. The return value int indicates the ordinal position of the newly-added Column. On error, this method throws a DataSetException.

Parameters:

columnName
The String name of the Column by which you refer to it most of the time.
colLabel
The name of the (displayed) label for the Column in a data-aware control. You may want to use a more descriptive name than columnName.
dataType
The data type of the field to be added. Valid values for this parameter are described in borland.jbcl.util.Variant Variables.

addUniqueColumn(borland.jbcl.dataset.Column)

  public final int addUniqueColumn(borland.jbcl.dataset.Column column)
Adds a Column to the DataSet only if it does not already exist. The specified column is cloned before being added to the DataSet. The return value int indicates the ordinal position of the newly-added Column. On error, this method throws a DataSetException of COLUMN_TYPE_CONFLICT.

Parameters:

column
The Column component to add to this StorageDataSet.

allocateValues()

  public final Variant[] allocateValues()
Allocates an array of Variant objects for all Column objects of the current row of the DataSet. This is used internally in the JBCL; for most situations, use the borland.jbcl.dataset.DataRow component.

calcFields(borland.jbcl.dataset.ReadWriteRow, boolean)

  public void calcFields(borland.jbcl.dataset.ReadWriteRow changedRow, boolean isPosted)

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

  public final synchronized void changeColumn(int oldOrdinal, borland.jbcl.dataset.Column newColumn)
Changes the Column at ordinal position to match the properties in newColumn. The newColumn parameter must be a separate Column instance from the one stored at position oldOrdinal in this StorageDataSet. To ensure this, clone the target Column before making changes to it.

Parameters:

oldOrdinal
The ordinal position of the Column to update.
newColumn
The Column component to match properties of.

checkMasterDetail(borland.jbcl.dataset.MasterLinkDescriptor)

  public void checkMasterDetail(borland.jbcl.dataset.MasterLinkDescriptor masterDetailDescriptor)

cloneColumns()

  public Column[] cloneColumns()
Array property for setting columns.

cloneDataSetStructure()

  public final synchronized StorageDataSet cloneDataSetStructure()
Creates a new empty StorageDataSet object with identical structure as the current StorageDataSet.

closeStorage(int)

  public final boolean closeStorage(int reason)
Closes the DataSet and notifies any accessListeners of this event. Returns true if the StorageDataSet was open. On error, this method throws a DataSetException.

Parameters:

reason
The reason for the notification. Valid values are defined in AccessEventvariables.

dropColumn(borland.jbcl.dataset.Column)

  public final void dropColumn(borland.jbcl.dataset.Column column)
Deletes the specified Column object (and all the data it contains) from the DataSet. If the Column cannot be dropped, this method throws a DataSetException.

Parameters:

column
The Column component to drop from this StorageDataSet.

dropColumn(java.lang.String)

  public final void dropColumn(java.lang.String columnName)
Deletes the specified Column object (and all the data it contains) from the DataSet where the Column is identified by its String column name. If the Column cannot be dropped, this method throws a DataSetException.

Parameters:

columnName
The String name of the Column component to drop from this StorageDataSet.

empty()

  public final synchronized void empty()
Empties all rows of the DataSet and resets the DataSet to contain no rows. All change state information (inserted, deleted, changed) is lost and therefore, nothing remains in the DataSet to be resolved back to the original data source. On error, this method generates a DataSetException.

endLoading()

  public final void endLoading()
Stops the loading of data into the StorageDataSet. Any row that has not been completely loaded is set to null. On error, this method throws a DataSetException.

endResolution()

  public synchronized void endResolution()
Ends the resolution of data changes back to the data source.

failIfOpen()

  protected void failIfOpen()
This property is used internally by other classes in the JBCL. You should never use this property directly.

freeAllIndexes()

  public void freeAllIndexes()
Releases all indexes used by this StorageDataSet. Can be used to save memory after viewing the data in the StorageDataSet in many different sort orders.

getDeletedRows(borland.jbcl.dataset.DataSetView)

  public final synchronized void getDeletedRows(borland.jbcl.dataset.DataSetView deleteDataSet)
Creates a DataSetView object, deleteDataSet, that displays only the deleted rows in the current DataSet. On error, this method generates a DataSetException.

Parameters:

deleteDataSet
The DataSetView created by this method that includes only deleted rows.

getInsertedRows(borland.jbcl.dataset.DataSetView)

  public final synchronized void getInsertedRows(borland.jbcl.dataset.DataSetView insertDataSet)
Creates a DataSetView object, insertDataSet, that displays only the inserted (new) rows in the current DataSet. On error, this method generates a DataSetException.

Parameters:

insertDataSet
The DataSetView returned by this method that includes only inserted rows.

getOriginalRow(borland.jbcl.dataset.DataSet, borland.jbcl.dataset.DataRow)

  public final void getOriginalRow(borland.jbcl.dataset.DataSet changeDataSet, borland.jbcl.dataset.DataRow originalRow)
Creates a DataRow component that contains the original values of the data in a row of a DataSet that has been changed. On error, this method generates a DataSetException.

Parameters:

changeDataSet
The DataSet containing changed rows of data.
originalRow
The returned DataRow that contains the original, unmodified values of the data in the modified row.

getUpdatedRows(borland.jbcl.dataset.DataSetView)

  public final synchronized void getUpdatedRows(borland.jbcl.dataset.DataSetView updateDataSet)
Creates a DataSetView object that displays only the updated rows in the current DataSet. On error, this method generates a DataSetException.

Parameters:

updateDataSet
The DataSetView that is created by this method that contains only updated rows.

hasRowIds()

  public final synchronized boolean hasRowIds()
Returns whether the DataSet has any unique row identifiers. If at least one exists, this method returns true.

loadDetailRows(borland.jbcl.dataset.DataSet, borland.jbcl.dataset.DataSet)

  public abstract void loadDetailRows(borland.jbcl.dataset.DataSet detailDataSet, borland.jbcl.dataset.DataSet masterDataSet)

loadRow()

  public final void loadRow()

moveColumn(int, int)

  public final synchronized void moveColumn(int oldOrdinal, int newOrdinal)
Moves a Column at the specified ordinal postion to a new ordinal position. If either parameter is invalid, a DataSetException of type INVALID_COLUMN_POSITION is thrown.

Parameters:

oldOrdinal
The ordinal position of the Column component to move.
newOrdinal
The ordinal position where the Column should be moved to.

openStorage(borland.jbcl.dataset.DataSet, borland.jbcl.dataset.AccessEvent)

  protected synchronized boolean openStorage(borland.jbcl.dataset.DataSet dataSet, borland.jbcl.dataset.AccessEvent event)
This method is used internally by other classes in the JBCL. You should never use this method directly.

postAllDataSets()

  public void postAllDataSets()
Attempts to post any unposted rows in the DataSet and DataSetView components that share the same StorageDataSet property. On error, this method throws a DataSetException.

Overrides: borland.jbcl.dataset.DataSet.postAllDataSets()

recalc()

  public final synchronized void recalc()
Forces a recalculation of any calculated columns in the StorageDataSet.

refresh()

  public void refresh()
Refreshes data from the data source of the StorageDataSet.

Overrides: borland.jbcl.dataset.DataSet.refresh()

refreshSupported()

  public boolean refreshSupported()
Returns true if the data source of the StorageDataSet supports refresh operations. Otherwise, this method returns false.

Overrides: borland.jbcl.dataset.DataSet.refreshSupported()

replaceColumns(borland.jbcl.dataset.Column[], boolean)

  protected int[] replaceColumns(borland.jbcl.dataset.Column[] columns, boolean accumulateResults)
This method is used internally by other classes in the JBCL. You should never use this method directly.

restructure(boolean)

  public final void restructure(boolean recalc)

saveChanges(borland.jbcl.dataset.DataSet)

  public void saveChanges(borland.jbcl.dataset.DataSet dataSet)
Saves changes made to the data in the StorageDataSet back to its data source. This method is applicable only for JDBC data sources that support data resolution. Text file data sources (typically) do not support this feature, therefore, TableDataSet components do not. To save changes back to a text file, see the Exporting data topic in the Database Application Developer's Guide.

saveChangesSupported()

  public boolean saveChangesSupported()
Returns true if the data source supports resolving changes made to the StorageDataSet, (false) if not.

Overrides: borland.jbcl.dataset.DataSet.saveChangesSupported()

setAllRowIds(boolean)

  protected final synchronized void setAllRowIds(boolean setting)
This method is used internally by other classes in the JBCL. You should never use this method directly.

setRowId(java.lang.String, boolean)

  public final synchronized void setRowId(java.lang.String columnName, boolean setting)
Specifies whether the named Column component uniquely identifies a row in the server table where changes made to this StorageDataSet will be saved back to, or the named Column is one of a group of Column components that uniquely identifies a row. A false value indicates that the specified Column is not (part of) a unique row identifier (rowId).

startLoading(borland.jbcl.dataset.LoadCancel, int, boolean)

  public final synchronized Variant[] startLoading(borland.jbcl.dataset.LoadCancel loader, int loadStatus, boolean loadAsync)

startResolution()

  public synchronized void startResolution()

usesStoredProcedure()

  public boolean usesStoredProcedure()

StorageDataSet 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)

calcAggFields

 public synchronized void addCalcAggFieldsListener(borland.jbcl.dataset.CalcAggFieldsListener listener)
 public synchronized void removeCalcAggFieldsListener(borland.jbcl.dataset.CalcAggFieldsListener listener)

calcFields

 public synchronized void addCalcFieldsListener(borland.jbcl.dataset.CalcFieldsListener listener)
 public synchronized void removeCalcFieldsListener(borland.jbcl.dataset.CalcFieldsListener listener)

dataChange

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

edit

 public void addEditListener(borland.jbcl.dataset.EditListener listener)
 public synchronized void removeEditListener(borland.jbcl.dataset.EditListener listener)

load

 public final void addLoadListener(borland.jbcl.dataset.LoadListener listener)
 public final void removeLoadListener(borland.jbcl.dataset.LoadListener 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)

storageAccess

 public final void removeStorageAccessListener(borland.jbcl.dataset.AccessListener listener)