001/* An event that represents a token or tokens are taken by the actor.
002   (read event)
003
004 Copyright (c) 2007-2014 The Regents of the University of California.
005 All rights reserved.
006 Permission is hereby granted, without written agreement and without
007 license or royalty fees, to use, copy, modify, and distribute this
008 software and its documentation for any purpose, provided that the above
009 copyright notice and the following two paragraphs appear in all copies
010 of this software.
011
012 IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
013 FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
014 ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
015 THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF
016 SUCH DAMAGE.
017
018 THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
019 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
020 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
021 PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
022 CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES,
023 ENHANCEMENTS, OR MODIFICATIONS.
024
025 PT_COPYRIGHT_VERSION_2
026 COPYRIGHTENDKEY
027
028 */
029package ptolemy.actor;
030
031import ptolemy.data.Token;
032
033///////////////////////////////////////////////////////////////////
034//// TokenGotEvent
035
036/**
037 An event that is published by IOPorts whenever get or
038 getInside is called.  The appropriate event should be published
039 whenever a token is taken out from the port's queue by the actor code.
040 In Kepler the provenance recorder uses these events to save
041 intermediate results of the workflow.  In the future these events
042 could be used for "smart" reruns or a fault tolerance mechanism.
043
044 @author  Norbert Podhorszki
045 @version $Id$
046 @since Ptolemy II 6.1
047 @deprecated Use IOPortEvent instead.
048 @Pt.ProposedRating Red (pnorbert)
049 @Pt.AcceptedRating Red (pnorbert)
050 */
051@Deprecated
052public class TokenGotEvent {
053    /** Create a new token got event with the given parameters.  This
054     *  constructor is used when an array of tokens is taken.
055     *  @param sink The IOPort the token is stored at.
056     *  @param channel Channel the token was received on.
057     *  @param tokens The token array used for the get.
058     *  @param vectorLength The number of tokens taken.
059     *  @param outside True if the token was taken on outside channel,
060     *  false otherwise.
061     */
062    public TokenGotEvent(IOPort sink, int channel, Token[] tokens,
063            int vectorLength, boolean outside) {
064        _port = sink;
065        _channel = channel;
066        _tokenArray = tokens;
067        _token = null;
068        _vectorLength = vectorLength;
069        _outside = outside;
070    }
071
072    /** Create a new token got event with the given parameters.  This
073     *  constructor is used when a token is taken using get or getInside.
074     *  @param sink The IOPort the token is stored at.
075     *  @param channel Channel the token was received on.
076     *  @param token The token that was received.
077     *  @param outside True if the token was taken on outside channel,
078     *  false otherwise.
079     */
080
081    public TokenGotEvent(IOPort sink, int channel, Token token,
082            boolean outside) {
083        _port = sink;
084        _channel = channel;
085        _tokenArray = null;
086        _token = token;
087        _vectorLength = -1;
088        _outside = outside;
089    }
090
091    ///////////////////////////////////////////////////////////////////
092    ////                         public methods                    ////
093
094    /** Return the channel the token was received on.
095     *  @return The channel number.
096     */
097    public int getChannel() {
098        return _channel;
099    }
100
101    /** Return the port that the token was received at.
102     *  @return An instance of IOPort.
103     */
104    public IOPort getPort() {
105        return _port;
106    }
107
108    /** Return the token that was received by the IOPort.  The variable
109     *  _token will be null if the event was for a get array. To get
110     *  the tokens that were received use getTokenArray() instead.
111     *  @return The token received at the IOPort.
112     */
113    public Token getToken() {
114        return _token;
115    }
116
117    /** Return the array of tokens that was received by the
118     *  IOPort. The variable _tokenArray will be null if an individual
119     *  token was got instead of an array.
120     *  @return The array of tokens which were taken.
121     */
122    public Token[] getTokenArray() {
123        //may want to return the array shortened to be vector length long?
124        return _tokenArray;
125    }
126
127    /** Return the number of tokens in the array taken at the IOPort.
128     *  The variable _vectorLength will be -1 if an individual token
129     *  was taken instead of an array of tokens.
130     *  @return The number of tokens taken at the port.
131     */
132    public int getVectorLength() {
133        return _vectorLength;
134    }
135
136    /** Return the direction flag (outside or inside).  The flag is
137     *  true, if the token was taken from outside, false if from
138     *  inside
139     *  @return The direction flag.
140     */
141    public boolean getOutsideFlag() {
142        return _outside;
143    }
144
145    /** Return a string representation of this event.
146     *  @return A user-readable string describing the event.
147     */
148    @Override
149    public String toString() {
150        StringBuffer buffer = new StringBuffer();
151        buffer.append("The port " + _port + " took ");
152        if (_vectorLength != -1) {
153            buffer.append(_vectorLength);
154            buffer.append(" tokens ");
155        } else {
156            buffer.append(_token.toString());
157        }
158        buffer.append(" on channel " + _channel + ".");
159
160        return buffer.toString();
161    }
162
163    ///////////////////////////////////////////////////////////////////
164    ////                         private variables                 ////
165
166    //The channel the token was sent on.
167    private int _channel;
168
169    // The IOPort that was activated.
170    private IOPort _port;
171
172    //The token sent by the IOPort.
173    private Token _token;
174
175    //The array of tokens sent by the IOPort.
176    private Token[] _tokenArray;
177
178    //The number of tokens from the array that were sent by the IOPort.
179    private int _vectorLength;
180
181    // Boolean flag if the token was taken on outside link (true) or
182    // inside (false)
183    private boolean _outside;
184}