gumbo.visualize.data
Class DataModel

java.lang.Object
  |
  +--gumbo.util.AbstractDisposable
        |
        +--gumbo.visualize.data.DataModel

All Implemented Interfaces:

Disposable, java.io.Serializable

Direct Known Subclasses:

AspectModel, PartModel, WholeModel

public abstract class DataModel

extends AbstractDisposable

implements java.io.Serializable

Data Model

An abstract class for the role of "model" in an MVC-based visualization of client data. A data model serves as a proxy for a client model defined outside of Gumbo. As such, a data model includes an immutable "client ID" reference, which associates the data model with its client model, and a mutable "client data" object, which represents aspects of the client model state that affect its presentation.

The client ID uniquely associates this model with the client model it represents; however, the default identity (equals, hashcode) of a data model is reference identity, not its client ID identity. As such, by default, two data models with the same client ID will NOT test equal. See ClientModels for details concerning the creation and use of client IDs.

The client data, if provided, is only used by graphic views, to render a more specific presentation of the client model. As such, a data model's client data is typically a lightweight proxy for the actual client data, containing only that portion of the data required for presentation. Since a data model contains only one data model reference, the client data must be compatible with any graphic view requiring it. See the package readme.html for more information.

For the sake of view generation, data models are conceptually divided into "strong" and "weak" models. Strong models, such as whole and part models, form a rigid model framework, with a strong sense of ownership (a part can only be owned by one whole) and no allowance for missing elements. As such, strong models form the basis upon which layouts and views are built. Weak models, such as aspect models, form a rather loose model framework, with multiple ownership (a client model can belong to many aspect models) and transient elements (aspect model children without a view are ignored).

This object implements the Disposable interface with "fail fast" disposal detection. Any attempt to access this model after it has been disposed will throw an IllegalStateException. Disposing a data model also disposes any data views that depend on it since, in general, a data view is incapable of maintaining itself without its data model and client ID.

The client model to data model relationship is one to many, and client models are intended to be oblivious to the existence of data models. As such, this class maintains a global map so that all active (not disposed) data models associated with a given client model (through its client ID) can be efficiently found.

Client Model

A client model refers to a client's data model living outside the scope of Gumbo, in the client's domain. Inside of Gumbo, a client model is represented by its unique "client ID", which serves as a proxy for the client model. In order for Gumbo to visualize a client model, the client model must be associated with a data model, which in turn must be (strongly or weakly) associated with a data view (see DataView) and graphic view (see GraphicView).

The client ID is intended as an immutable "cookie" provided by the client. Via the client ID's equals() method, the client and system can determine if a model (and by association, any views) of the client model is present, and whether or not it is accurate, by checking the client IDs of its contituent elements. The client ID also provides the client and system an association between the originating client model and its representation as none or more data models and views. For example, a user would interactively select an object in a view, and the client would be notified with the selection's client ID, thereby allowing the client to identify the client model object corresponding to the user selection.

The client is responsible for generating and interpreting the client ID. Issues to consider are its immutabilty (at least as concerns equals() and hashCode()), the scope of uniqueness (within a JVM, across the entire application, or for all time), the scope of freshness (if a model is stale is it just the model or also all dependent models), and the interpretation of its value (as implemented by its equals() and hashCode() methods). If client IDs are used at all they should at least be unique within the data model's JVM (assuming that all the data models are in the same JVM).

Implementation of the equals() method in the client ID must conform to the contract for Object.equals(), which stipulates that if the equals() is overridden, then hashCode() must also be overridden. The hashcode for a client ID is defined to be the sum of the hash codes of the objects involved in determining equals(), where the hashcode of a null object is defined to be zero. This ensures that id1.equals(id2) implies that id1.hashCode()==id2.hashCode() for any two client IDs id1 and id2.

By definition, the client ID in a data model is never null. If the client does not provide one the system will use the reference to the data model itself as the default client ID (the implication being that the client is using data models to model client data, not just for visualizing it). Note that if default client IDs are used, each time a model is serialized it will be received as a new model with a different client ID. Also, if the client only provides some of the client IDs, leaving the rest of the IDs to default, unintended conflicts may arise. To avoid the possibility of a client provided client ID testing equal to a default one the client should provide all or none of the data model client IDs.

Version:

$Revision: 1.21 $

Author:

Jon Barrilleaux (jonb@jmbaai.com) of JMB and Associates Inc.

See Also:

Serialized Form

Method Summary

java.lang.Object	getClientData() Gets the client data represented by this model, which may be a proxy for the actual client data that is used by graphic views.
java.lang.Object	getClientId() Gets the client ID intended to uniquely associate this model with the client data it represents.
protected void	implDispose() Disposes all views associated with this model, removes the model from the global monitor, then disposes itself.
protected DataModel	initDataModel(java.lang.Object clientId, java.lang.Object clientData) Used by subclasses and serialization to complete the initialization of this object.
void	setClientData(java.lang.Object clientData) Sets the client data used by this data model for presentation, and fires DataModel.clientDataChanged() events (whether or not the client data has detectably changed).

Methods inherited from class gumbo.util.AbstractDisposable

dispose, isDisposed

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getClientId

public java.lang.Object getClientId()

Gets the client ID intended to uniquely associate this model with the client data it represents. If a null client ID was specified upon model creation returns this model as the client ID. Throws an exception if not yet initialized.

Returns:

Reference to the client ID. Never null.

setClientData

public void setClientData(java.lang.Object clientData)

Sets the client data used by this data model for presentation, and fires DataModel.clientDataChanged() events (whether or not the client data has detectably changed). Clients should also call this method if state of the current client data object changes so that change events are fired. Throws an exception if not yet initialized.

Parameters:

clientData - Reference to the data model's actual client data or a proxy thereof. Used by graphic views for display. The type of this object must be compatible with any graphic view that may use it. Null if none.

getClientData

public java.lang.Object getClientData()

Gets the client data represented by this model, which may be a proxy for the actual client data that is used by graphic views. Throws an exception if not yet initialized.

Returns:

Reference to the client data. Null if none.

initDataModel

protected final DataModel initDataModel(java.lang.Object clientId,
                                        java.lang.Object clientData)

Used by subclasses and serialization to complete the initialization of this object. Throws an exception if already initialized.

Parameters:

clientId - Reference to the data model's client data ID. Used by the client and system to uniquely associate the model with the client data it represents, which may not be the same as clientData. The object's equals() and hashCode() methods must conform to the general contract for Object (see Object and DataModel). Null if none, in which case the client ID defaults to this object.

clientData - Reference to the data model's actual client data or a proxy thereof. Used by graphic views for display. The type of this object must be compatible with any graphic view that may use it. Null if none.

Returns:

Reference to this object (which facilitates inline construction). Never null.

implDispose

protected void implDispose()

Disposes all views associated with this model, removes the model from the global monitor, then disposes itself.

Specified by:

implDispose in class AbstractDisposable