001/*
002 * JPPF.
003 * Copyright (C) 2005-2015 JPPF Team.
004 * http://www.jppf.org
005 *
006 * Licensed under the Apache License, Version 2.0 (the "License");
007 * you may not use this file except in compliance with the License.
008 * You may obtain a copy of the License at
009 *
010 *   http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018package org.jppf.utils.stats;
019
020import java.io.Serializable;
021import java.util.*;
022import java.util.concurrent.*;
023
024/**
025 * Instances of this class hold statistics snapshots.
026 * To create and add a new snapshot, <code>createSnapshot(String)</code> should be called first,
027 * before any call to one of the <code>addXXX()</code> methods, in order to respect thread safety.
028 * @author Laurent Cohen
029 */
030public class JPPFStatistics implements Serializable, Iterable<JPPFSnapshot>
031{
032  /**
033   * Explicit serialVersionUID.
034   */
035  private static final long serialVersionUID = 1L;
036  /**
037   * Contains all snapshots currently handled.
038   */
039  private final ConcurrentHashMap<String, JPPFSnapshot> snapshots = new ConcurrentHashMap<>();
040  /**
041   * The list of liteners.
042   */
043  private List<JPPFStatisticsListener> listeners = new CopyOnWriteArrayList<>();
044
045  /**
046   * Default constructor.
047   * @exclude
048   */
049  public JPPFStatistics()
050  {
051  }
052
053  /**
054   * Copy constructor.
055   * @param map the statistics map to copy.
056   * @exclude
057   */
058  private JPPFStatistics(final Map<String, JPPFSnapshot> map)
059  {
060    for (Map.Entry<String, JPPFSnapshot> entry: map.entrySet())
061      snapshots.put(entry.getKey(), entry.getValue().copy());
062  }
063
064  /**
065   * Get a snapshot specified by its label.
066   * @param label the label of the snapshot to look up.
067   * @return a {@link JPPFSnapshot} instance, or <code>null</code> if none could be found with the specified label.
068   */
069  public JPPFSnapshot getSnapshot(final String label)
070  {
071    return snapshots.get(label);
072  }
073
074  /**
075   * Create a snapshot with the specified label if it doesn't exist.
076   * If a snapshot with this label already exists, it is returned.
077   * @param label the label of the snapshot to create.
078   * @return a {@link JPPFSnapshot} instance representing the newly created snapshot or the exsting one.
079   * @exclude
080   */
081  public JPPFSnapshot createSnapshot(final String label)
082  {
083    return createSnapshot(false, label);
084  }
085
086  /**
087   * Create a snapshot with the specified label if it doesn't exist.
088   * If a snapshot with this label already exists, it is returned.
089   * @param label the label of the snapshot to create.
090   * @param cumulative determines whether updates are accumulated instead of simply stored as latest value.
091   * @return a {@link JPPFSnapshot} instance representing the newly created snapshot or the exsting one.
092   * @exclude
093   */
094  public JPPFSnapshot createSnapshot(final boolean cumulative, final String label)
095  {
096    JPPFSnapshot newSnapshot = cumulative ? new CumulativeSnapshot(label) : new NonCumulativeSnapshot(label);
097    JPPFSnapshot oldSnapshot = snapshots.putIfAbsent(label, newSnapshot);
098    JPPFSnapshot snapshot = oldSnapshot == null ? newSnapshot : oldSnapshot;
099    if (!listeners.isEmpty()) fireSnapshotAdded(snapshot.copy());
100    return snapshot;
101  }
102
103  /**
104   * Create a single value snapshot with the specified label if it doesn't exist.
105   * If a snapshot with this label already exists, it is returned.
106   * @param label the label of the snapshot to create.
107   * @return a {@link JPPFSnapshot} instance representing the newly created snapshot or the exsting one.
108   * @exclude
109   */
110  public JPPFSnapshot createSingleValueSnapshot(final String label)
111  {
112    JPPFSnapshot newSnapshot = new SingleValueSnapshot(label);
113    JPPFSnapshot oldSnapshot = snapshots.putIfAbsent(label, newSnapshot);
114    JPPFSnapshot snapshot = oldSnapshot == null ? newSnapshot : oldSnapshot;
115    if (!listeners.isEmpty()) fireSnapshotAdded(snapshot);
116    return snapshot;
117  }
118
119  /**
120   * Create an array of snapshots with the specified labels, if it doesn't exist.
121   * If one of the snapshots already exists, it is returned.
122   * @param labels the label of the snapshot to create.
123   * @return an array of {@link JPPFSnapshot} instances representing the newly created or exsting snapshots, in the smaez order as the input labels.
124   * @exclude
125   */
126  public JPPFSnapshot[] createSnapshots(final String...labels)
127  {
128    return createSnapshots(false, labels);
129  }
130
131  /**
132   * Create an array of snapshots with the specified labels, if they don't exist.
133   * If any of the snapshots already exists, it is returned.
134   * @param labels the label of the snapshot to create.
135   * @param cumulative determines whether updates are accumulated instead of simply stored as latest value.
136   * @return an array of {@link JPPFSnapshot} instances representing the newly created or exsting snapshots, in the smaez order as the input labels.
137   * @exclude
138   */
139  public JPPFSnapshot[] createSnapshots(final boolean cumulative, final String...labels)
140  {
141    JPPFSnapshot[] snapshots = new JPPFSnapshot[labels.length];
142    for (int i=0; i<labels.length; i++) snapshots[i] = createSnapshot(cumulative, labels[i]);
143    return snapshots;
144  }
145
146  /**
147   * Create an array of single value snapshots with the specified labels, if they don't exist.
148   * If any of the snapshots already exists, it is returned.
149   * @param labels the label of the snapshot to create.
150   * @return an array of {@link JPPFSnapshot} instances representing the newly created or exsting snapshots, in the smaez order as the input labels.
151   * @exclude
152   */
153  public JPPFSnapshot[] createSingleValueSnapshots(final String...labels)
154  {
155    JPPFSnapshot[] snapshots = new JPPFSnapshot[labels.length];
156    for (int i=0; i<labels.length; i++) snapshots[i] = createSingleValueSnapshot(labels[i]);
157    return snapshots;
158  }
159
160  /**
161   * Remove the snapshot with the specified label.
162   * If a snapshot with this label already exists, it is returned.
163   * @param label the label of the snapshot to create.
164   * @return a {@link JPPFSnapshot} instance representing the removed snapshot or <code>null</code> if the label is not in the map.
165   * @exclude
166   */
167  public JPPFSnapshot removeSnapshot(final String label)
168  {
169    JPPFSnapshot snapshot = snapshots.remove(label);
170    if (!listeners.isEmpty()) fireSnapshotRemoved(snapshot.copy());
171    return snapshot;
172  }
173
174  /**
175   * Add the specified value to the snapshot with the specified label.
176   * @param label the label of the snapshot to add the value to.
177   * @param value the accumulated sum of the values to add.
178   * @return a reference to the updated {@link JPPFSnapshot} object.
179   * @throws IllegalStateException if the snapshot does not exist.
180   * @exclude
181   */
182  public JPPFSnapshot addValue(final String label, final double value)
183  {
184    return addValues(label, value, 1L);
185  }
186
187  /**
188   * Add the specified values to the snapshot with the specified label.
189   * @param label the label of the snapshot to add the values to.
190   * @param accumulatedValues the accumulated sum of the values to add.
191   * @param count the number of values in the accumalated values.
192   * @return a reference to the updated {@link JPPFSnapshot} object.
193   * @throws IllegalStateException if the snapshot does not exist.
194   * @exclude
195   */
196  public JPPFSnapshot addValues(final String label, final double accumulatedValues, final long count)
197  {
198    JPPFSnapshot snapshot = snapshots.get(label);
199    if (snapshot == null) throw new IllegalStateException("snapshot '" + label + "' was either not created or removed!");
200    snapshot.addValues(accumulatedValues, count);
201    if (!listeners.isEmpty()) fireSnapshotUpdated(snapshot.copy());
202    return snapshot;
203  }
204
205  /**
206   * Build a copy of this stats object.
207   * @return a new <code>JPPFStats</code> instance, populated with the current values
208   * of the fields in this stats object.
209   * @exclude
210   */
211  public JPPFStatistics copy()
212  {
213    return new JPPFStatistics(snapshots);
214  }
215
216  @Override
217  public String toString()
218  {
219    StringBuilder sb = new StringBuilder();
220    sb.append("JPPF statistics:");
221    for (Map.Entry<String, JPPFSnapshot> entry: snapshots.entrySet()) sb.append('\n').append(entry.getValue());
222    return sb.toString();
223  }
224
225  /**
226   * Reset all contained snapshots to their initial values.
227   * @exclude
228   */
229  public void reset()
230  {
231    reset(null);
232  }
233
234  /**
235   * Reset all contained snapshots to their initial values.
236   * @param filter determines which snapshots will be reset.
237   * @exclude
238   */
239  public void reset(final JPPFStatistics.Filter filter)
240  {
241    for (Map.Entry<String, JPPFSnapshot> entry: snapshots.entrySet())
242    {
243      JPPFSnapshot snapshot = entry.getValue();
244      if ((filter == null) || filter.accept(snapshot)) snapshot.reset();
245    }
246  }
247
248  /**
249   * Remove all snapshots from this object.
250   * @exclude
251   */
252  public void clear()
253  {
254    snapshots.clear();
255  }
256
257  /**
258   * Get all the snapshots in this object.
259   * @return a collection of {@link JPPFSnapshot} instances.
260   */
261  public Collection<JPPFSnapshot> getSnapshots()
262  {
263    return new ArrayList<>(snapshots.values());
264  }
265
266  /**
267   * Get the snapshots in this object using the specified filter.
268   * @param filter determines which snapshots will be part of the returned collection.
269   * @return a collection of {@link JPPFSnapshot} instances, possibly empty but never null.
270   */
271  public Collection<JPPFSnapshot> getSnapshots(final Filter filter)
272  {
273    List<JPPFSnapshot> list = new ArrayList<>(snapshots.size());
274    for (Map.Entry<String, JPPFSnapshot> entry: snapshots.entrySet())
275    {
276      JPPFSnapshot snapshot = entry.getValue();
277      if ((filter == null) || filter.accept(snapshot)) list.add(snapshot);
278    }
279    return list;
280  }
281
282  /**
283   * Add a listener to the list of listeners.
284   * @param listener the listener to add.
285   * @exclude
286   */
287  public void addListener(final JPPFStatisticsListener listener)
288  {
289    if (listener != null) listeners.add(listener);
290  }
291
292  /**
293   * Remove a listener to the list of listeners.
294   * @param listener the listener to remove.
295   * @exclude
296   */
297  public void removeListener(final JPPFStatisticsListener listener)
298  {
299    if (listener != null) listeners.remove(listener);
300  }
301
302  /**
303   * Notify all listeners that a snapshot was created.
304   * @param snapshot a copy of the created snapshot.
305   * @exclude
306   */
307  private void fireSnapshotAdded(final JPPFSnapshot snapshot)
308  {
309    JPPFStatisticsEvent event = new JPPFStatisticsEvent(snapshot);
310    for (JPPFStatisticsListener listener: listeners) listener.snapshotAdded(event);
311  }
312
313  /**
314   * Notify all listeners that a snapshot was updated.
315   * @param snapshot a copy of the updated snapshot.
316   * @exclude
317   */
318  private void fireSnapshotUpdated(final JPPFSnapshot snapshot)
319  {
320    JPPFStatisticsEvent event = new JPPFStatisticsEvent(snapshot);
321    for (JPPFStatisticsListener listener: listeners) listener.snapshotUpdated(event);
322  }
323
324  /**
325   * Notify all listeners that a snapshot was removed.
326   * @param snapshot a copy of the removed snapshot.
327   * @exclude
328   */
329  private void fireSnapshotRemoved(final JPPFSnapshot snapshot)
330  {
331    JPPFStatisticsEvent event = new JPPFStatisticsEvent(snapshot);
332    for (JPPFStatisticsListener listener: listeners) listener.snapshotRemoved(event);
333  }
334
335  @Override
336  public Iterator<JPPFSnapshot> iterator()
337  {
338    return snapshots.values().iterator();
339  }
340
341  /**
342   * A filter interface for snapshots.
343   */
344  public interface Filter
345  {
346    /**
347     * Determines whether the specified snapshot is accepted by this filter.
348     * @param snapshot the snapshot to check.
349     * @return <code>true</code> if the snapshot is accepted, <code>false</code> otherwise.
350     */
351    boolean accept(JPPFSnapshot snapshot);
352  }
353}