001/* An interface for objects that can intervene in communication between actors.
002
003@Copyright (c) 2010-2013 The Regents of the University of California.
004All rights reserved.
005
006Permission is hereby granted, without written agreement and without
007license or royalty fees, to use, copy, modify, and distribute this
008software and its documentation for any purpose, provided that the
009above copyright notice and the following two paragraphs appear in all
010copies of this software.
011
012IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
013FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
014ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
015THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF
016SUCH DAMAGE.
017
018THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
019INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
020MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
021PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
022CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES,
023ENHANCEMENTS, OR MODIFICATIONS.
024
025                                                PT_COPYRIGHT_VERSION_2
026                                                COPYRIGHTENDKEY
027
028
029 */
030package ptolemy.actor;
031
032import ptolemy.data.Token;
033import ptolemy.kernel.util.IllegalActionException;
034
035/** An interface for objects that can intervene in communication between actors.
036 *  A communication aspect creates receivers that wrap the receivers created by a
037 *  {@link Director}, delegating (or not) to those receivers as it sees fit.
038 *  If an {@link IOPort} references a communication aspect, then calls to any
039 *  receiver in that port will be handled instead by a receiver created by
040 *  the communication aspect.
041 *  <p>
042 *  For example, a communication aspect could intervene in communications to take
043 *  into account shared resources. For example, it could delay delivery of any
044 *  tokens to the original receiver (that created by the director) until the
045 *  resources become available for the transport to occur.
046 *
047 *  @author Patricia Derler, Edward A. Lee
048 *  @version $Id$
049 *  @since Ptolemy II 10.0
050 *  @Pt.ProposedRating Red (cxh)
051 *  @Pt.AcceptedRating Red (cxh)
052 */
053public interface CommunicationAspect {
054
055    /** Create a receiver to mediate a communication via the specified receiver.
056     *  @param receiver Receiver whose communication is to be mediated.
057     *  @return A new receiver.
058     *  @exception IllegalActionException If the receiver cannot be created.
059     */
060    public Receiver createIntermediateReceiver(Receiver receiver)
061            throws IllegalActionException;
062
063    /** Add a communication aspect monitor to the list of listeners.
064     *  @param monitor The communication aspect monitor.
065     */
066    public void registerListener(CommunicationAspectListener monitor);
067
068    /** Reset the CommunicationAspect.
069     */
070    public void reset();
071
072    /** Take the specified token and mediate communication to the specified
073     *  receiver. An implementer could, for example, delay the communication
074     *  to account for resource contention. Or, it could make a record of the
075     *  energy consumed by the communication.
076     *  @param source Receiver that sent the token.
077     *  @param receiver The receiver for which this communication aspect is mediating
078     *   communication.
079     *  @param token The token for the communication to mediate.
080     *  @exception IllegalActionException If the token cannot be sent.
081     */
082    public void sendToken(Receiver source, Receiver receiver, Token token)
083            throws IllegalActionException;
084
085    /** The parameter name of the decorator highlight color.
086     */
087    public static String decoratorHighlightColorName = "decoratorHighlightColor";
088}