View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      https://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  
18  /*
19   * This is not the original file distributed by the Apache Software Foundation
20   * It has been modified by the Hipparchus project
21   */
22  package org.hipparchus.util;
23  
24  import org.hipparchus.exception.LocalizedCoreFormats;
25  import org.hipparchus.exception.MathIllegalArgumentException;
26  import org.hipparchus.exception.MathIllegalStateException;
27  import org.hipparchus.exception.NullArgumentException;
28  
29  /**
30   * Utility that increments a counter until a maximum is reached, at
31   * which point, the instance will by default throw a
32   * {@link MathIllegalStateException}.
33   * However, the user is able to override this behaviour by defining a
34   * custom {@link MaxCountExceededCallback callback}, in order to e.g.
35   * select which exception must be thrown.
36   */
37  public class Incrementor {
38      /** Default callback. */
39      private static final MaxCountExceededCallback DEFAULT_CALLBACK =
40          (int max) -> {
41              throw new MathIllegalStateException(LocalizedCoreFormats.MAX_COUNT_EXCEEDED, max);
42          };
43  
44      /** Upper limit for the counter. */
45      private final int maximalCount;
46      /** Function called at counter exhaustion. */
47      private final MaxCountExceededCallback maxCountCallback;
48      /** Current count. */
49      private int count;
50  
51      /**
52       * Defines a method to be called at counter exhaustion.
53       * The {@link #trigger(int) trigger} method should usually throw an exception.
54       */
55      @FunctionalInterface
56      public interface MaxCountExceededCallback {
57          /**
58           * Function called when the maximal count has been reached.
59           *
60           * @param maximalCount Maximal count.
61           * @throws MathIllegalStateException at counter exhaustion
62           */
63          void trigger(int maximalCount) throws MathIllegalStateException;
64      }
65  
66      /**
67       * Creates an Incrementor.
68       * <p>
69       * The maximal value will be set to {@code Integer.MAX_VALUE}.
70       */
71      public Incrementor() {
72          this(Integer.MAX_VALUE);
73      }
74  
75      /**
76       * Creates an Incrementor.
77       *
78       * @param max Maximal count.
79       * @throws MathIllegalArgumentException if {@code max} is negative.
80       */
81      public Incrementor(int max) {
82          this(max, DEFAULT_CALLBACK);
83      }
84  
85      /**
86       * Creates an Incrementor.
87       *
88       * @param max Maximal count.
89       * @param cb Function to be called when the maximal count has been reached.
90       * @throws NullArgumentException if {@code cb} is {@code null}.
91       * @throws MathIllegalArgumentException if {@code max} is negative.
92       */
93      public Incrementor(int max,
94                          MaxCountExceededCallback cb)
95          throws NullArgumentException {
96          this(0, max, cb);
97      }
98  
99      /**
100      * Creates an Incrementor.
101      *
102      * @param count Initial counter value.
103      * @param max Maximal count.
104      * @param cb Function to be called when the maximal count has been reached.
105      * @throws NullArgumentException if {@code cb} is {@code null}.
106      * @throws MathIllegalArgumentException if {@code max} is negative.
107      */
108     private Incrementor(int count,
109                         int max,
110                         MaxCountExceededCallback cb)
111         throws NullArgumentException {
112         if (cb == null) {
113             throw new NullArgumentException();
114         }
115         if (max < 0) {
116             throw new MathIllegalArgumentException(LocalizedCoreFormats.NUMBER_TOO_SMALL, max, 0);
117         }
118         this.maximalCount = max;
119         this.maxCountCallback = cb;
120         this.count = count;
121     }
122 
123     /**
124      * Creates a new instance and set the counter to the given value.
125      *
126      * @param value Value of the counter.
127      * @return a new instance.
128      */
129     public Incrementor withCount(int value) {
130         return new Incrementor(value,
131                                this.maximalCount,
132                                this.maxCountCallback);
133     }
134 
135     /**
136      * Creates a new instance with a given maximal count.
137      * The counter is reset to 0.
138      *
139      * @param max Maximal count.
140      * @return a new instance.
141      * @throws MathIllegalArgumentException if {@code max} is negative.
142      */
143     public Incrementor withMaximalCount(int max) {
144         return new Incrementor(0,
145                                max,
146                                this.maxCountCallback);
147     }
148 
149     /**
150      * Creates a new instance with a given callback.
151      * The counter is reset to 0.
152      *
153      * @param cb Callback to be called at counter exhaustion.
154      * @return a new instance.
155      */
156     public Incrementor withCallback(MaxCountExceededCallback cb) {
157         return new Incrementor(0,
158                                this.maximalCount,
159                                cb);
160     }
161 
162     /**
163      * Gets the upper limit of the counter.
164      *
165      * @return the counter upper limit.
166      */
167     public int getMaximalCount() {
168         return maximalCount;
169     }
170 
171     /**
172      * Gets the current count.
173      *
174      * @return the current count.
175      */
176     public int getCount() {
177         return count;
178     }
179 
180     /**
181      * Checks whether incrementing the counter {@code nTimes} is allowed.
182      *
183      * @return {@code false} if calling {@link #increment()}
184      * will trigger a {@code MathIllegalStateException},
185      * {@code true} otherwise.
186      */
187     public boolean canIncrement() {
188         return canIncrement(1);
189     }
190 
191     /**
192      * Checks whether incrementing the counter several times is allowed.
193      *
194      * @param nTimes Number of increments.
195      * @return {@code false} if calling {@link #increment(int)
196      * increment(nTimes)} would call the {@link MaxCountExceededCallback callback}
197      * {@code true} otherwise.
198      * @throws MathIllegalArgumentException if {@code nTimes} is negative.
199      */
200     public boolean canIncrement(int nTimes) {
201         if (nTimes < 0) {
202             throw new MathIllegalArgumentException(LocalizedCoreFormats.NUMBER_TOO_SMALL,
203                                                    nTimes, 0);
204         }
205         return count <= maximalCount - nTimes;
206     }
207 
208     /**
209      * Performs multiple increments.
210      *
211      * @param nTimes Number of increments.
212      * @throws MathIllegalArgumentException if {@code nTimes} is negative.
213      *
214      * @see #increment()
215      */
216     public void increment(int nTimes) {
217         if (nTimes < 0) {
218             throw new MathIllegalArgumentException(LocalizedCoreFormats.NUMBER_TOO_SMALL,
219                                                    nTimes, 0);
220         }
221 
222         for (int i = 0; i < nTimes; i++) {
223             increment();
224         }
225     }
226 
227     /**
228      * Adds the increment value to the current iteration count.
229      * At counter exhaustion, this method will call the
230      * {@link MaxCountExceededCallback#trigger(int) trigger} method of the
231      * callback object passed to the
232      * {@link #withCallback(MaxCountExceededCallback)} method.
233      *
234      * @see #increment(int)
235      */
236     public void increment() {
237         if (count > maximalCount - 1) {
238             maxCountCallback.trigger(maximalCount);
239         }
240         ++count;
241     }
242 
243     /**
244      * Resets the counter to 0.
245      */
246     public void reset() {
247         count = 0;
248     }
249 }