Skip to main content
aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorHenrik Rentz-Reichert2013-07-31 11:24:41 -0400
committerHenrik Rentz-Reichert2013-07-31 11:24:41 -0400
commitfeb5ff02f1db559f1e7dcf500121ddd5b2732116 (patch)
tree8003d5f1c3a259f082e115655645ef8fad96cc08 /runtime/org.eclipse.etrice.runtime.java/src/org/eclipse
parentc64a7bbca19b64532a65a0101d13b76660ee66e3 (diff)
downloadorg.eclipse.etrice-feb5ff02f1db559f1e7dcf500121ddd5b2732116.tar.gz
org.eclipse.etrice-feb5ff02f1db559f1e7dcf500121ddd5b2732116.tar.xz
org.eclipse.etrice-feb5ff02f1db559f1e7dcf500121ddd5b2732116.zip
[runtime.java, runtime.common.tests, examples] fixes, life cycle and JavaDoc
1. changed paths for optional actors Originally the path looked like e.g. /LS/main/appl/cont/optarray/optarray:0/sub2/deep_sub then we tried to achieve /LS/main/appl/cont/optarray:0/sub2/deep_sub but ran into issues: To retrieve objects in the instance tree the complete path (the first version) is needed. Thus we rolled back those changes. 2. life cycle is implemented for dynamic actors 3. JavaDoc for OptionalActorInterfaceBase and sub classes
Diffstat (limited to 'runtime/org.eclipse.etrice.runtime.java/src/org/eclipse')
-rw-r--r--runtime/org.eclipse.etrice.runtime.java/src/org/eclipse/etrice/runtime/java/modelbase/OptionalActorInterfaceBase.java206
-rw-r--r--runtime/org.eclipse.etrice.runtime.java/src/org/eclipse/etrice/runtime/java/modelbase/ReplicatedOptionalActorInterfaceBase.java100
-rw-r--r--runtime/org.eclipse.etrice.runtime.java/src/org/eclipse/etrice/runtime/java/modelbase/ScalarOptionalActorInterfaceBase.java66
3 files changed, 328 insertions, 44 deletions
diff --git a/runtime/org.eclipse.etrice.runtime.java/src/org/eclipse/etrice/runtime/java/modelbase/OptionalActorInterfaceBase.java b/runtime/org.eclipse.etrice.runtime.java/src/org/eclipse/etrice/runtime/java/modelbase/OptionalActorInterfaceBase.java
index 602aa6c7b..d00c04edc 100644
--- a/runtime/org.eclipse.etrice.runtime.java/src/org/eclipse/etrice/runtime/java/modelbase/OptionalActorInterfaceBase.java
+++ b/runtime/org.eclipse.etrice.runtime.java/src/org/eclipse/etrice/runtime/java/modelbase/OptionalActorInterfaceBase.java
@@ -12,62 +12,110 @@
package org.eclipse.etrice.runtime.java.modelbase;
+import java.io.IOException;
+import java.io.ObjectInput;
+import java.io.ObjectOutput;
import java.util.ArrayList;
import java.util.List;
-import org.eclipse.etrice.runtime.java.messaging.IRTObject;
import org.eclipse.etrice.runtime.java.modelbase.RTSystemProtocol.RTSystemConjPort;
/**
+ * This is the abstract base class of all optional actor interfaces.
+ * Concrete sub classes are {@link ScalarOptionalActorInterfaceBase} and {@link ReplicatedOptionalActorInterfaceBase}.
+ * <p>
+ * The code generator again derives from the concrete sub classes and adds {@link InterfaceItemBroker}s as members.
+ * </p><p>
+ * This generated class is instantiated as member of the containing actor (the one holding the associated optional
+ * actor reference).
+ * </p><p>
+ * The broker items are responsible for the mediation of the port connections.
+ * </p>
+ *
* @author Henrik Rentz-Reichert
- *
*/
public abstract class OptionalActorInterfaceBase extends SystemPortOwner implements IEventReceiver {
protected static final int IFITEM_RTSystemPort = 0;
+ /**
+ * The name of the optional actor class. This and all sub classes of it are valid candidates
+ * for instantiation at this place.
+ */
private String className;
+
+ /**
+ * This map is set during optional actor creation by the factory.
+ */
private PathToPeers path2peers = null;
+
+ /**
+ * The path of this instance is used to determine correct mappings.
+ * It is subtracted from incoming paths, then (relative) peer paths are looked up and
+ * the result paths are turned into absolute ones by adding this again.
+ *
+ * @see #getPeersForPath(String)
+ */
private String ownPath;
+
+ /**
+ * The thread (associated with the message service of this ID) that will be used by the
+ * optional actor instance.
+ */
private int subtreeThread;
+ /**
+ * This port is used to send system messages to the optional sub instance tree.
+ */
private RTSystemConjPort RTSystemPort = null;
/**
- * @param parent
- * @param name
+ * The only constructor.
+ *
+ * @param parent the containing {@link ActorClassBase}
+ * @param name the reference name
+ * @param clsname the class name of this reference
*/
protected OptionalActorInterfaceBase(IEventReceiver parent, String name, String clsname) {
super(parent, name);
className = clsname;
subtreeThread = parent.getThread();
- setOwnPath(getInstancePath()+IRTObject.PATH_DELIM+getName());
+ setOwnPath(getInstancePath());
RTSystemPort = new RTSystemConjPort(this, IFITEM_RTSystemPort);
}
- public String getInstancePath(char delim) {
- if (getParent()!=null)
- return getParent().getInstancePath(delim);
-
- return "";
- }
-
/**
- * Get list of peer paths
+ * Get list of peer paths.
+ * <p>
+ * This method delegates to its parent if {@link #getPath2peers()}{@code ==null}.
+ * </p>
+ * <p>
+ * If an optional actor instance is created the used factory will set
+ * its own path-to-peer mapping. Then the incoming path is made relative to
+ * the created actor and the paths looked up in the map are made absolute again.
*
- * @param path
- * @return list of peer paths or {@code null} if not mapped
+ * @param path an absolute path
+ * @return a list of absolute peer paths or {@code null} if not mapped
*/
public List<String> getPeersForPath(String path) {
if (getPath2peers()==null)
return getParent().getPeersForPath(path);
- // remove own path +
+ /* remove own path + following segment (which is a second time
+ * the name of the optional ref (+ maybe a replication index)
+ * e.g.
+ * incoming path = /LS/appl/cont/opt/opt/path/to/port
+ * rel path = /path/to/port
+ * result of lookup (to interface port) = /port
+ * returned = /LS/appl/cont/opt/port (one of the interface port brokers)
+ */
int sep = path.indexOf(PATH_DELIM, getOwnPath().length()+1);
if (sep<0 || sep>=path.length())
return null;
+ // The optInstPath for scalar optional actors ownPath/<name>.
+ // However, for replicated actors it is ownPath/<name>:<idx>
String optInstPath = path.substring(0, sep);
path = path.substring(sep);
@@ -89,70 +137,186 @@ public abstract class OptionalActorInterfaceBase extends SystemPortOwner impleme
}
/**
- * get thread for path
+ * Get thread for path. The thread is passed to the optional actor creation method.
+ *
* @param path
- * @return thread id or {@code -1} if not mapped
+ * @return always the thread that was specified with the creation call
*/
public int getThreadForPath(String path) {
return subtreeThread;
}
+ /**
+ * This method is called by the optional actor factory to set the relative path mappings
+ * for the created instance sub tree
+ *
+ * @param path2peers
+ */
public void setPath2peers(PathToPeers path2peers) {
this.path2peers = path2peers;
}
/**
+ * Returns the locally set path-to-peer mapping
* @return the path2peers
*/
protected PathToPeers getPath2peers() {
return path2peers;
}
+ /**
+ * @return the class name for this optional actor
+ */
public String getClassName() {
return className;
}
+ /**
+ * {@code null} implementation since never called
+ * @see org.eclipse.etrice.runtime.java.modelbase.IEventReceiver#receiveEvent(org.eclipse.etrice.runtime.java.modelbase.InterfaceItemBase, int, java.lang.Object)
+ */
@Override
public void receiveEvent(InterfaceItemBase ifitem, int evt, Object data) {
// nothing to do, never called
}
/**
+ * Returns the cached own path to avoid multiple re-computation
* @return the ownPath
*/
- public String getOwnPath() {
+ private String getOwnPath() {
return ownPath;
}
/**
* @param ownPath the ownPath to set
*/
- public void setOwnPath(String ownPath) {
+ private void setOwnPath(String ownPath) {
this.ownPath = ownPath;
}
+ /**
+ * @return the thread for the optional actors to be created
+ */
protected int getSubtreeThread() {
return subtreeThread;
}
+ /**
+ * sets the thread for the optional actor to be created
+ * @param subtreeThread
+ */
protected void setSubtreeThread(int subtreeThread) {
this.subtreeThread = subtreeThread;
}
- protected void startSubTree() {
+ /**
+ * This method is responsible for the start-up part of the life cycle of the newly created
+ * instances:
+ *
+ * <ul>
+ * <li>load from input (if not {@code null})</li>
+ * <li>recursively {@link ActorClassBase#init() initialize}</li>
+ * <li>send initialization messages</li>
+ * </ul>
+ *
+ * @param actor the newly created actor (actually a whole tree)
+ * @param input an optional input source for the sub tree's data
+ */
+ protected void startupSubTree(ActorClassBase actor, ObjectInput input) {
+ if (input!=null)
+ loadActor(actor, input);
+
+ // recursive initialization
+ actor.init();
+
+ // send system messages for initialization (does nothing for persisted actors)
RTSystemPort.executeInitialTransition();
}
+ /**
+ * This method is responsible for the shut-down part of the life cycle of the newly created
+ * instances:
+ *
+ * <ul>
+ * <li>save to output (if not {@code null})</li>
+ * <li>recursively {@link ActorClassBase#stop() stop}</li>
+ * </ul>
+ *
+ * @param actor
+ * @param output
+ */
+ protected void shutdownSubTree(ActorClassBase actor, ObjectOutput output) {
+ if (output!=null)
+ saveActor(actor, output);
+
+ // recursively stop
+ actor.stop();
+ }
+
+ /**
+ * Other than the base class implementation this method doesn't delegate but
+ * returns our own {@link org.eclipse.etrice.runtime.java.modelbase.RTSystemProtocol.RTSystemPort RTSystemPort}.
+ *
+ * @see org.eclipse.etrice.runtime.java.modelbase.SystemPortOwner#getSystemPort()
+ */
@Override
public IReplicatedInterfaceItem getSystemPort() {
return RTSystemPort;
}
+ /**
+ * This is an empty implementation which can be overridden by the generator
+ * if MSC logging is enabled.
+ *
+ * @param actorClass the name of the actor class to be instantiated
+ * @param name the name of the reference (eventually including an index for replicated actors)
+ */
protected void logCreation(String actorClass, String name) {
// empty implementation, may be overridden by sub class
}
+ /**
+ * This is an empty implementation which can be overridden by the generator
+ * if MSC logging is enabled.
+ *
+ * @param name the name of the reference (eventually including an index for replicated actors)
+ */
protected void logDeletion(String name) {
// empty implementation, may be overridden by sub class
}
+
+ /**
+ * TODO: persistence not implemented yet
+ *
+ * @param actor
+ * @param input
+ */
+ protected void loadActor(ActorClassBase actor, ObjectInput input) {
+ if (input==null || actor==null)
+ return;
+
+ try {
+ input.close();
+ }
+ catch (IOException e) {
+ }
+ }
+
+ /**
+ * TODO: persistence not implemented yet
+ *
+ * @param actor
+ * @param output
+ */
+ protected void saveActor(ActorClassBase actor, ObjectOutput output) {
+ if (output==null || actor==null)
+ return;
+
+ try {
+ output.close();
+ }
+ catch (IOException e) {
+ }
+ }
}
diff --git a/runtime/org.eclipse.etrice.runtime.java/src/org/eclipse/etrice/runtime/java/modelbase/ReplicatedOptionalActorInterfaceBase.java b/runtime/org.eclipse.etrice.runtime.java/src/org/eclipse/etrice/runtime/java/modelbase/ReplicatedOptionalActorInterfaceBase.java
index af2211bcd..3cedc7a4b 100644
--- a/runtime/org.eclipse.etrice.runtime.java/src/org/eclipse/etrice/runtime/java/modelbase/ReplicatedOptionalActorInterfaceBase.java
+++ b/runtime/org.eclipse.etrice.runtime.java/src/org/eclipse/etrice/runtime/java/modelbase/ReplicatedOptionalActorInterfaceBase.java
@@ -12,6 +12,8 @@
package org.eclipse.etrice.runtime.java.modelbase;
+import java.io.ObjectInput;
+import java.io.ObjectOutput;
import java.util.ArrayList;
import java.util.LinkedList;
@@ -19,30 +21,63 @@ import org.eclipse.etrice.runtime.java.messaging.IRTObject;
import org.eclipse.etrice.runtime.java.messaging.RTServices;
/**
+ * This class serves as base class for generated classes.
+ * It specializes {@link OptionalActorInterfaceBase} for replicated optional actors.
+ *
+ * @see OptionalActorInterfaceBase
+ *
* @author Henrik Rentz-Reichert
- *
*/
public class ReplicatedOptionalActorInterfaceBase extends OptionalActorInterfaceBase {
+ /**
+ * A separator for the index part of the name.
+ */
private static final char INDEX_SEP = ':';
+
+ /**
+ * A list of freed indices.
+ */
private LinkedList<Integer> releasedIndices = new LinkedList<Integer>();
+
+ /**
+ * All actor instances currently alive.
+ */
private ArrayList<ActorClassBase> actors = new ArrayList<ActorClassBase>();
/**
- * @param parent
- * @param name
- * @param clsname
+ * The only constructor.
+ *
+ * @param parent the parent event receiver
+ * @param name the name of the actor reference
+ * @param clsname the actor class name of the reference
*/
- public ReplicatedOptionalActorInterfaceBase(IEventReceiver parent, String name, String clsname) {
+ protected ReplicatedOptionalActorInterfaceBase(IEventReceiver parent, String name, String clsname) {
super(parent, name, clsname);
}
+ /**
+ * This method instantiates and starts an optional actor (together with its contained instances).
+ *
+ * @param actorClass the name of the actor class to be instantiated
+ * @param thread the ID of the message service (and thus the thread) for the newly created instances
+ * @return the index of the newly create instance or {@code -1} on failure
+ */
public int createOptionalActor(String actorClass, int thread) {
+ return createOptionalActor(actorClass, thread, null);
+ }
+
+ /**
+ * This method instantiates and starts an optional actor (together with its contained instances).
+ *
+ * @param actorClass the name of the actor class to be instantiated
+ * @param thread the ID of the message service (and thus the thread) for the newly created instances
+ * @param input an optional {@link ObjectInput}
+ * @return the index of the newly create instance or {@code -1} on failure
+ */
+ public int createOptionalActor(String actorClass, int thread, ObjectInput input) {
setSubtreeThread(thread);
- // make sure the path is up to date
- setOwnPath(getInstancePath());
-
IOptionalActorFactory factory = RTServices.getInstance().getSubSystem().getFactory(getClassName(), actorClass);
if (factory==null)
return -1;
@@ -56,23 +91,40 @@ public class ReplicatedOptionalActorInterfaceBase extends OptionalActorInterface
return -1;
actors.add(actor);
-
- startSubTree();
+
+ startupSubTree(actor, input);
return index;
}
/**
- * @param idx
- * @return
+ * Destroys an actor instance of this array.
+ * Before actual destruction the instances are shut down properly.
+ *
+ * @param idx the index of the instance to be destroyed
+ * @return {@code true} on success, {@code false} else
*/
public boolean destroyOptionalActor(int idx) {
+ return destroyOptionalActor(idx, null);
+ }
+
+ /**
+ * Destroys an actor instance of this array.
+ * Before actual destruction the instances are shut down properly.
+ *
+ * @param idx the index of the instance to be destroyed
+ * @param output an optional {@link ObjectOutput}
+ * @return {@code true} on success, {@code false} else
+ */
+ public boolean destroyOptionalActor(int idx, ObjectOutput output) {
String childName = getChildName(idx);
logDeletion(childName);
IRTObject child = getChild(childName);
if (!(child instanceof ActorClassBase))
return false;
+ shutdownSubTree((ActorClassBase)child, output);
+
((ActorClassBase)child).destroy();
releasedIndices.push(idx);
actors.remove(child);
@@ -80,8 +132,23 @@ public class ReplicatedOptionalActorInterfaceBase extends OptionalActorInterface
return true;
}
+ /**
+ * Destroys all instances in the array.
+ * Before actual destruction the instances are shut down properly.
+ */
public void destroyAllOptionalActors() {
+ destroyAllOptionalActors(null);
+ }
+
+ /**
+ * Destroys all instances in the array.
+ * Before actual destruction the instances are shut down properly.
+ *
+ * @param output an optional {@link ObjectOutput}
+ */
+ public void destroyAllOptionalActors(ObjectOutput output) {
for (ActorClassBase actor : actors) {
+ shutdownSubTree(actor, output);
actor.destroy();
int idx = Integer.parseInt(actor.getName().substring(getName().length()));
releasedIndices.push(idx);
@@ -89,10 +156,19 @@ public class ReplicatedOptionalActorInterfaceBase extends OptionalActorInterface
actors.clear();
}
+ /**
+ * Composes a name with an index for a child instance.
+ *
+ * @param idx the index to be used
+ * @return the composed name of the form &lt;name>:&lt;idx>
+ */
public String getChildName(int idx) {
return getName()+INDEX_SEP+idx;
}
+ /**
+ * @return the next free index
+ */
private int getFreeIndex() {
if (releasedIndices.isEmpty())
return actors.size();
diff --git a/runtime/org.eclipse.etrice.runtime.java/src/org/eclipse/etrice/runtime/java/modelbase/ScalarOptionalActorInterfaceBase.java b/runtime/org.eclipse.etrice.runtime.java/src/org/eclipse/etrice/runtime/java/modelbase/ScalarOptionalActorInterfaceBase.java
index 0f412ed6b..6afdc5ec0 100644
--- a/runtime/org.eclipse.etrice.runtime.java/src/org/eclipse/etrice/runtime/java/modelbase/ScalarOptionalActorInterfaceBase.java
+++ b/runtime/org.eclipse.etrice.runtime.java/src/org/eclipse/etrice/runtime/java/modelbase/ScalarOptionalActorInterfaceBase.java
@@ -12,34 +12,62 @@
package org.eclipse.etrice.runtime.java.modelbase;
+import java.io.ObjectInput;
+import java.io.ObjectOutput;
+
import org.eclipse.etrice.runtime.java.messaging.RTServices;
/**
+ * This class serves as base class for generated classes.
+ * It specializes {@link OptionalActorInterfaceBase} for scalar optional actors.
+ *
+ * @see OptionalActorInterfaceBase
+ *
* @author Henrik Rentz-Reichert
- *
*/
public class ScalarOptionalActorInterfaceBase extends OptionalActorInterfaceBase {
+ /**
+ * Our single actor instance or {@code null} if not instantiated or destroyed.
+ */
private ActorClassBase actor = null;
/**
- * @param parent
- * @param name
- * @param clsname
+ * The only constructor.
+ *
+ * @param parent the parent event receiver
+ * @param name the name of the actor reference
+ * @param clsname the actor class name of the reference
*/
- public ScalarOptionalActorInterfaceBase(IEventReceiver parent, String name, String clsname) {
+ protected ScalarOptionalActorInterfaceBase(IEventReceiver parent, String name, String clsname) {
super(parent, name, clsname);
}
+ /**
+ * This method instantiates and starts an optional actor (together with its contained instances).
+ *
+ * @param actorClass the name of the actor class to be instantiated
+ * @param thread the ID of the message service (and thus the thread) for the newly created instances
+ * @return {@code true} on success or {@code false} on failure
+ */
public boolean createOptionalActor(String actorClass, int thread) {
+ return createOptionalActor(actorClass, thread, null);
+ }
+
+ /**
+ * This method instantiates and starts an optional actor (together with its contained instances).
+ *
+ * @param actorClass the name of the actor class to be instantiated
+ * @param thread the ID of the message service (and thus the thread) for the newly created instances
+ * @param input an optional {@link ObjectInput}
+ * @return {@code true} on success or {@code false} on failure
+ */
+ public boolean createOptionalActor(String actorClass, int thread, ObjectInput input) {
if (actor!=null)
return false;
setSubtreeThread(thread);
- // make sure the path is up to date
- setOwnPath(getInstancePath());
-
// SubSystemClass.createOptionalActor() will set our PathTo* maps
IOptionalActorFactory factory = RTServices.getInstance().getSubSystem().getFactory(getClassName(), actorClass);
if (factory==null)
@@ -49,21 +77,37 @@ public class ScalarOptionalActorInterfaceBase extends OptionalActorInterfaceBase
logCreation(actorClass, getName());
actor = factory.create(this, getName());
- startSubTree();
+ startupSubTree(actor, input);
return actor!=null;
}
/**
- * @param idx
- * @return
+ * Destroys our actor instance.
+ * Before actual destruction the instances are shut down properly.
+ *
+ * @return {@code true} on success, {@code false} else
*/
public boolean destroyOptionalActor() {
+ return destroyOptionalActor(null);
+ }
+
+ /**
+ * Destroys our actor instance.
+ * Before actual destruction the instances are shut down properly.
+ *
+ * @param output an optional {@link ObjectOutput}
+ * @return {@code true} on success, {@code false} else
+ */
+ public boolean destroyOptionalActor(ObjectOutput output) {
if (actor==null)
return false;
logDeletion(getName());
+ if (output!=null)
+ saveActor(actor, output);
+
actor.destroy();
actor = null;

Back to the top