com.klg.jclass.datasource
Interface DataModel

All Known Implementing Classes:

HiGridData, TreeData

public interface DataModel

This is the data interface for JClass DataSource. All data for JClass DataSource is maintained and manipulated in this data model through its sub-interfaces. This data model requires the implementation of two tree models, one for describing the relationships of the hierarchical data (MetaDataModel) and one for the actual data (DataTableModel).

Method Summary

void	addDataModelListener(com.klg.jclass.datasource.DataModelListener listener) Registers a listener for this DataModel.
void	cancelAll(com.klg.jclass.datasource.DataModelListener originator) Cancels all pending changes in all DataTables.
void	clearCurrentPath(com.klg.jclass.datasource.MetaDataModel parentMeta) Clear the current path of all children of this MetaDataModel.
void	clearDataTableTreeInternalData(Object user) For internal use only.
void	clearDataTableTreeUserData(Object user) Clears all user data.
void	enableDataModelEvents(boolean value) Enables or disables data model events.
boolean	fireDataModelEvent(com.klg.jclass.datasource.DataModelEvent event) Passes event on to listeners of this DataModel.
boolean	fireDataModelEvent(com.klg.jclass.datasource.DataModelEvent event, com.klg.jclass.datasource.DataModelListener listener) Passes event on to a single specific listener of this DataModel.
Object	getCurrentDataItem(com.klg.jclass.datasource.DataModelListener originator, com.klg.jclass.datasource.MetaDataModel myLevel, String column) Returns the data item at the specified MetaData level and column for the current row.
com.klg.jclass.datasource.DataTableModel	getCurrentDataTable(com.klg.jclass.datasource.DataModelListener originator, com.klg.jclass.datasource.MetaDataModel myLevel) Returns the DataTable at the specified MetaData level based on the current bookmark.
long	getCurrentGlobalBookmark() Returns the bookmark of the row which has the global cursor's focus.
com.klg.jclass.datasource.DataTableModel	getCurrentGlobalTable() Returns the DataTableModel currently in focus.
TreeModel	getDataTableTree() Returns a handle to the DataTree.
boolean	getEventsEnabled() Returns true if events are enabled, false otherwise.
Object	getListeners() Returns a list of listeners on this DataModel.
com.klg.jclass.datasource.MetaDataModel	getMetaData(String metaDataName) Gets a MetaDataModel instance by name, or null if not found.
TreeModel	getMetaDataTree() Returns a handle to a TreeModel containing meta-data.
String	getModelName() Gets this model's name
boolean	isModified() Are there any pending modifications in any rows in this entire data model?
boolean	moveToRow(com.klg.jclass.datasource.DataModelListener originator, com.klg.jclass.datasource.DataTableModel data_table, long bookmark) Called by observers to tell this data model to which row it should move.
boolean	moveToRow(com.klg.jclass.datasource.DataModelListener originator, com.klg.jclass.datasource.DataTableModel data_table, long bookmark, boolean moveIdeCursor) For internal use only.
void	removeDataModelListener(com.klg.jclass.datasource.DataModelListener listener) Removes a listener on this DataModel.
void	requeryAll(com.klg.jclass.datasource.DataModelListener originator) Requeries all DataTables.
void	setModelName(String modelName) Sets this model's name.
void	updateAll(com.klg.jclass.datasource.DataModelListener originator) Writes all pending changes in all DataTables to the data source.

Method Detail

getMetaDataTree

public TreeModel getMetaDataTree()

Returns a handle to a TreeModel containing meta-data.

Returns:

a TreeModel which can be traversed to determine the hierarchy of the MetaDataModels.

getDataTableTree

public TreeModel getDataTableTree()

Returns a handle to the DataTree.

Returns:

a TreeModel which can be traversed to the hierarchy of DataTableModels.

addDataModelListener

public void addDataModelListener(com.klg.jclass.datasource.DataModelListener listener)

Registers a listener for this DataModel.

See Also:

DataModelListener

removeDataModelListener

public void removeDataModelListener(com.klg.jclass.datasource.DataModelListener listener)

Removes a listener on this DataModel.

See Also:

DataModelListener

moveToRow

public boolean moveToRow(com.klg.jclass.datasource.DataModelListener originator,
                         com.klg.jclass.datasource.DataTableModel data_table,
                         long bookmark)
                  throws DataModelException

Called by observers to tell this data model to which row it should move. Depending on the commit policy, moving the internal cursor may automatically commit changes to the originating data source.

Parameters:

originator - the DataModelListener which initiated this action

data_table - the DataTable to which the cursor should be moved

bookmark - a long uniquely identify to which row the cursor should move

Returns:

true if move succeeded, false otherwise

Throws:

DataModelException - If move to row fails.

moveToRow

public boolean moveToRow(com.klg.jclass.datasource.DataModelListener originator,
                         com.klg.jclass.datasource.DataTableModel data_table,
                         long bookmark,
                         boolean moveIdeCursor)
                  throws DataModelException

For internal use only. Called by observers to tell this data model to which row it should move. Depending on the commit policy, moving the internal cursor may automatically commit changes to the originating data source.

Parameters:

originator - the DataModelListener which initiated this action

data_table - the DataTable to which the cursor should be moved

bookmark - a long uniquely identify to which row the cursor should move

moveIdeCursor - a boolean indicating if this move should also cause the ide's cursor to move

Returns:

true if move succeeded, false otherwise

Throws:

DataModelException - If move to row fails.

updateAll

public void updateAll(com.klg.jclass.datasource.DataModelListener originator)
               throws DataModelException

Writes all pending changes in all DataTables to the data source.

Parameters:

originator - the DataModelListener which initiated this action

Throws:

DataModelException - If update fails.

cancelAll

public void cancelAll(com.klg.jclass.datasource.DataModelListener originator)
               throws DataModelException

Cancels all pending changes in all DataTables.

Parameters:

originator - the DataModelListener which initiated this action

Throws:

DataModelException - If changes can't be canceled.

requeryAll

public void requeryAll(com.klg.jclass.datasource.DataModelListener originator)
                throws DataModelException

Requeries all DataTables.

Parameters:

originator - the DataModelListener which initiated this action

Throws:

DataModelException - If requery fails.

getListeners

public Object getListeners()

Returns a list of listeners on this DataModel.

Returns:

an Object which is a list of listeners

fireDataModelEvent

public boolean fireDataModelEvent(com.klg.jclass.datasource.DataModelEvent event)

Passes event on to listeners of this DataModel.

Parameters:

event - a DataModelEvent

Returns:

true if the event was accepted by all listeners, or false if at least one listener vetoed the change.

fireDataModelEvent

public boolean fireDataModelEvent(com.klg.jclass.datasource.DataModelEvent event,
                                  com.klg.jclass.datasource.DataModelListener listener)

Passes event on to a single specific listener of this DataModel.

Parameters:

event - a DataModelEvent

listener - the DataModelListener

Returns:

true if the event was accepted by the listener, or false if the listener vetoed the change.

enableDataModelEvents

public void enableDataModelEvents(boolean value)

Enables or disables data model events. When disabled, events are not dispatched to registered listeners. This is useful for making mass changes without having listeners repainting on each change. That is, set enabled to false, make the changes, then set back true.

This is different from the DataModelEvent BEGIN_EVENTS and END_EVENTS events where events are still sent but the listener having received the BEGIN_EVENTS event knows it may choose to disregard the events until the END_EVENTS event is received. They are given the choice.

Temporarily disabling events is more efficient than using the BEGIN/END_EVENTS method since the events are not dispatched to all listeners.

See Also:

DataModelEvent, getEventsEnabled()

getEventsEnabled

public boolean getEventsEnabled()

Returns true if events are enabled, false otherwise.

Returns:

true if events are enabled, false otherwise.

See Also:

enableDataModelEvents(boolean)

setModelName

public void setModelName(String modelName)

Sets this model's name.

Parameters:

modelName - a String which is to be this model's name

getModelName

public String getModelName()

Gets this model's name

Returns:

a String which is the name of this model.

getCurrentGlobalTable

public com.klg.jclass.datasource.DataTableModel getCurrentGlobalTable()

Returns the DataTableModel currently in focus.

Returns:

the DataTableModel which has the global cursor's focus

See Also:

moveToRow(com.klg.jclass.datasource.DataModelListener, com.klg.jclass.datasource.DataTableModel, long), getCurrentGlobalBookmark()

getCurrentGlobalBookmark

public long getCurrentGlobalBookmark()

Returns the bookmark of the row which has the global cursor's focus.

Returns:

the bookmark of the row on which the global cursor is located

See Also:

moveToRow(com.klg.jclass.datasource.DataModelListener, com.klg.jclass.datasource.DataTableModel, long), getCurrentGlobalTable()

getCurrentDataTable

public com.klg.jclass.datasource.DataTableModel getCurrentDataTable(com.klg.jclass.datasource.DataModelListener originator,
                                                                    com.klg.jclass.datasource.MetaDataModel myLevel)
                                                             throws DataModelException

Returns the DataTable at the specified MetaData level based on the current bookmark. Bookmark refers to what we're calling the "bookmark path" ie the bookmarks for each parent MetaData level down to the specified level.

Will create the table if it does not exist. In this case it will be the child of the current row in the parent, and so on.

Parameters:

originator - the DataModelListener which initiated this action

Returns:

the DataTableModel currently in focus for this level

Throws:

DataModelException - If get fails.

getCurrentDataItem

public Object getCurrentDataItem(com.klg.jclass.datasource.DataModelListener originator,
                                 com.klg.jclass.datasource.MetaDataModel myLevel,
                                 String column)
                          throws DataModelException

Returns the data item at the specified MetaData level and column for the current row. Equivalent to calling DataTableModel.getResultData() with the current bookmark at the MetaData level.

Will create the table if it does not exist. In this case it will be the child of the current row in the parent, and so on.

Parameters:

originator - the DataModelListener which initiated this action

Throws:

DataModelException - If get fails.

getMetaData

public com.klg.jclass.datasource.MetaDataModel getMetaData(String metaDataName)

Gets a MetaDataModel instance by name, or null if not found.

Parameters:

metaDataName - a String which is the name of the MetaDataModel object

Returns:

the MetaDataModel for which getDescription() == metaDataName, or null if not found.

See Also:

MetaDataModel.setDescription(java.lang.String), MetaDataModel.getDescription()

isModified

public boolean isModified()

Are there any pending modifications in any rows in this entire data model?

Returns:

true if there is at least one change pending, false otherwise

clearCurrentPath

public void clearCurrentPath(com.klg.jclass.datasource.MetaDataModel parentMeta)

Clear the current path of all children of this MetaDataModel.

Parameters:

parentMeta - the MetaDataModel whose children are to be cleared.

clearDataTableTreeUserData

public void clearDataTableTreeUserData(Object user)

Clears all user data. Clears all Objects which were arbitrarily associated with the entire DataTableTree.

Parameters:

user - an Object, a reference to the user.

clearDataTableTreeInternalData

public void clearDataTableTreeInternalData(Object user)

For internal use only. Clears all internal data. Clears all Objects which were arbitrarily associated with the entire DataTableTree.

Parameters:

user - an Object, a reference to the user.