001package org.javasimon;
002
003/**
004 * Counter tracks the single integer value and watches its max/min values. It can be used
005 * for values starting with 0 - in that case min might not be important if counter does not
006 * go bellow 0. Counter can also start from any other arbitrary number that is set after the
007 * first change (increment, decrement, set) - this is more typical case for tracking also the
008 * min value.
009 * <p/>
010 * <h3>Initialization</h3>
011 * When a counter is created, it is set to 0, but its maximum/minimum values are undefined:
012 * <pre>
013 * Counter counter = SimonManager.getCounter("com.my.counter");
014 * System.out.println("counter = " + counter);</pre>
015 * Output is:
016 * <pre>
017 * counter = Simon Counter: [com.my.counter INHERIT] counter=0, max=undef, min=undef</pre>
018 *
019 * This behavior allows the counter to be initialized before it is used and its extremes are
020 * tracked - first initialization also sets max/min (extreme) values:
021 * <pre>
022 * Counter counter = SimonManager.getCounter("com.my.counter").set(47);
023 * System.out.println("counter = " + counter);</pre>
024 * Output is:
025 * <pre>
026 * counter = Simon Counter: [com.my.counter INHERIT] counter=47, max=47, min=47</pre>
027 *
028 * <h3>Usage</h3>
029 * Typical Counter usage is based on {@link #increase()} and {@link #decrease()} methods when
030 * it is possible to track the monitored value - this can be used for example to count users logged
031 * in. If the value changes by more than 1 than it is possible to use methods with arguments -
032 * {@link #increase(long)} and {@link #decrease(long)}. Finally method {@link #set(long)} is
033 * always available to set the counter to the particular value when needed.
034 *
035 * @author <a href="mailto:virgo47@gmail.com">Richard "Virgo" Richter</a>
036 */
037public interface Counter extends Simon {
038
039        /**
040         * Increments the counter by one.
041         *
042         * @return this
043         */
044        Counter increase();
045
046        /**
047         * Decrements the counter by one.
048         *
049         * @return this
050         */
051        Counter decrease();
052
053        /**
054         * Increments the counter by the specified value. Using negative values is possible but may provide
055         * unexpected results - this method updates only incrementSum, it is decreased when negative number is used.
056         * Min and max are updated as expected.
057         *
058         * @param inc added value
059         * @return this
060         */
061        Counter increase(long inc);
062
063        /**
064         * Increments the counter by the specified value. Using negative values is possible but may provide
065         * unexpected results - this method updates only decrementSum, it is decreased when negative number is used.
066         * Min and max are updated as expected.
067         *
068         * @param dec subtracted value
069         * @return this
070         */
071        Counter decrease(long dec);
072
073        /**
074         * Returns the current value of the counter.
075         *
076         * @return counter value
077         */
078        long getCounter();
079
080        /**
081         * Returns minimal value of counter. Updated by {@link #decrease()}, {@link #decrease(long)} and {@link #set(long)}.
082         *
083         * @return maximal reached value
084         */
085        long getMin();
086
087        /**
088         * Returns ms timestamp when the min value was reached.
089         *
090         * @return ms timestamp of the min value decremented
091         */
092        long getMinTimestamp();
093
094        /**
095         * Returns maximal value of counter. Updated by {@link #increase()}, {@link #increase(long)} and {@link #set(long)}.
096         *
097         * @return maximal reached value
098         */
099        long getMax();
100
101        /**
102         * Returns ms timestamp when the max value was reached.
103         *
104         * @return ms timestamp of the max value incremented
105         */
106        long getMaxTimestamp();
107
108        /**
109         * Sets the value of the counter to specified value.
110         *
111         * @param val new counter value
112         * @return this
113         */
114        Counter set(long val);
115
116        /**
117         * Returns the sum of all incremented values. If incremented value was negative, sum
118         * is lowered by this value.
119         *
120         * @return sum of all incremented values
121         */
122        long getIncrementSum();
123
124        /**
125         * Returns the sum of all decremented values (as a positive number). If decremented value was negative, sum
126         * is lowered by this value.
127         *
128         * @return sum of all decremented values
129         */
130        long getDecrementSum();
131
132        @Override
133        CounterSample sample();
134
135        CounterSample sampleIncrement(Object key);
136        CounterSample sampleIncrementNoReset(Object key);
137}