at.spardat.xma.mdl.WModel Maven / Gradle / Ivy
/*******************************************************************************
* Copyright (c) 2003, 2007 s IT Solutions AT Spardat GmbH .
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* s IT Solutions AT Spardat GmbH - initial API and implementation
*******************************************************************************/
// @(#) $Id: WModel.java 3240 2009-03-03 16:10:56Z gub $
package at.spardat.xma.mdl;
import at.spardat.xma.mdl.util.DNode;
import at.spardat.xma.mdl.util.Descriptive;
import at.spardat.xma.page.*;
/**
* The base class for all WidgetModels.
*/
public abstract class WModel implements Transactional, Synchronization, Descriptive {
/**
* Some subclasses require style flags driving their behaviour. S_NULL
* may be used as default.
*/
public static final int S_NULL = 0;
/**
* Unique id of a widget model within a page
*/
private short id_;
/**
* Constructor
*
* @param id a unique id identifying this WidgetModel within its page. This constant
* is known at compile time and produced by the UI generator.
* @param pm the Page this model belongs to
*/
public WModel (short id, Page pm) {
id_ = id;
// pm reserved for future use
}
/**
* 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.
*
* @return true if changed, false otherwise
*/
public abstract boolean changed();
/**
* This method restores this Widget Model to its state immediately after the
* last server side event (or creation).
*/
public abstract void rollback();
/**
* This method clears the change history. Calling rollback afterwards won't
* have any effect.
*/
public abstract void commit();
/**
* Every widget model has an integer id which identifies the model within
* the scope of its page.
*
* @return the id
*/
public short getId() {
return id_;
}
/**
* All events that might change a WidgetModel are executed via this method.
*
* @param event the event carrying the information of a change.
* @return true if change has been applied, false if it has been rejected.
*/
public abstract boolean handle (ModelChangeEvent event);
/**
* Resets this WModel to an empty status. Clearing applies to attributes
* that have not been set via the constructor of the widget
* model, rather those that may be changed via methods.
*/
public abstract void clear ();
/**
* @see at.spardat.xma.mdl.util.Descriptive#describe(at.spardat.xma.mdl.util.DNode)
*/
public void describe (DNode n) {
n.app("[").app(id_).app("] ");
n.appShortClass(this).app(": ");
}
/**
* The default implementation is to map this on a debug string.
*/
public String toString () {
return DNode.toString(this);
}
/**
* A implementing subclass must make a random change to its widget model.
* This method is used to extensively test the synchronization mechanism.
*/
public abstract void randomlyChange ();
/**
* 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.
*
* @param mServer the server side model partner for this.
* @param 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.
* @exception RuntimeException if models differ
*/
public abstract void equalsCS (WModel mServer, int syncPoint);
/**
* Provides the estimated number of bytes this widget model consumes
* in memory, asuming that it is in a committed state, i.e, there
* are no pending changes.
* This is just to get a crude feeling about memory consumption.
* It needs not to be exact, which is also not possible as long as a JVM
* does not provide the numbers.
*
* @return estimated number of bytes this model consumes in memory
*/
public abstract int estimateMemory ();
/**
* A server event has been sucessfully executed. This method releases all memory in models
* that may be released. This method is only executed at the server side of XMA.
*/
public void cleanUpAfterServerEvent () {
}
/**
* Creates a NewModelEvent which will create and register an
* identical widget model on the other side of the network.
* This copy will be synchronized with the original in all RPCs.
* @since 2.1.0
*/
public abstract NewModelEvent createNewModelEvent();
}