View Javadoc
1   package org.djutils.stats.summarizers.event;
2   
3   import java.io.Serializable;
4   import java.rmi.RemoteException;
5   import java.util.Calendar;
6   
7   import org.djutils.event.Event;
8   import org.djutils.event.EventListener;
9   import org.djutils.event.EventListenerMap;
10  import org.djutils.event.EventProducer;
11  import org.djutils.event.LocalEventProducer;
12  import org.djutils.event.TimedEvent;
13  import org.djutils.exceptions.Throw;
14  import org.djutils.stats.summarizers.TimestampWeightedTally;
15  
16  /**
17   * The TimestampWeightedTally class defines a time-weighted tally based on timestamped data. The difference with a normal
18   * time-weighed tally is that the weight of a value is only known at the occurrence of the next timestamp. Furthermore, a last
19   * timestamp needs to be specified to determine the weight of the last value. This EventBased version of the tally can be
20   * notified with timestamps and values using the EventListenerInterface. It also produces events when values are tallied and
21   * when the tally is initialized. Timestamps can be Number based or Calendar based.
22   * <p>
23   * Copyright (c) 2020-2024 Delft University of Technology, Jaffalaan 5, 2628 BX Delft, the Netherlands. All rights reserved. See
24   * for project information <a href="https://simulation.tudelft.nl/" target="_blank"> https://simulation.tudelft.nl</a>. The DSOL
25   * project is distributed under a three-clause BSD-style license, which can be found at
26   * <a href="https://simulation.tudelft.nl/dsol/3.0/license.html" target="_blank">
27   * https://simulation.tudelft.nl/dsol/3.0/license.html</a>. <br>
28   * @author <a href="https://www.tudelft.nl/averbraeck" target="_blank"> Alexander Verbraeck</a>
29   */
30  public class EventBasedTimestampWeightedTally extends TimestampWeightedTally implements EventProducer, EventListener
31  {
32      /** */
33      private static final long serialVersionUID = 20200228L;
34  
35      /** The embedded EventProducer. */
36      private EventProducer eventProducer = null;
37  
38      /**
39       * constructs a new EventBasedTimestampWeightedTally with a description.
40       * @param description String; the description of this EventBasedTimestampWeightedTally
41       */
42      public EventBasedTimestampWeightedTally(final String description)
43      {
44          this(description, new LocalEventProducer());
45      }
46  
47      /**
48       * Construct a new EventBasedTimestampWeightedTally with a description.
49       * @param description String; the description of this WeightedTally
50       * @param eventProducer EventProducer; the EventProducer to embed and use in this statistic
51       */
52      public EventBasedTimestampWeightedTally(final String description, final EventProducer eventProducer)
53      {
54          super(description);
55          Throw.whenNull(eventProducer, "eventProducer cannot be null");
56          this.eventProducer = eventProducer;
57      }
58  
59      /** {@inheritDoc} */
60      @Override
61      public EventListenerMap getEventListenerMap() throws RemoteException
62      {
63          return this.eventProducer.getEventListenerMap();
64      }
65  
66      /** {@inheritDoc} */
67      @Override
68      public void initialize()
69      {
70          super.initialize();
71          if (this.eventProducer != null)
72          {
73              try
74              {
75                  this.eventProducer.fireEvent(StatisticsEvents.INITIALIZED_EVENT);
76              }
77              catch (RemoteException exception)
78              {
79                  throw new RuntimeException(exception);
80              }
81          }
82      }
83  
84      /** {@inheritDoc} */
85      @Override
86      public void notify(final Event event)
87      {
88          if (event instanceof TimedEvent<?>)
89          {
90              TimedEvent<?> timedEvent = (TimedEvent<?>) event;
91              double value = 0.0;
92              if (event.getContent() instanceof Number)
93              {
94                  value = ((Number) event.getContent()).doubleValue();
95              }
96              else
97              {
98                  throw new IllegalArgumentException(
99                          "EventBasedTimestampWeightedTally.notify: Content " + event.getContent() + " should be a Number");
100             }
101             Object timestamp = timedEvent.getTimeStamp();
102             if (timestamp instanceof Number)
103             {
104                 register(((Number) timestamp).doubleValue(), value);
105             }
106             else if (timestamp instanceof Calendar)
107             {
108                 register(((Calendar) timestamp).getTimeInMillis(), value);
109             }
110             else
111             {
112                 throw new IllegalArgumentException(
113                         "EventBasedTimestampWeightedTally.notify: timestamp should be a Number or Calendar");
114             }
115         }
116         else
117         {
118             throw new IllegalArgumentException("EventBasedTimestampWeightedTally.notify: Event should be a TimedEvent");
119         }
120     }
121 
122     /**
123      * Process one observed Calender-based value. The time used will be the Calendar's time in milliseconds. Silently ignore
124      * when a value is registered, but tally is not active, i.e. when endObservations() has been called.
125      * @param timestamp Calendar; the Calendar object representing the timestamp
126      * @param value double; the value to process
127      * @return double; the value
128      * @throws NullPointerException when timestamp is null
129      * @throws IllegalArgumentException when value is NaN
130      * @throws IllegalArgumentException when given timestamp is before last timestamp
131      */
132     @Override
133     public double register(final Calendar timestamp, final double value)
134     {
135         super.register(timestamp, value);
136         try
137         {
138             if (hasListeners())
139             {
140                 this.eventProducer.fireEvent(StatisticsEvents.TIMESTAMPED_OBSERVATION_ADDED_EVENT,
141                         new Serializable[] {timestamp, value});
142                 fireEvents(timestamp);
143             }
144         }
145         catch (RemoteException exception)
146         {
147             throw new RuntimeException(exception);
148         }
149         return value;
150     }
151 
152     /**
153      * Process one observed Number-based value. Silently ignore when a value is registered, but tally is not active, i.e. when
154      * endObservations() has been called.
155      * @param timestamp Number; the object representing the timestamp
156      * @param value double; the value to process
157      * @return double; the value
158      * @throws NullPointerException when timestamp is null
159      * @throws IllegalArgumentException when value is NaN or timestamp is NaN
160      * @throws IllegalArgumentException when given timestamp is before last timestamp
161      */
162     @Override
163     public double register(final Number timestamp, final double value)
164     {
165         super.register(timestamp, value);
166         try
167         {
168             if (hasListeners())
169             {
170                 this.eventProducer.fireEvent(StatisticsEvents.TIMESTAMPED_OBSERVATION_ADDED_EVENT,
171                         new Serializable[] {timestamp, value});
172                 fireEvents(timestamp);
173             }
174         }
175         catch (RemoteException exception)
176         {
177             throw new RuntimeException(exception);
178         }
179         return value;
180     }
181 
182     /**
183      * Explicit;y override the double value method signature of WeightedTally to call the right method.<br>
184      * Process one observed double value. Silently ignore when a value is registered, but tally is not active, i.e. when
185      * endObservations() has been called.
186      * @param timestamp Number; the object representing the timestamp
187      * @param value double; the value to process
188      * @return double; the value
189      * @throws NullPointerException when timestamp is null
190      * @throws IllegalArgumentException when value is NaN or timestamp is NaN
191      * @throws IllegalArgumentException when given timestamp is before last timestamp
192      */
193     @Override
194     public double register(final double timestamp, final double value)
195     {
196         return register((Number) Double.valueOf(timestamp), value);
197     }
198 
199     /**
200      * Method that can be overridden to fire own events or additional events when registering an observation.
201      * @param <T> a type for the timestamp that is Serializable and Comparable
202      * @param timestamp T; the timestamp to use in the TimedEvents
203      * @throws RemoteException on network error
204      */
205     protected <T extends Serializable & Comparable<T>> void fireEvents(final Serializable timestamp) throws RemoteException
206     {
207         // Note that All implementations of Number are Comparable and (by default) Serializable. So is Calendar.
208         @SuppressWarnings("unchecked")
209         T castedTimestamp = (T) timestamp;
210         fireTimedEvent(StatisticsEvents.TIMED_N_EVENT, getN(), castedTimestamp);
211         fireTimedEvent(StatisticsEvents.TIMED_MIN_EVENT, getMin(), castedTimestamp);
212         fireTimedEvent(StatisticsEvents.TIMED_MAX_EVENT, getMax(), castedTimestamp);
213         fireTimedEvent(StatisticsEvents.TIMED_WEIGHTED_POPULATION_MEAN_EVENT, getWeightedPopulationMean(), castedTimestamp);
214         fireTimedEvent(StatisticsEvents.TIMED_WEIGHTED_POPULATION_VARIANCE_EVENT, getWeightedPopulationVariance(),
215                 castedTimestamp);
216         fireTimedEvent(StatisticsEvents.TIMED_WEIGHTED_POPULATION_STDEV_EVENT, getWeightedPopulationStDev(), castedTimestamp);
217         fireTimedEvent(StatisticsEvents.TIMED_WEIGHTED_SUM_EVENT, getWeightedSum(), castedTimestamp);
218         fireTimedEvent(StatisticsEvents.TIMED_WEIGHTED_SAMPLE_MEAN_EVENT, getWeightedSampleMean(), castedTimestamp);
219         fireTimedEvent(StatisticsEvents.TIMED_WEIGHTED_SAMPLE_VARIANCE_EVENT, getWeightedSampleVariance(), castedTimestamp);
220         fireTimedEvent(StatisticsEvents.TIMED_WEIGHTED_SAMPLE_STDEV_EVENT, getWeightedSampleStDev(), castedTimestamp);
221     }
222 
223     /** {@inheritDoc} */
224     @Override
225     @SuppressWarnings("checkstyle:designforextension")
226     public String toString()
227     {
228         return "EventBasedWeightedTally" + super.toString().substring("WeightedTally".length());
229     }
230 
231 }