com.klg.jclass.datasource
Interface MetaDataModel

All Superinterfaces:

TreeNode

All Known Subinterfaces:

IdeMetaDataModel

All Known Implementing Classes:

BaseMetaData, IdeMetaData, SummaryMetaData

public interface MetaDataModel

extends TreeNode

This is the interface for objects that hold the meta-data for data tables.
Please note that only the "get" methods are meant to be used by an application programmer. All other methods are for DataSource's internal use only.
There can be zero, one or more data tables associated with a MetaDataModel, thus it is more efficient to store the meta-data only once.

In terms of JClass DataSource, each MetaDataModel is a node of the MetaTree. The MetaTree describes the hierarchacal relations between MetaDataModel objects.

Each MetaData has its own commit policy. The default is COMMIT_LEAVING_RECORD. A commit policy determines when changes will be written to the data source. There are three policies:

• COMMIT_LEAVING_RECORD
• COMMIT_LEAVING_ANCESTOR
• COMMIT_MANUALLY

When the policy is set to COMMIT_LEAVING_RECORD (the default) modifications to a row will be automatically written to the originating data source when the cursor moves to any other row (see DataModel.movetoRow(..)). In the case of delete, the row is immediately deleted.

When the policy is COMMIT_LEAVING_ANCESTOR changes will be automatically written to the originating data source when the cursor moves to a row which is not in the same subtree as the current row. For example, in a master-detail relationship where the master table is Orders and the details table is OrderDetails, the cursor can be moved to any of the OrderDetail lines which correspond to the current Order. As soon as the cursor is moved to a different Order or to an OrderDetail line for a different Order, the previous edits will be automatically committed.

A policy of COMMIT_MANUALLY will never automatically commit changes. Any row changes will simply change the status of those rows (see DataTableModel.getRowStatus()). You must then call DataTableModel.commitRow(bookmark) or DataModel.updateAll() to make the changes permanent, or call DataTableModel.cancelRowChanges(bookmark) or DataModel.cancelAll() to undo the changes.

See Also:

DataModel.moveToRow(com.klg.jclass.datasource.DataModelListener, com.klg.jclass.datasource.DataTableModel, long), DataTableModel.getRowStatus(long), DataTableModel.commitRow(com.klg.jclass.datasource.DataModelListener, long), DataModel.updateAll(com.klg.jclass.datasource.DataModelListener), DataModel.cancelAll(com.klg.jclass.datasource.DataModelListener)

Field Summary

static int	COMMIT_LEAVING_ANCESTOR Automatically save changes to originating data source when the new bookmark is not in the same subtree as the previous bookmark.
static int	COMMIT_LEAVING_RECORD Automatically save changes to originating data source when cursor bookmark changes
static int	COMMIT_MANUALLY No automatic commit.
static int	TYPE_BIG_DECIMAL
static int	TYPE_BOOLEAN Java data types used to map JDBC data types
static int	TYPE_BYTE
static int	TYPE_BYTE_ARRAY
static int	TYPE_DOUBLE
static int	TYPE_FLOAT
static int	TYPE_INTEGER
static int	TYPE_LONG
static int	TYPE_OBJECT
static int	TYPE_SHORT
static int	TYPE_SQL_DATE
static int	TYPE_SQL_TIME
static int	TYPE_SQL_TIMESTAMP
static int	TYPE_STRING
static int	TYPE_UTIL_DATE

Method Summary

void	addColumn(com.klg.jclass.datasource.ColumnModel column) Add a column to the list of column objects.
void	clear() Change the query for this data control.
void	commitTransaction() Commits transaction.
boolean	getAutoCommit() Returns true if the transaction capabilities of the underlying data source should be used when saving modifications (transactions are supported and enabled).
com.klg.jclass.datasource.BindingModel	getBinding() Return the Binding object associated with this MetaData level.
boolean	getCacheChildren() Returns a boolean flag indicating whether subtrees of DataTables rooted at this level are eligible for deletion.
int	getColumnCount() Returns the number of columns in this result set
String	getColumnIdentifier(int column_index) Returns a string which uniquely identifies this column.
int	getColumnIndex(String name) Given a column name, gets its index.
com.klg.jclass.datasource.ColumnModel	getColumnObject(String column_identifier) Returns the ColumnModel for the given column.
Vector	getColumnObjects() Returns the list of ColumnModel objects.
int	getCommitPolicy() Returns the commit policy for this level.
long	getCurrentBookmark() Returns the bookmark of the row currently in focus.
com.klg.jclass.datasource.DataTableModel	getCurrentDataTable() Returns the data table which currently has focus.
com.klg.jclass.datasource.DataModel	getDataModel() Return the DataModel which encapsulates this MetaDataModel.
boolean	getDeleteAllowed(String table) Returns true if this table can be deleted, false otherwise.
String	getDescription() Returns the user-assigned description of this instance, or "" if the description has not been set.
boolean	getInsertAllowed(String table) Returns true if this table can be inserted into, false otherwise.
int	getJavaColumnType(String column_identifier) Returns the Java Object type for a column as an enum.
int	getMaxRows() Returns the maximum number of rows which can be returned by a query.
int	getMetaID() Returns an int which uniquely identifies this instance of the MetaDataModel.
Object	getNativeMetaData() Returns the native meta data object.
com.klg.jclass.datasource.ProviderModel	getProvider() Get the provider (if any) for this level.
boolean	getShowDeletedRows() Show logically deleted rows?
Class	getStoreClass() Returns the class responsible for data storage and retrieval (implements StoreModel).
boolean	getUpdateAllowed(String table) Returns true if this table can be updated.
boolean	isUpdateAllowedOnColumn(String column) Do permissions on the model allow this column to be editied?
void	rollbackTransaction() Rolls back the transaction.
void	setAutoCommit(boolean value) Sets the auto commit flag.
void	setBinding(com.klg.jclass.datasource.BindingModel binding) Set the Binding object associated with this MetaData level.
void	setCacheChildren(boolean cacheChildren) Sets a boolean indicating whether subtrees of DataTables rooted at this level are eligible for deletion.
void	setCommitPolicy(int commit_policy) Sets the commit policy for this level.
void	setCurrentBookmark(long currentBookmark)
void	setCurrentDataTable(com.klg.jclass.datasource.DataTableModel currentDataTable)
void	setDeleteAllowed(String table, boolean v) Sets a boolean indicating if rows in this table are allowed to be deleted.
void	setDescription(String description) Sets the user-assigned description of this instance.
void	setInsertAllowed(String table, boolean v) Sets a boolean indicating if this table is allowed to be inserted into.
void	setMaxRows(int maxRows) Sets the maximum number of rows a query at this level can return.
void	setMetaID(int id) For internal use only.
void	setProviderClassName(String providerModelClassName) Set the ProviderModel class name which will provide data for this level.
void	setShowDeletedRows(boolean value) Indicates if logically deleted rows showld be shown.
void	setStoreClass(String storeClassName) Sets an alternate class to handle data storage and retrieval responsibilities.
void	setUpdateAllowed(String table, boolean v) Sets a boolean indicating if this table is allowed to be updated.

Methods inherited from interface javax.swing.tree.TreeNode

children, getAllowsChildren, getChildAt, getChildCount, getIndex, getParent, isLeaf

Field Detail

TYPE_BOOLEAN

public static final int TYPE_BOOLEAN

Java data types used to map JDBC data types

See Also:

Constant Field Values

TYPE_SQL_DATE

public static final int TYPE_SQL_DATE

See Also:

Constant Field Values

TYPE_DOUBLE

public static final int TYPE_DOUBLE

See Also:

Constant Field Values

TYPE_FLOAT

public static final int TYPE_FLOAT

See Also:

Constant Field Values

TYPE_INTEGER

public static final int TYPE_INTEGER

See Also:

Constant Field Values

TYPE_STRING

public static final int TYPE_STRING

See Also:

Constant Field Values

TYPE_BIG_DECIMAL

public static final int TYPE_BIG_DECIMAL

See Also:

Constant Field Values

TYPE_LONG

public static final int TYPE_LONG

See Also:

Constant Field Values

TYPE_SQL_TIME

public static final int TYPE_SQL_TIME

See Also:

Constant Field Values

TYPE_SQL_TIMESTAMP

public static final int TYPE_SQL_TIMESTAMP

See Also:

Constant Field Values

TYPE_OBJECT

public static final int TYPE_OBJECT

See Also:

Constant Field Values

TYPE_BYTE

public static final int TYPE_BYTE

See Also:

Constant Field Values

TYPE_SHORT

public static final int TYPE_SHORT

See Also:

Constant Field Values

TYPE_BYTE_ARRAY

public static final int TYPE_BYTE_ARRAY

See Also:

Constant Field Values

TYPE_UTIL_DATE

public static final int TYPE_UTIL_DATE

See Also:

Constant Field Values

COMMIT_LEAVING_RECORD

public static final int COMMIT_LEAVING_RECORD

Automatically save changes to originating data source when cursor bookmark changes

See Also:

Constant Field Values

COMMIT_LEAVING_ANCESTOR

public static final int COMMIT_LEAVING_ANCESTOR

Automatically save changes to originating data source when the new bookmark is not in the same subtree as the previous bookmark.

See Also:

Constant Field Values

COMMIT_MANUALLY

public static final int COMMIT_MANUALLY

No automatic commit.

See Also:

Constant Field Values

Method Detail

clear

public void clear()

Change the query for this data control. For customizer use during design-time.

getColumnIdentifier

public String getColumnIdentifier(int column_index)
                           throws DataModelException

Returns a string which uniquely identifies this column. Used to access data rather than a column index which can change when columns are sorted.

Parameters:

column_index - an int indicating for which column a unique identifier should be returned.

Returns:

a String which uniquely identifies a column

Throws:

DataModelException - If a column identifier cannot obtained.

getColumnCount

public int getColumnCount()
                   throws DataModelException

Returns the number of columns in this result set

Returns:

an int indicating the number of columns in table

Throws:

DataModelException - If getColumnCount() fails.

getJavaColumnType

public int getJavaColumnType(String column_identifier)
                      throws DataModelException

Returns the Java Object type for a column as an enum. All data in the datasource are objects. These are the object types returned by this method:

• TYPE_BOOLEAN
• TYPE_SQL_DATE
• TYPE_DOUBLE
• TYPE_FLOAT
• TYPE_INTEGER
• TYPE_STRING
• TYPE_BIG_DECIMAL
• TYPE_LONG
• TYPE_SQL_TIME
• TYPE_SQL_TIMESTAMP
• TYPE_OBJECT
• TYPE_BYTE
• TYPE_SHORT
• TYPE_BYTE_ARRAY
• TYPE_UTIL_DATE

Thus if a call to this method returns TYPE_BOOLEAN, then the object returned by a call to DataTableModel.getResultData(..) will be a Boolean object. TYPE_BYTE_ARRAY returns a byte[] array which is a "quasi" object.

Parameters:

column_identifier - an String uniquely identifying a column

Returns:

an int representing the meta column type for this column, will be one of

• TYPE_BOOLEAN
• TYPE_SQL_DATE
• TYPE_DOUBLE
• TYPE_FLOAT
• TYPE_INTEGER
• TYPE_STRING
• TYPE_BIG_DECIMAL
• TYPE_LONG
• TYPE_SQL_TIME
• TYPE_SQL_TIMESTAMP
• TYPE_OBJECT
• TYPE_BYTE
• TYPE_SHORT
• TYPE_BYTE_ARRAY
• TYPE_UTIL_DATE

Throws:

DataModelException - If the Java column type cannot be found.

setCommitPolicy

public void setCommitPolicy(int commit_policy)
                     throws DataModelException

Sets the commit policy for this level. Determines when changes are permanently written to the originating data source.

When the policy is set to COMMIT_LEAVING_RECORD (the default) modifications to a row will be automatically written to the originating data source when the cursor moves to any other row (see DataModel.movetoRow(..)). In the case of delete, the row is immediately deleted.

When the policy is COMMIT_LEAVING_ANCESTOR changes will be automatically written to the originating data source when the cursor moves to a row which is not in the same subtree as the current row. For example, in a master-detail relationship where the master table is Orders and the details table is OrderDetails, the cursor can be moved to any of the OrderDetail lines which correspond to the current Order. As soon as the cursor is moved to a different Order or to an OrderDetail line for a different Order, the previous edits will be automatically committed.

A policy of COMMIT_MANUALLY will never automatically commit changes. Any row changes will simply change the status of those rows (see DataTableModel.getRowStatus()). You must then call DataTableModel.commitRow(bookmark) or DataModel.updateAll() to make the changes permanent, or call DataTableModel.cancelRowChanges(bookmark) or DataModel.cancelAll() to undo the changes.

Parameters:

commit_policy - an int, one of COMMIT_LEAVING_RECORD, COMMIT_LEAVING_ANCESTOR, or COMMIT_MANUALLY

Throws:

DataModelException - If set fails.

getCommitPolicy

public int getCommitPolicy()

Returns the commit policy for this level. Determines when changes are permanently written to the originating data source. Will be one of COMMIT_LEAVING_RECORD, COMMIT_LEAVING_ANCESTOR, or COMMIT_MANUALLY.

Returns:

an int, one of COMMIT_LEAVING_RECORD, COMMIT_LEAVING_ANCESTOR, or COMMIT_MANUALLY

getDataModel

public com.klg.jclass.datasource.DataModel getDataModel()

Return the DataModel which encapsulates this MetaDataModel.

Returns:

the DataModel

setInsertAllowed

public void setInsertAllowed(String table,
                             boolean v)

Sets a boolean indicating if this table is allowed to be inserted into. The default is to allow this. Care must be taken in the case where a row is composed of columns from several tables joined in a one-to-one relationship. The default behaviour when a row is inserted is to insert into all the tables in the row. In many cases this is not the desired behaviour. Use this method to turn off insert of the tables you do not wish to be inserted. For example, when entering a SalesOrder row which is a join between SalesOrder and Customer, the default is to try to insert the SalesOrder information into the SalesOrder table, and insert the Customer information into the Customer Table. In many cases, you would just want to the insert into SalesOrder to occur. To accomplish this you would setInsertAllowed for Customer to false.

Parameters:

table - a String name of the table

setUpdateAllowed

public void setUpdateAllowed(String table,
                             boolean v)

Sets a boolean indicating if this table is allowed to be updated. The default is to allow this.

Parameters:

table - a String name of the table

setDeleteAllowed

public void setDeleteAllowed(String table,
                             boolean v)

Sets a boolean indicating if rows in this table are allowed to be deleted. The default is to allow this. Care must be taken in the case where a row is composed of columns from several tables joined in a one-to-one relationship. The default behaviour when a row is deleted is to delete from all the tables in the row. In many cases this is not the desired behaviour. Use this method to turn off delete of the tables you do not wish to be deleted.

Parameters:

table - a String name of the table

getInsertAllowed

public boolean getInsertAllowed(String table)

Returns true if this table can be inserted into, false otherwise. The default is to allow this.

Parameters:

table - a String name of the table

Returns:

true if table can be updated

getUpdateAllowed

public boolean getUpdateAllowed(String table)

Returns true if this table can be updated. The default is to allow updating.

Parameters:

table - a String name of the table

Returns:

true if table can be updated

getDeleteAllowed

public boolean getDeleteAllowed(String table)

Returns true if this table can be deleted, false otherwise. The default is to allow deletions.

Parameters:

table - a String name of the table

Returns:

true if rows in this table can be deleted.

getMetaID

public int getMetaID()

Returns an int which uniquely identifies this instance of the MetaDataModel. This id is automatically generated.

Returns:

an int which uniquely identifies this object.

See Also:

setMetaID(int)

setMetaID

public void setMetaID(int id)

For internal use only. Assigns a unique id to a meta data instance

Parameters:

id - an int which is the unique id for this instance

See Also:

getMetaID()

getDescription

public String getDescription()

Returns the user-assigned description of this instance, or "" if the description has not been set.

Returns:

a String which describes this instance.

setDescription

public void setDescription(String description)

Sets the user-assigned description of this instance.

Parameters:

description - a String which describles this instance.

getAutoCommit

public boolean getAutoCommit()
                      throws DataModelException

Returns true if the transaction capabilities of the underlying data source should be used when saving modifications (transactions are supported and enabled). If the underlying data source supports transactions and this capability has been enabled, data modifications will be wrapped in a transaction which can be committed or rolled back.

Throws:

DataModelException - If an error occurs getting commit flag.

See Also:

commitTransaction(), rollbackTransaction()

setAutoCommit

public void setAutoCommit(boolean value)
                   throws DataModelException

Sets the auto commit flag. If the underlying data source supports transactions and this flag is set to true, a transaction will wrap data modifications.

Parameters:

value - a boolean, true if transactions are to be used, false otherwise.

Throws:

DataModelException - If an error occurs setting commit flag.

rollbackTransaction

public void rollbackTransaction()
                         throws DataModelException

Rolls back the transaction. If the underlying data source supports transactions and transactions have been enabled, calling this method will rollback all pending transactions on the data source (on this connection).

Throws:

DataModelException - If rollback fails.

See Also:

getAutoCommit()

commitTransaction

public void commitTransaction()
                       throws DataModelException

Commits transaction. If the underlying data source supports transactions and transactions have been enabled, calling this method will commit all pending transactions on the data source (on this connection).

Throws:

DataModelException - If commit fails.

getColumnObjects

public Vector getColumnObjects()

Returns the list of ColumnModel objects.

Returns:

a vector of ColumnModel objects.

See Also:

ColumnModel

getColumnObject

public com.klg.jclass.datasource.ColumnModel getColumnObject(String column_identifier)
                                                      throws DataModelException

Returns the ColumnModel for the given column.

Parameters:

column_identifier - a String which uniquely identifies a column

Returns:

a ColumnModel

Throws:

DataModelException - If get fails.

isUpdateAllowedOnColumn

public boolean isUpdateAllowedOnColumn(String column)
                                throws DataModelException

Do permissions on the model allow this column to be editied?

Returns:

true if edits are allowed, false otherwise

Throws:

DataModelException - If the primary keys cannot be determined for the update table.

See Also:

setUpdateAllowed(java.lang.String, boolean), getUpdateAllowed(java.lang.String)

addColumn

public void addColumn(com.klg.jclass.datasource.ColumnModel column)
               throws DataModelException

Add a column to the list of column objects.

Throws:

DataModelException - If duplicate column found.

See Also:

ColumnModel

getNativeMetaData

public Object getNativeMetaData()

Returns the native meta data object. This is a DataSet in JBuilder and a RelationView in VisualCafe.

Returns:

the native meta data object for this level.

setShowDeletedRows

public void setShowDeletedRows(boolean value)
                        throws DataModelException

Indicates if logically deleted rows showld be shown. This attribute can only be set if the commitPolicy is COMMIT_MANUALLY or COMMIT_LEAVING_ANCESTOR, otherwise an exception is thrown.

Parameters:

value - a boolean: true to show rows, false otherwise

Throws:

DataModelException - If set fails.

getShowDeletedRows

public boolean getShowDeletedRows()

Show logically deleted rows?

Returns:

a boolean: true to show rows, false otherwise

getColumnIndex

public int getColumnIndex(String name)
                   throws DataModelException

Given a column name, gets its index.

Returns:

an int which is this column's ordinal position in the original result data.

Throws:

DataModelException - If the operation fails.

setMaxRows

public void setMaxRows(int maxRows)

Sets the maximum number of rows a query at this level can return. Useful for design time where only a sampling of row is required. Set to -1 to have no limit.

Does not apply to ide-specific implmentations. Set the max rows directly on the ide data object instead.

Parameters:

maxRows - an int indicating the max rows to be returned

See Also:

getMaxRows()

getMaxRows

public int getMaxRows()

Returns the maximum number of rows which can be returned by a query.

Does not apply to ide-specific implmentations. Set the max rows directly on the ide data object instead.

Returns:

the maximum number of rows which can be returned by a query

See Also:

setMaxRows(int)

setCacheChildren

public void setCacheChildren(boolean cacheChildren)

Sets a boolean indicating whether subtrees of DataTables rooted at this level are eligible for deletion. The defaul is false meaning DataTableModel.deleteCacheChildren should be called when a subtree is collapsed.

Parameters:

cacheChildren - a boolean: true means children should be cached, false means deleteCacheChildren should be called when a tree is collapsed.

See Also:

getCacheChildren(), DataTableModel.deleteCacheChildren(com.klg.jclass.datasource.DataModelListener)

getCacheChildren

public boolean getCacheChildren()

Returns a boolean flag indicating whether subtrees of DataTables rooted at this level are eligible for deletion.

Returns:

false if deleteCacheChildren should be called on this level when it is collapsed. Return true if the children should be preserved, that is no call should be made to deleteCacheChildren.

See Also:

setCacheChildren(boolean), DataTableModel.deleteCacheChildren(com.klg.jclass.datasource.DataModelListener)

getCurrentDataTable

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

Returns the data table which currently has focus.

Returns:

a DataTableModel, the one currently in focus.

getCurrentBookmark

public long getCurrentBookmark()

Returns the bookmark of the row currently in focus.

Returns:

the bookmark of the row currently in focus.

setCurrentDataTable

public void setCurrentDataTable(com.klg.jclass.datasource.DataTableModel currentDataTable)

setCurrentBookmark

public void setCurrentBookmark(long currentBookmark)

setStoreClass

public void setStoreClass(String storeClassName)
                   throws DataModelException

Sets an alternate class to handle data storage and retrieval responsibilities. A "Class.forName()" will be done to load this alternate class.

If set, BaseDataTable instances will use this instances of this class rather than the default class ("Store") to store and retrieve data.

Throws:

DataModelException - If an error occurs loading the class.

See Also:

StoreModel, getStoreClass()

getStoreClass

public Class getStoreClass()
                    throws DataModelException

Returns the class responsible for data storage and retrieval (implements StoreModel). If not set, the default class (com.klg.jclass.datasource.Store) is loaded and used.

Returns:

the class used to store/retrieve data

Throws:

DataModelException - If get fails.

getBinding

public com.klg.jclass.datasource.BindingModel getBinding()

Return the Binding object associated with this MetaData level.

Returns:

the Binding object for this level.

setBinding

public void setBinding(com.klg.jclass.datasource.BindingModel binding)

Set the Binding object associated with this MetaData level.

getProvider

public com.klg.jclass.datasource.ProviderModel getProvider()

Get the provider (if any) for this level.

Returns:

ProviderModel the class which will provide matrix data for this level

See Also:

ProviderModel.getData(com.klg.jclass.datasource.DataModelListener, long, com.klg.jclass.datasource.MetaDataModel), DataTableModel.createTable(com.klg.jclass.datasource.DataModelListener, long, javax.swing.tree.TreeNode), DataTableModel.getTable(long, javax.swing.tree.TreeNode)

setProviderClassName

public void setProviderClassName(String providerModelClassName)
                          throws DataModelException

Set the ProviderModel class name which will provide data for this level. This class will be instantiated and to provide data.

Throws:

DataModelException - if the provider fails to be instantiated.