at.spardat.xma.mdl.Synchronization 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: Synchronization.java 2089 2007-11-28 13:56:13Z s3460 $
package at.spardat.xma.mdl;
import java.io.IOException;
import at.spardat.xma.serializer.XmaInput;
import at.spardat.xma.serializer.XmaOutput;
/**
* This interface is realized by model objects that have the capability
* to synchronize its state. Its used in XMA to synchronize a client and
* its server side instance of a widget model.
*
* The methods in this interface work much like Java-serialization. Basically,
* state is saved in a byte stream (externalize) and may be restored from
* there (internalize).
*
* This interface works in close relationship with Transactional.
* An implementing class may decide not to store its complete state in
* externalize, but only to store changes since the last syncpoint
* (see Transactional).
*
* @author YSD, 17.04.2003 21:41:58
*/
public 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.
*
* @param xo the serialization destination
* @param forceFull if true, the complete state is written
* and deltas are ignored.
* @throws IOException on serialization errors
*/
public abstract void externalize (XmaOutput xo, boolean forceFull) throws IOException;
/**
* 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.
*
* @param in the XMAObjectInput. If a XMAObjectInputChangeListener is
* set in the object in, it will be notified after applying
* changes read from in.
* @throws IOException on serialization errors
* @throws ClassNotFoundException on serialization errors
*/
public abstract void internalize (XmaInput in) throws IOException, ClassNotFoundException;
}