/* Copyright 2011 - iSencia Belgium NV

Licensed under the Apache License, Version 2.0 (the "License");

you may not use this file except in compliance with the License.

You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software

distributed under the License is distributed on an "AS IS" BASIS,

WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

See the License for the specific language governing permissions and

limitations under the License.

*/

package com.isencia.passerelle.actor;

import java.util.ArrayList;

import java.util.Collection;

import java.util.HashMap;

import java.util.HashSet;

import java.util.Iterator;

import java.util.List;

import java.util.Map;

import org.slf4j.Logger;

import org.slf4j.LoggerFactory;

import ptolemy.actor.Director;

import ptolemy.actor.FiringEvent;

import ptolemy.actor.FiringEvent.FiringEventType;

import ptolemy.actor.Receiver;

import ptolemy.actor.TypedAtomicActor;

import ptolemy.actor.process.ProcessDirector;

import ptolemy.actor.process.TerminateProcessException;

import ptolemy.data.IntToken;

import ptolemy.data.Token;

import ptolemy.data.expr.Parameter;

import ptolemy.kernel.CompositeEntity;

import ptolemy.kernel.util.Attribute;

import ptolemy.kernel.util.IllegalActionException;

import ptolemy.kernel.util.NameDuplicationException;

import ptolemy.kernel.util.Settable;

import ptolemy.kernel.util.Workspace;

import com.isencia.passerelle.actor.gui.EditorIcon;

import com.isencia.passerelle.actor.gui.IOptionsFactory;

import com.isencia.passerelle.actor.gui.OptionsFactory;

import com.isencia.passerelle.core.ControlPort;

import com.isencia.passerelle.core.ErrorCode;

import com.isencia.passerelle.core.ErrorPort;

import com.isencia.passerelle.core.PasserelleException;

import com.isencia.passerelle.core.PasserelleToken;

import com.isencia.passerelle.core.Port;

import com.isencia.passerelle.core.PortFactory;

import com.isencia.passerelle.core.PortHandler;

import com.isencia.passerelle.core.PortListener;

import com.isencia.passerelle.core.PortListenerAdapter;

import com.isencia.passerelle.director.DirectorUtils;

import com.isencia.passerelle.domain.cap.BlockingQueueReceiver;

import com.isencia.passerelle.ext.DirectorAdapter;

import com.isencia.passerelle.ext.ErrorControlStrategy;

import com.isencia.passerelle.message.ManagedMessage;

import com.isencia.passerelle.message.MessageException;

import com.isencia.passerelle.message.MessageFactory;

import com.isencia.passerelle.message.interceptor.IMessageCreator;

import com.isencia.passerelle.statistics.ActorStatistics;

import com.isencia.passerelle.statistics.StatisticsServiceFactory;

/**

* Base class for all Passerelle Actors. Uses Passerelle's custom parameter panes. Defines a getInfo() method, combining the actor's name with extended info

* that can be defined in actor subclasses.

* <p>

* An actor's life cycle is determined/executed through the following methods, that are being invoked by the Passerelle engine. <br>

* 1. Constructor :

* <ul>

* <li>invoked once

* <li>this is where IO ports and parameters must be constructed

* <li>Actor subclasses must call the super(...) constructor

* </ul>

* 2. preInitialize()

* <ul>

* <li>invoked once for every model execution

* <li>this is where model-dependent resource activation/configuration must be done

* <li>Actor subclasses must call super.preInitialize()

* </ul>

* <p>

* In the standard Passerelle execution mode, the above methods are invoked for all actors in a model in one common thread, e.g. the preInitialize() of all

* actors is called sequentially. As a consequence, none of these methods should block!

* </p>

* <p>

* In the standard Passerelle execution mode, all methods below are invoked concurrently on all actors in a model, i.e. each actor's fireing cycle has its own

* thread.

* </p>

* 3. initialize()

* <ul>

* <li>invoked once for every model execution AND for every dynamic model adjustment (not supported by engine in Passerelle v1.x)

* <li>this is where all run initialization must be done

* <li>Actor subclasses must call super.initialize()

* </ul>

* 4. preFire()

* <ul>

* <li>invoked once before every fire()

* <li>used to test cycle preconditions and (re)set cycle parameters

* <li>return true to allow call to fire()

* <li>return false to indicate preconditions are not OK and firing cycle should be retried later

* <li>Actor subclasses must call super.preFire() and include the returned boolean in their logical result expression

* </ul>

* 5. fire()

* <ul>

* <li>invoked once between every preFire() and postFire()

* <li>this is where the real actor behaviour must be implemented: read inputs, do something and possibly send results

* <li>fire() is implemented by Actor base classes as a template method, and some specific methods (doFire(),...) must be implemented to fill in the custom

* behaviour.

* </ul>

* 6. postFire()

* <ul>

* <li>invoked once after every fire()

* <li>used to test cycle postconditions

* <li>return true if actor's processing cycle should continue

* <li>return false if actor's processing cycle should stop, after which wrapUp() will be invoked by the Passerelle Engine

* <li>Actor subclasses must call super.postFire() and include the returned boolean in their logical result expression

* </ul>

* 7a. wrapUp()

* <ul>

* <li>invoked once at the end of an actor's processing cycle

* <li>this is where all resources should be released, and all extra threads that the actor has launched should be properly terminated

* <li>after this method invocation, the actor will leave from the running model

* <li>Actor subclasses must call super.wrapUp()

* </ul>

* 7b. terminate()

* <ul>

* <li>invoked when normal termination via wrapUp() does not work

* <li>should also release all resources and ensure that all threads for the actor are terminated.

* <li>should not block, a terminate() procedure should be swift and reliable.

* <li>Actor subclasses must call super.terminate()

* </ul>

* </p>

* <p>

* An actor normally determines by itself at what moment it can leave from a running model, i.e. when it is of no more use. This is typically related to the

* status of the actor's input feeds: input ports (for Transformers and Sinks) or external data feeds (for Sources).

* </p>

* A Passerelle input may signal that it has reached the end of its feed by returning a "null" message. For actors with only 1 input, a "null" message indicates

* that the actor can safely decide that it can leave the running model. The actor implementation code can signal that to the Passerelle infrastructure by

* calling Actor.requestFinish(). Then the Actor.postFire() will return false, wrapUp() will be called etc. Actors with multiple inputs must determine which

* inputs are critical for the actors' processing and which are optional. If a situation arises where the critical inputs are no longer alive, again

* requestFinish() can be invoked after which the actor will gracefully leave the running model. </p>

* <p>

* Some actors also have a "trigger" port. These have the following behaviour:

* <ul>

* <li>the trigger port is not connected: the trigger port is completely ignored, i.e. the Actor behaves as a non-triggered one

* <li>the trigger port is connected:

* <ul>

* <li>1. the actor may only start generating output messages after receiving a trigger message

* <li>2. the actor may only invoke requestFinish() when its (critical) input(s) have run dry AND the trigger port as well.

* <li>3. the actor must be able to restart getting input data and generating results after its inputs have run dry, when a next trigger message is received. <br>

* E.g. a FileReader actor will re-read the same file and send the contents as output messages every time a new trigger is received.

* </ul>

* </ul>

* </p>

*

* @author erwin

*/

public abstract class Actor extends TypedAtomicActor implements IMessageCreator {