Started to refactor the transitionEngine

src/de/tudarmstadt/maki/simonstrator/api/component/transition/CallbackTarget.java → src/de/tudarmstadt/maki/simonstrator/api/component/transition/AtomicTransition.java

@@ -20,10 +20,40 @@
 
 package de.tudarmstadt.maki.simonstrator.api.component.transition;
 
-public interface CallbackTarget {
-	public void success(TransitionEnabled component, boolean isSource,
-			boolean isTarget);
+/**
+ * Simplified version of an atomic transition providing a method to transfer
+ * state between two mechanisms. This is only required if the
+ * {@link TransferState} annotation is not sufficient in your use case.
+ * 
+ * @author Bjoern Richerzhagen, Alexander Froemmgen
+ *
+ * @param <S>
+ *            Source component type
+ * @param <T>
+ *            Target component type
+ */
+public interface AtomicTransition<S extends TransitionEnabled, T extends TransitionEnabled> {
+
+	/**
+	 * Implement custom state transformations here. For simple variable passing,
+	 * is is sufficient to use the {@link TransferState} annotation.
+	 * 
+	 * @param sourceComponent
+	 * @param targetComponent
+	 */
+	public void transferState(S sourceComponent, T targetComponent);
+
+	/**
+	 * Implement a custom failure recovery mechanism for this transition, if
+	 * desired. This is called as soon as the transition finished (successful
+	 * and unsuccessful).
+	 * 
+	 * @param sourceComponent
+	 * @param targetComponent
+	 * @param successful
+	 *            true, if no error occured during the transition.
+	 */
+	public void transitionFinished(S sourceComponent, T targetComponent,
+			boolean successful);
 
-	public void fail(TransitionEnabled component, boolean isSource,
-			boolean isTarget, Exception e);
 }

src/de/tudarmstadt/maki/simonstrator/api/component/transition/StateCallback.java

-package de.tudarmstadt.maki.simonstrator.api.component.transition;
-
-public final class StateCallback {
-	private final TransitionEnabled component;
-	private final CallbackTarget target;
-	private final boolean isSource;
-	private final boolean isTarget;
-
-	private boolean called = false;
-
-	public StateCallback(TransitionEnabled component, CallbackTarget target,
-			boolean isSource, boolean isTarget) {
-		this.component = component;
-		this.target = target;
-		this.isSource = isSource;
-		this.isTarget = isTarget;
-
-		assert isSource != isTarget;
-	}
-
-	public void success() {
-		if (called)
-			throw new RuntimeException(
-					"Transition StateCallback invoked twice.");
-		called = true;
-
-		target.success(component, isSource, isTarget);
-	}
-
-	public void fail(Exception e) {
-		if (called)
-			throw new RuntimeException(
-					"Transition StateCallback invoked twice.");
-		called = true;
-
-		target.fail(component, isSource, isTarget, e);
-	}
-}
\ No newline at end of file

src/de/tudarmstadt/maki/simonstrator/api/component/transition/AtomicTransitionStrategy.java → src/de/tudarmstadt/maki/simonstrator/api/component/transition/TransferState.java

@@ -20,63 +20,44 @@
 
 package de.tudarmstadt.maki.simonstrator.api.component.transition;
 
-import java.io.Serializable;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
 
 /**
- * Classes implementing this interface define an AtomicTransition from F to T
- * (with the respective transition lifecycle).
+ * Annotate fields that you want to automatically migrate during a transition.
+ * Usually, this makes sense if you have an abstract base class for your
+ * strategies and have some field like, e.g., a reference to a local overlay
+ * component that is required by all of those.
  * 
- * @author Bjoern Richerzhagen, Alex Froemmgen
+ * If a <strong>field</strong> is marked with @TransferState, but the target
+ * component does not also carry a field or a constructor with the annotation
+ * and the same type and name, the transfer of the respective value is discarded
+ * silently.
  * 
- *         TODO Annotation Flip/Flip vs. Run/Run
+ * This annotation might also be used to annotate a <strong>constructor</strong>
+ * - in this case, the respective annotation has to carry the names of the
+ * variables that are to be transfered in the order they are used by the
+ * constructor.
  * 
- * @param <F>
- *            From
- * @param <T>
- *            To
+ * For more complex transformations of state between different transition
+ * enabled components, you need to specify a custom instance of an
+ * {@link AtomicTransitionStrategy}.
+ * 
+ * @author Bjoern Richerzhagen
+ *
  */
-public interface AtomicTransitionStrategy<F extends TransitionEnabled, T extends TransitionEnabled>
-		extends Serializable {
-
-	/**
-	 * The Transition is in the startup-phase
-	 * 
-	 * @param from
-	 * @param to
-	 */
-	public void inStartup(F from, T to);
-
-	/**
-	 * Now, both F and T are active, but T is preparing its shutdown.
-	 * (F.runnning, T.shutdown)
-	 * 
-	 * FIXME: this callback is currently not triggered within the RunRun
-	 * Transition. Do we require it at all?
-	 * 
-	 * @param from
-	 * @param to
-	 */
-	@Deprecated
-	public void inParallelActive(F from, T to);
-
-	/**
-	 * The Run/Run-Transition is currently in its rollback-state. Note the
-	 * reversed meaning of from and to in this context!!
-	 * 
-	 * @param from
-	 *            source of the transition (NOT source of the rollback!)
-	 * @param to
-	 *            target of the transition (NOT target of the rollback!)
-	 */
-	public void inRollback(F from, T to);
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ ElementType.FIELD, ElementType.CONSTRUCTOR })
+public @interface TransferState {
 
 	/**
-	 * Last call to the transition-object (after the components did their
-	 * cleanup)
+	 * A string array listing the names of transfered variables in order of the
+	 * arguments of the constructor.
 	 * 
-	 * @param from
-	 * @param to
+	 * @return
 	 */
-	public void inCleanup(F from, T to);
+	String[] value();
 
 }

src/de/tudarmstadt/maki/simonstrator/api/component/transition/TransitionEnabled.java

@@ -21,33 +21,58 @@
 package de.tudarmstadt.maki.simonstrator.api.component.transition;
 
 /**
- * A {@link TransitionEnabled} class can be controlled by the Transi
+ * A {@link TransitionEnabled} mechanism is controlled by the
+ * {@link TransitionEngine}. It allows for the transparent exchange of the
+ * underlying implementation of that mechanism and for basic lifecycle
+ * callbacks.
  * 
- * @author bjoern
+ * @author Bjoern Richerzhagen, Alexander Froemmgen, Julius Rueckert
  *
  */
 public interface TransitionEnabled {
 
 	/**
-	 * Prepare internal state / datastructures, no communication
+	 * Notifies the mechanism that it is now supposed to run. "Start" the
+	 * mechanism: e.g., join by sending some messages or connect to other nodes.
+	 * Once you are ready to fully operate, trigger the callback. State has been
+	 * transferred right before this method is called.
 	 * 
 	 * @param cb
+	 *            Callback to be triggered on success (when the mechanism is
+	 *            fully functional) or failure (join did not succeed, ...)
 	 */
-	public void onInit(StateCallback cb);
-
-	// FIXME Future Work public void onStartup(StateCallback cb);
+	public void startMechanism(TransitionEnabled.Callback cb);
 
 	/**
-	 * "Start" the overlay: join, and on join successful call cb.finished
+	 * A transition occurred and this implementation of the
+	 * {@link TransitionEnabled} mechanism has to stop operating (e.g., by
+	 * gracefully leaving a system and sending some final messages). Once
+	 * operation has stopped, invoke the callback. State has already been
+	 * transferred to the new target component.
 	 * 
 	 * @param cb
+	 *            Callback to be triggered on success or failure!
+	 */
+	public void stopMechanism(TransitionEnabled.Callback cb);
+
+	/**
+	 * Simple callback - has to be invoked to terminate a lifecycle-phase of a
+	 * mechanism.
+	 * 
+	 * @author Bjoern Richerzhagen
+	 *
 	 */
-	public void onRunning(StateCallback cb);
+	public static interface Callback {
 
-	public void onShutdown(StateCallback cb, ParallelActiveCallback paC);
+		/**
+		 * The respective lifecycle-phase was finished. Do also trigger this in
+		 * case of an error!
+		 * 
+		 * @param successful
+		 *            true, if the phase is finished successfully.
+		 */
+		public void finished(boolean successful);
 
-	public void onCleanup(StateCallback cb);
-	
-	// public void onFinished(StateCallback cb);
+	}
 
 }

src/de/tudarmstadt/maki/simonstrator/api/component/transition/TransitionEngine.java

+/*
+ * Copyright (c) 2005-2010 KOM – Multimedia Communications Lab
+ *
+ * This file is part of Simonstrator.KOM.
+ * 
+ * Simonstrator.KOM is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * any later version.
+ * 
+ * PeerfactSim.KOM is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ * 
+ * You should have received a copy of the GNU General Public License
+ * along with PeerfactSim.KOM.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+package de.tudarmstadt.maki.simonstrator.api.component.transition;
+
+import de.tudarmstadt.maki.simonstrator.api.component.HostComponent;
+
+/**
+ * Interface for the local transition engine that is used to fetch component
+ * proxies. This enables us to exchange the way proxies are created without
+ * modifying tons of overlay code to replace static calls.
+ * 
+ * Furthermore, programmatic execution of transitions is eased to promote the
+ * use of the {@link TransitionEnabled} interface even if control communication
+ * is realized in-band with the application protocol.
+ * 
+ * This is the <strong>local</strong> transition engine.
+ * 
+ * @author Bjoern Richerzhagen
+ *
+ */
+public interface TransitionEngine extends HostComponent {
+
+	/**
+	 * To create an register a new component proxy that can then be used in the
+	 * respective application code.
+	 * 
+	 * @param proxyInterface
+	 *            the interface (must extend {@link TransitionEnabled}) that is
+	 *            exported by this proxy.
+	 * @param defaultInstance
+	 *            a default implementation of the {@link TransitionEnabled}
+	 *            component to be used initially. Lifecycle-methods will be
+	 *            invoked.
+	 * @param proxyName
+	 *            an identifier (string) for this proxy
+	 * @param transitionListener
+	 *            an optional listener that is triggered on every transition.
+	 *            Can be useful for analyzing.
+	 * @return the proxy to be used in the application code
+	 */
+	public <T extends TransitionEnabled> T createMechanismProxy(
+			Class<T> proxyInterface, T defaultInstance, String proxyName,
+			TransitionListener transitionListener);
+
+	/**
+	 * Executes an atomic transition. If an {@link AtomicTransition} instance
+	 * for the respective types was previously registered, it is used to execute
+	 * the transition. Otherwise, the default model is used, including the
+	 * support for state transfers using the {@link TransferState} annotation.
+	 * 
+	 * @param proxyName
+	 *            the previously chosen proxy identifier.
+	 * @param targetClass
+	 */
+	public <T extends TransitionEnabled> void executeAtomicTransition(
+			String proxyName, Class<T> targetClass);
+
+	/**
+	 * Register a transition with a custom transitionStrategy. This is optional
+	 * - if you execute a previously not registered transition, a default model
+	 * is used (including basic state transfer).
+	 * 
+	 * @param proxyName
+	 * @param fromClass
+	 * @param toClass
+	 * @param transitionStrategy
+	 */
+	public <F extends TransitionEnabled, T extends TransitionEnabled> void registerTransition(
+			String proxyName, Class<F> fromClass, Class<T> toClass,
+			AtomicTransition<F, T> transitionStrategy);
+
+}

src/de/tudarmstadt/maki/simonstrator/api/component/transition/ParallelActiveCallback.java → src/de/tudarmstadt/maki/simonstrator/api/component/transition/TransitionListener.java

@@ -21,13 +21,18 @@
 package de.tudarmstadt.maki.simonstrator.api.component.transition;
 
 /**
+ * This listener is notified if a transition for a given
+ * {@link TransitionEnabled} component occurred locally.
  * 
- * @author Alexander Froemmgen
- * 
+ * @author Bjoern Richerzhagen
+ *
  */
-public interface ParallelActiveCallback {
+public interface TransitionListener {
 
-	public void finishTransition();
+	/**
+	 * Called as soon as the actual underlying component has been exchanged by
+	 * the transition.
+	 */
+	public void executedTransition();
 
-	public void rollbackTransition();
 }