borland Packages  Class Hierarchy  jbcl.dataset Package  Index 

StorageDataSet component

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

About the StorageDataSet component

Constructors  Properties  Methods  Event Listeners

Implements AccessListener, ColumnDesigner, MasterNavigateListener, StatusListener, Serializable, EventListener

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

The StorageDataSet component 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 execution of a query or stored procedure. You can also load data stored in a text file into a TableDataSet object. Once data is loaded (provided) into a StorageDataSet object, you handle the data in a common way, regardless of how the data was obtained or which StorageDataSet extension you use.

When making structure changes to the StorageDataSet, use the addColumn, changeColumn, dropColumn, and moveColumn methods as these methods allow for better before and after mapping. Otherwise, Column names are used for mapping, which may not always work. The Column component's preferredOrdinal property is retained when calling these StorageDataSet methods.

If your application involves a master-detail relationship, the resolveOrder property indicates the order in which changes made to the DataSets are resolved back to the data source.


StorageDataSet constructors

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.ReadWriteRow

Methods implemented in java.lang.Object

StorageDataSet event listeners


StorageDataSet constructors

StorageDataSet()

  public StorageDataSet()
Constructs a StorageDataSet component, generates a StatusEvent of StatusEvent.LOADING_DATA and sets the following properties:

StorageDataSet properties

allRowIds

 public final synchronized void setAllRowIds(boolean setting)
Sets all Column components as being unique row identifers.

calcAggFieldsListener

 public final CalcAggFieldsListener getCalcAggFieldsListener()
Read-only property that returns the CalcAggFieldsListener of the StorageDataSet.

This property was added in JBuilder 2.0.

calcFieldsListener

 public final CalcFieldsListener getCalcFieldsListener()

columns

 public synchronized void setColumns(borland.jbcl.dataset.Column[] columns)
Specifies the Column components in the StorageDataSet and sets the persist property to true for all specified columns. Any pre-existing columns are removed when this property is set.

dataFile

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

deletedRowCount

 public final int getDeletedRowCount()
Read-only property that returns the number of deleted rows not visible to this StorageDataSet

insertedRowCount

 public final int getInsertedRowCount()
Read-only property that returns the number of inserted rows visible to this StorageDataSet

locale

 public Locale getLocale()
 public synchronized void setLocale(java.util.Locale locale)
Stores the Locale used for formatting the data stored in the StorageDataSet. Locale contains country or area-specific formatting specifications such as date format (MM/DD/YY, DD/MM/YY, YY/MM/DD), currency symbol, and so on.

When set at the StorageDataSet level, this property is the default locale for all Column components in the StorageDataSet. If the StorageDataSet's locale property is null, and the store property is set to a DataStore component, the locale property of the DataStore will be used if set. If not set any level, it defaults to the locale of the Java environment.

matrixData

 public MatrixData getMatrixData()
This property is used internally by other classes in the JBCL. You should never use this property directly.

maxDesignRows

 public final int getMaxDesignRows()
 public final 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 int getMaxRows()
 public final 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 set the maxRows property since the maximum number of rows defaults to unlimited.

See also: borland.sql.dataset.Load.AS_NEEDED

metaDataUpdate

 public final int getMetaDataUpdate()
 public final synchronized void setMetaDataUpdate(int metaDataUpdate)
Determines what kind of metadata discovery is performed when executing a query or a stored procedure against a SQL server database. Valid values for this property are defined in the MetaDataUpdate interface.

To prevent the addition of row ID columns and various metadata related properties on DataSet and Column components, set this property to MetaDataUpdate.NONE.

For more information on metadata, see the topic Metadata and how it is obtained in the Database Application Developer's Guide.

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. To cause the restructure to happen, call the restructure() method or click the Restructure button in the JBuilder Column Designer. After a successful restructure, getNeedsRestructure() returns false.

A StorageDataSet that uses a MemoryStore always returns false. Currently, this method is meaningful only with DataStore use.

A StorageDataSet with pending structural changes can still be used. Moved columns can be read and written to. Deleted columns are not visible, inserted columns can be read, but not written, changed data type columns can be read but not written to.

provider

 public Provider getProvider()
 public synchronized void setProvider(borland.jbcl.dataset.Provider provider)
Specifies the Provider component that controls how the data is fetched from the database when the StorageDataSet is opened. The Client-Server edition of JBuilder includes these provider components in the JBCL:

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. (Some join queries are supported.)

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, then set the rowId and metadataupdate properties.

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

resolvable

 public final boolean isResolvable()
 public final synchronized void setResolvable(boolean resolvable)
Specifies whether to allow changes made to this DataSet to be saved back to its data source (true) or not (false).

resolveOrder

 public final String[] getresolveOrder()
 public final void setResolveOrder(java.lang.String[] resolveOrder)
A String array that specifies the resolution order for multi-table resolution. Inserts and updates use the order of the String array while deletes use the reverse order. The default order of the tables in the String array is the order by which they appear in the query statement. The tablenames should include any necessary schema names. If a table is removed from the list, then the columns from that table will not be resolved.

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 final String getSchemaName()
 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.

store

 public final Store getStore()
 public final void setStore(borland.jbcl.dataset.Store store)
Sets the storage for the DataSet. Valid values for this property are MemoryStore or DataStore. The default is MemoryStore.

With MemoryStore, DataSet data is stored in memory and released when an application closes. With DataStore, storage is persistent and file-based so that when an application closes, it can be restarted in the same state as when it was closed.

storeName

 public final String getStoreName()
 public synchronized void setStoreName(java.lang.String name)
If the store property component supports naming of a DataSet components in the Store, this can be set. The default store is MemoryStore, which does not support naming of DataSet components. This property is meaningful to and used only by DataStore.

When specified for a DataStore component, the storeName property must be unique. The value specified for storeName is case insensitive, though it is stored internally in upper case. To force a storeName to be case insensitive, enclose it in quotes, for example:

 "\"name\""

tableName

 public final String getTableName()
 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, then set the rowId and metadataupdate properties (if not already set). The table name is also useful as a String identifier of the data source.

updatedRowCount

 public final int getUpdatedRowCount()
Read-only property that returns the number of updated rows visible to this StorageDataSet

StorageDataSet methods

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. Use the enableDataSetEvents method to propagate changes to a control that is bound to this DataSet. 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 Column. 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 caption, 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.

cancelLoading()

  public final void cancelLoading()
Cancels any long running load operations currently active on this DataSet. For this have an effect, the long running loading operation must be executing on a different thread than the thread that calls this method.

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

cancelOperation()

  public final 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.

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

changesPending()

  public boolean changesPending()
Returns true if there are any inserted, deleted, or updated rows to be resolved back to the data source. If true, one or more of the following methods getUpdatedRowCount(), getDeletedCount(), or getInsertedCount() return a value greater than 0.

cloneColumns()

  public Column[] cloneColumns()
Creates a copy of all Columns in the StorageDataSet.

cloneDataSetStructure()

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

closeProvider(boolean)

  public void closeProvider(boolean loadRemainingRows)

dropAllIndexes()

  public final void dropAllIndexes()
Drops all indexes used by this StorageDataSet. For MemoryStore, this can be used to save memory after viewing the data in different sort orders. For DataStore, this frees up maintained secondary indexes, releasing disk storage. In both MemoryStore and DataStore, this can improve update performance.

dropColumn(borland.jbcl.dataset.Column)

  public final synchronized 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. dropColumn does not affect the relative order of columns but does cause a recalculation of column ordinal values.

Parameters:

column
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.

enableDataSetEventsInViews(boolean)

  public void enableDataSetEventsInViews(boolean enable)

endLoading()

  public final synchronized void endLoading()
Stops the loading of data into the StorageDataSet.

See also: startLoading(borland.jbcl.dataset.LoadCancel, int, boolean), loadRow()

freeAllIndexes()

  public final void freeAllIndexes()

getDeletedRows(borland.jbcl.dataset.DataSetView)

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

Parameters:

deleteDataSet
The DataSetView initialized by this method to includes only deleted rows.

getInsertedRows(borland.jbcl.dataset.DataSetView)

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

Parameters:

insertDataSet
The DataSetView initialized by this method to include only inserted rows.

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

  public final void getOriginalRow(borland.jbcl.dataset.DataSet updateDataSet, borland.jbcl.dataset.DataRow originalRow)
Initializes the DataRow component to contain 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 changed row.

getUpdatedRows(borland.jbcl.dataset.DataSetView)

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

Parameters:

updateDataSet
The DataSetView that is initialized by this method to contain 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.

loadRow()

  public final void loadRow()
This method allows for faster loading of a StorageDataSet. For thread safety it must be called from a synchronized method of the DataSet you are working with. If used by a derivation of StorageDataSet, add a synchronized method to the derivation to call this method from. You should also call processDataChanged() after calling loadRow() one or more times.

See also: startLoading(borland.jbcl.dataset.LoadCancel, int, boolean), endLoading()

loadRow(int)

  public void loadRow(int status)
Loads a row with the status bits as they are passed in.

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.

postAllDataSets()

  public final 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()

resetPendingStatus(boolean)

  public final void resetPendingStatus(boolean resolved)
Resets the pending bit in the status bits for a specific row.

Overrides: borland.jbcl.dataset.DataSet.resetPendingStatus(boolean)

resetPendingStatus(long, boolean)

  public final void resetPendingStatus(long internalRow, boolean resolved)

Overrides: borland.jbcl.dataset.DataSet.resetPendingStatus(long, boolean)

restructure()

  public final void restructure()
Restructures the StorageDataSet. Currently meaningful only for DataStore after a move, delete, add, or change column method call.

The needsRestructure property returns whether a restructure operation is pending. A StorageDataSet with pending structural changes can still be used, and moved columns can be read and written to. Deleted columns are not visible, inserted columns can be read but not written and changed data type columns can be read but not written to.

You can perform a restructure operation through the JBuilder Column Designer by opening the StorageDataSet and clicking the restructure button.

The restructure() method can also be used to repair or compact a StorageDataSet and its associated indexes even when there are no pending structural changes.

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. If the resolver property is null, a DataSetException of CANNOT_SAVE_CHANGES is thrown. To save changes back to a text file, see the Exporting data topic in the Database Application Developer's Guide.

Parameters:

dataSet
The DataSet containing the updated data.

saveChangesSupported()

  public boolean saveChangesSupported()
Returns true if the data source supports resolving changes made to the StorageDataSet, false if not. Typically, file-based data sources do not support data resolution. To save changes back to a text file, see the Exporting data topic in the Database Application Developer's Guide.

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

setRowId(java.lang.String, boolean)

  public final synchronized void setRowId(java.lang.String columnName, boolean setting)
Specifies that the named Column component either uniquely identifies a row in the server table where changes made to this StorageDataSet will be saved back to, or 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.

Parameters:

columnName
The String name of the Column component.
setting
A boolean value indicating the participation of the columnName in the row identifier (true) or not (false).

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

  public final synchronized Variant[] startLoading(borland.jbcl.dataset.LoadCancel loader, int loadStatus, boolean loadAsync)
This method is used for high-speed loading of data into a StorageDataSet. It returns an array of Variant objects for all columns in a DataSet. You set the values in the array and call loadRow(). When the load operation is complete, you must call endLoading. Only one load operation may be active at one time.

This method may generate a DataSetException of LOADING_NOT_STARTED.

Parameters:

loader
A call back interface that requests the load operation to be canceled. Cannot be null.
loadStatus
Boolean that determines the status of the load process. Can be RowStatus.INSERTED or RowStatus.LOADED. Normally RowStatus.LOADED is used to indicate that the row was not inserted or updated.
loadAsync
Whether the loading should be done in a separate thread. Set this paramter to true if the intention is to load the StorageDataSet using a separate thread. This will cause periodic update notifications to be sent to any data aware controls and StatusListeners.

See also: loadRow(),endLoading()

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

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

StorageDataSet event listeners

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