at.spardat.xma.mdl.list
Class ListDomWM

java.lang.Object
  extended byat.spardat.xma.mdl.WModel
      extended byat.spardat.xma.mdl.list.ListDomWM
All Implemented Interfaces:
Descriptive, IListDomWM, ISelectable, Synchronization, Transactional
Direct Known Subclasses:
ListDomWMClient

public class ListDomWM
extends WModel
implements ISelectable, IListDomWM

The widget model that encapsulates domain values which are usually displayed in a combo box.

The displayed entries in the combobox are drawn from a tabular data source specified by a parameter in the constructor. The datasource is required to provide three columns:

  1. The first column is a key that uniquely identifies an entry. There must be no two entries with the same key. The key is also used to identify the entry when it comes to selection (see ISelectable).
  2. The second column is a short value, acting as a short identification for the end user. This data item usually is localized. Nevertheless, it is optional. If the short value is empty, the key is taken instead.
  3. The third column is a long value which fully describes the entry to the end user. Programmatically, these values are also optinal, although this does not make much sense. If the data source holds an empty long value, the key is taken instead.


Field Summary
 
Fields inherited from class at.spardat.xma.mdl.WModel
S_NULL
 
Constructor Summary
ListDomWM(short id, Page pm, java.lang.String dataSource)
          Constructs with a provided data source.
 
Method Summary
 boolean changed()
          Yields true if this WidgetModel has changed since the last server side event (or creation).
 void clear()
          Removes the selection from this.
 void commit()
          This method clears the change history.
 void describe(DNode n)
          describe puts all relevant information about this into the provided node.
 void deselect(java.lang.String key)
          Deselects a particular entry.
 void deselectAll()
          All selected entries get deselected.
 void equalsCS(WModel mServer, int syncPoint)
          Compares this widget model (which must be a client side one) with the server buddy mServer and returns true if they are correct with respect to syncPoint.
 int estimateMemory()
          Estimates the number of bytes this object consumes in memory.
 void externalize(XmaOutput xo, boolean forceFull)
          Externalizing either saves the actual state or deltas (changes) in a provided XMAObjectOutput.
 java.lang.String getDataSource()
          Returns the set data source or null, if non is set.
 Page getPage()
          Returns the page this widget model is part of.
 java.lang.String getSelected()
          Returns the id of the selected element.
 java.lang.String[] getSelection()
          Returns a newly created array containing the ids of the selected entries or an empty array, if nothing is selected.
 int getSelectionCount()
          Returns the number of selected elements.
 boolean handle(ModelChangeEvent event)
          All events that might change a WidgetModel are executed via this method.
 void internalize(XmaInput in)
          Updates the state of this with information of the given XMAObjectInput.
 boolean isDynamicDataSource()
          Defines whether the data-source is defined at compile-time in the UI-designer or is always set dynamically (via setDataSource()).
 boolean isMultiSelect()
          Returns true if more than one entry may be selected.
 boolean isSelected(java.lang.String key)
          Returns true if the entry with the provided key is selected, false otherwise.
 boolean isStrict()
          Returns if this Selectable has strict behaviour, that is, the selected keys must always be in the underlying domain of this.
 void randomlyChange()
          Make random changes to this
 void rollback()
          This method restores this Widget Model to its state immediately after the last server side event (or creation).
 void select(java.lang.String key)
          Sets the entry with a provided key as selected.
 void setDataSource(java.lang.String dataSource)
          Sets a new data source.
 void setDynamicDataSource(boolean what)
          Sets whether the data source is set at runtime or compile-time.
 
Methods inherited from class at.spardat.xma.mdl.WModel
cleanUpAfterServerEvent, getId, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

ListDomWM

public ListDomWM(short id,
                 Page pm,
                 java.lang.String dataSource)
Constructs with a provided data source.

Parameters:
id - a numeric id which identifies the WidgetModel within its Page.
pm - reference to the enclosing Page
dataSource - specifies a tabular data source
Throws:
java.lang.IllegalArgumentException - if dataSource is null or empty.
See Also:
ITabularDataSource
Method Detail

setDataSource

public void setDataSource(java.lang.String dataSource)
Description copied from interface: IListDomWM
Sets a new data source. If null is provided, an empty table is considered to be the range of values.

Specified by:
setDataSource in interface IListDomWM
Parameters:
dataSource - specification of a tabular data source.
See Also:
IListDomWM.setDataSource(java.lang.String)

getDataSource

public java.lang.String getDataSource()
Description copied from interface: IListDomWM
Returns the set data source or null, if non is set.

Specified by:
getDataSource in interface IListDomWM
Returns:
data source specification
See Also:
IListDomWM.getDataSource()

isDynamicDataSource

public boolean isDynamicDataSource()
Description copied from interface: IListDomWM
Defines whether the data-source is defined at compile-time in the UI-designer or is always set dynamically (via setDataSource()).

Specified by:
isDynamicDataSource in interface IListDomWM
See Also:
IListDomWM.isDynamicDataSource()

setDynamicDataSource

public void setDynamicDataSource(boolean what)
Sets whether the data source is set at runtime or compile-time. This method may only be called immediately after construction by the generated XMA-code that is created from the UI-designer's generator.


changed

public boolean changed()
Description copied from class: WModel
Yields true if this WidgetModel has changed since the last server side event (or creation). Some models have a more complex state, e.g., a table has a domain and a selection, where either may change. In this case, subclasses will provide more detailed information on what aspect of the model really has changed.

Specified by:
changed in interface Transactional
Specified by:
changed in class WModel
Returns:
true if changed, false otherwise
See Also:
Transactional.changed()

rollback

public void rollback()
Description copied from class: WModel
This method restores this Widget Model to its state immediately after the last server side event (or creation).

Specified by:
rollback in interface Transactional
Specified by:
rollback in class WModel
See Also:
Transactional.rollback()

commit

public void commit()
Description copied from class: WModel
This method clears the change history. Calling rollback afterwards won't have any effect.

Specified by:
commit in interface Transactional
Specified by:
commit in class WModel
See Also:
Transactional.commit()

handle

public boolean handle(ModelChangeEvent event)
Description copied from class: WModel
All events that might change a WidgetModel are executed via this method.

Specified by:
handle in class WModel
Parameters:
event - the event carrying the information of a change.
Returns:
true if change has been applied, false if it has been rejected.
See Also:
WModel.handle(at.spardat.xma.mdl.ModelChangeEvent)

externalize

public void externalize(XmaOutput xo,
                        boolean forceFull)
                 throws java.io.IOException
Description copied from interface: Synchronization
Externalizing either saves the actual state or deltas (changes) in a provided XMAObjectOutput. The default behaviour is to serialize the changes if changes are beeing tracked. This behaviour may be overwritten by forceFull. If true, the complete state information is written.

If forceFull is false, the object implementing this interface must also implement Transactional. If the object implementing this is able to track changes, these are the changes since the last syncpoint.

Specified by:
externalize in interface Synchronization
Parameters:
xo - the serialization destination
forceFull - if true, the complete state is written and deltas are ignored.
Throws:
java.io.IOException - on serialization errors
See Also:
Synchronization.externalize(at.spardat.xma.serializer.XmaOutput, boolean)

internalize

public void internalize(XmaInput in)
                 throws java.io.IOException,
                        java.lang.ClassNotFoundException
Description copied from interface: Synchronization
Updates the state of this with information of the given XMAObjectInput. in either contains changes or the complete new state information. If in contains changes the implementing class also must implement Transactional and the state after calling internalize is !Transactional.changed(), e.g., a syncpoint is defined.

This method is not allowed to throw Exceptions because that would leave models in an inconsistent state. Thrown exceptions are considered to be programming errors. Internalize must not throw technical exceptions which indicate system or ressource failures. That implies that the person implementing internalize is not allowed to access ressources outside the JVM, either directly or via calls to other methods. Examples of ressource access which must not be triggered are calls to communication of file system services.

Specified by:
internalize in interface Synchronization
Parameters:
in - the XMAObjectInput. If a XMAObjectInputChangeListener is set in the object in, it will be notified after applying changes read from in.
Throws:
java.lang.ClassNotFoundException - on serialization errors
java.io.IOException - on serialization errors
See Also:
Synchronization.internalize(at.spardat.xma.serializer.XmaInput)

deselect

public void deselect(java.lang.String key)
Description copied from interface: ISelectable
Deselects a particular entry. If the entry for the provided key is not selected, this method does nothing.

Specified by:
deselect in interface ISelectable
Parameters:
key - identifies the entry to deselect. If the entry with the provided key is not selected, this method does nothing.
See Also:
ISelectable.deselect(java.lang.String)

deselectAll

public void deselectAll()
Description copied from interface: ISelectable
All selected entries get deselected. After calling this method, the condition getSelectionCount() == 0 holds.

Specified by:
deselectAll in interface ISelectable
See Also:
ISelectable.deselectAll()

getSelected

public java.lang.String getSelected()
Description copied from interface: ISelectable
Returns the id of the selected element. If nothing is selected, null is returned. If more than one entry is selected, some of them is returned. Note that the selected id need not have to be in the underlying domain of this if !isStrict().

Usually, this method is the preferred way of querying the selection state if !isMultiSelect().

Specified by:
getSelected in interface ISelectable
Returns:
key of selected entry or null if nothing is selected
See Also:
ISelectable.getSelected()

getSelection

public java.lang.String[] getSelection()
Description copied from interface: ISelectable
Returns a newly created array containing the ids of the selected entries or an empty array, if nothing is selected.

Specified by:
getSelection in interface ISelectable
Returns:
array of the selected keys. The length of the array equals getSelectionCount().
See Also:
ISelectable.getSelection()

getSelectionCount

public int getSelectionCount()
Description copied from interface: ISelectable
Returns the number of selected elements.

Specified by:
getSelectionCount in interface ISelectable
Returns:
number of selected elements
See Also:
ISelectable.getSelectionCount()

isMultiSelect

public boolean isMultiSelect()
Description copied from interface: ISelectable
Returns true if more than one entry may be selected.

Specified by:
isMultiSelect in interface ISelectable
Returns:
boolean true if the widget model realizing this interface allows multiselection.
See Also:
ISelectable.isMultiSelect()

isSelected

public boolean isSelected(java.lang.String key)
Description copied from interface: ISelectable
Returns true if the entry with the provided key is selected, false otherwise.

Specified by:
isSelected in interface ISelectable
See Also:
ISelectable.isSelected(java.lang.String)

isStrict

public boolean isStrict()
Description copied from interface: ISelectable
Returns if this Selectable has strict behaviour, that is, the selected keys must always be in the underlying domain of this. In the case of !isStrict(), the selected key may be freely choosen and need not be drawn from the domain.

Strict behaviour is only supported if !isMultiSelect(). That means, isMultiSelect() always implies isStrict().

Specified by:
isStrict in interface ISelectable
Returns:
true if the widget model implementing this interface supports strict behaviour, false otherwise.
See Also:
ISelectable.isStrict()

select

public void select(java.lang.String key)
Description copied from interface: ISelectable
Sets the entry with a provided key as selected. If this model does not allow multiselection, a previous selected element is deselected before.

If isStrict() and the provided key is not contained in the underlying domain, this method does nothing.

Specified by:
select in interface ISelectable
Parameters:
key - the entry to select
See Also:
ISelectable.select(java.lang.String)

describe

public void describe(DNode n)
Description copied from interface: Descriptive
describe puts all relevant information about this into the provided node. The implementing method may construct subnodes of node.

Specified by:
describe in interface Descriptive
Overrides:
describe in class WModel
See Also:
Descriptive.describe(at.spardat.xma.mdl.util.DNode)

randomlyChange

public void randomlyChange()
Make random changes to this

Specified by:
randomlyChange in class WModel

equalsCS

public void equalsCS(WModel mServer,
                     int syncPoint)
Description copied from class: WModel
Compares this widget model (which must be a client side one) with the server buddy mServer and returns true if they are correct with respect to syncPoint. If syncPoint is zero, the client model has been externalized and the changes have been applied to the server model. If synPoint is one, the server model has been externalized and the chagnes have been applied to the client model.

This method is for debugging purpose and assumes that client and server models are running within the same VM. It tests if the models the programmer views after a synchronization operation are consistent.

This method requires that this is a client side model.

This method does not throw an exception if models are the same in terms of their contained model data. If it is allowed that models differ (for example some one way tables), this method must take this fact into account. If the models differ, this indicates a programming error and a RuntimeException is thrown.

Specified by:
equalsCS in class WModel
Parameters:
mServer - the server side model partner for this.
syncPoint - 0 if the point in time is after a client to server sychnronization, 1 if the point is after a server to client synchronization.
See Also:
WModel.equalsCS(at.spardat.xma.mdl.WModel, int)

getPage

public Page getPage()
Returns the page this widget model is part of.


clear

public void clear()
Removes the selection from this.

Specified by:
clear in class WModel
See Also:
WModel.clear()

estimateMemory

public int estimateMemory()
Estimates the number of bytes this object consumes in memory.

Specified by:
estimateMemory in class WModel
Returns:
estimated number of bytes this model consumes in memory