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 | * http://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 | package agents.anac.y2019.harddealer.math3.util;
|
---|
18 |
|
---|
19 | import java.util.Collection;
|
---|
20 | import java.util.concurrent.CopyOnWriteArrayList;
|
---|
21 |
|
---|
22 | import agents.anac.y2019.harddealer.math3.exception.MaxCountExceededException;
|
---|
23 |
|
---|
24 | /**
|
---|
25 | * This abstract class provides a general framework for managing iterative
|
---|
26 | * algorithms. The maximum number of iterations can be set, and methods are
|
---|
27 | * provided to monitor the current iteration count. A lightweight event
|
---|
28 | * framework is also provided.
|
---|
29 | *
|
---|
30 | */
|
---|
31 | public class IterationManager {
|
---|
32 |
|
---|
33 | /** Keeps a count of the number of iterations. */
|
---|
34 | private IntegerSequence.Incrementor iterations;
|
---|
35 |
|
---|
36 | /** The collection of all listeners attached to this iterative algorithm. */
|
---|
37 | private final Collection<IterationListener> listeners;
|
---|
38 |
|
---|
39 | /**
|
---|
40 | * Creates a new instance of this class.
|
---|
41 | *
|
---|
42 | * @param maxIterations the maximum number of iterations
|
---|
43 | */
|
---|
44 | public IterationManager(final int maxIterations) {
|
---|
45 | this.iterations = IntegerSequence.Incrementor.create().withMaximalCount(maxIterations);
|
---|
46 | this.listeners = new CopyOnWriteArrayList<IterationListener>();
|
---|
47 | }
|
---|
48 |
|
---|
49 | /**
|
---|
50 | * Creates a new instance of this class.
|
---|
51 | *
|
---|
52 | * @param maxIterations the maximum number of iterations
|
---|
53 | * @param callBack the function to be called when the maximum number of
|
---|
54 | * iterations has been reached
|
---|
55 | * @throws agents.anac.y2019.harddealer.math3.exception.NullArgumentException if {@code callBack} is {@code null}
|
---|
56 | * @since 3.1
|
---|
57 | * @deprecated as of 3.6, replaced with {@link #IterationManager(int,
|
---|
58 | * agents.anac.y2019.harddealer.math3.util.IntegerSequence.Incrementor.MaxCountExceededCallback)}
|
---|
59 | */
|
---|
60 | @Deprecated
|
---|
61 | public IterationManager(final int maxIterations,
|
---|
62 | final Incrementor.MaxCountExceededCallback callBack) {
|
---|
63 | this(maxIterations, new IntegerSequence.Incrementor.MaxCountExceededCallback() {
|
---|
64 | /** {@inheritDoc} */
|
---|
65 | public void trigger(final int maximalCount) throws MaxCountExceededException {
|
---|
66 | callBack.trigger(maximalCount);
|
---|
67 | }
|
---|
68 | });
|
---|
69 | }
|
---|
70 |
|
---|
71 | /**
|
---|
72 | * Creates a new instance of this class.
|
---|
73 | *
|
---|
74 | * @param maxIterations the maximum number of iterations
|
---|
75 | * @param callBack the function to be called when the maximum number of
|
---|
76 | * iterations has been reached
|
---|
77 | * @throws agents.anac.y2019.harddealer.math3.exception.NullArgumentException if {@code callBack} is {@code null}
|
---|
78 | * @since 3.6
|
---|
79 | */
|
---|
80 | public IterationManager(final int maxIterations,
|
---|
81 | final IntegerSequence.Incrementor.MaxCountExceededCallback callBack) {
|
---|
82 | this.iterations = IntegerSequence.Incrementor.create().withMaximalCount(maxIterations).withCallback(callBack);
|
---|
83 | this.listeners = new CopyOnWriteArrayList<IterationListener>();
|
---|
84 | }
|
---|
85 |
|
---|
86 | /**
|
---|
87 | * Attaches a listener to this manager.
|
---|
88 | *
|
---|
89 | * @param listener A {@code IterationListener} object.
|
---|
90 | */
|
---|
91 | public void addIterationListener(final IterationListener listener) {
|
---|
92 | listeners.add(listener);
|
---|
93 | }
|
---|
94 |
|
---|
95 | /**
|
---|
96 | * Informs all registered listeners that the initial phase (prior to the
|
---|
97 | * main iteration loop) has been completed.
|
---|
98 | *
|
---|
99 | * @param e The {@link IterationEvent} object.
|
---|
100 | */
|
---|
101 | public void fireInitializationEvent(final IterationEvent e) {
|
---|
102 | for (IterationListener l : listeners) {
|
---|
103 | l.initializationPerformed(e);
|
---|
104 | }
|
---|
105 | }
|
---|
106 |
|
---|
107 | /**
|
---|
108 | * Informs all registered listeners that a new iteration (in the main
|
---|
109 | * iteration loop) has been performed.
|
---|
110 | *
|
---|
111 | * @param e The {@link IterationEvent} object.
|
---|
112 | */
|
---|
113 | public void fireIterationPerformedEvent(final IterationEvent e) {
|
---|
114 | for (IterationListener l : listeners) {
|
---|
115 | l.iterationPerformed(e);
|
---|
116 | }
|
---|
117 | }
|
---|
118 |
|
---|
119 | /**
|
---|
120 | * Informs all registered listeners that a new iteration (in the main
|
---|
121 | * iteration loop) has been started.
|
---|
122 | *
|
---|
123 | * @param e The {@link IterationEvent} object.
|
---|
124 | */
|
---|
125 | public void fireIterationStartedEvent(final IterationEvent e) {
|
---|
126 | for (IterationListener l : listeners) {
|
---|
127 | l.iterationStarted(e);
|
---|
128 | }
|
---|
129 | }
|
---|
130 |
|
---|
131 | /**
|
---|
132 | * Informs all registered listeners that the final phase (post-iterations)
|
---|
133 | * has been completed.
|
---|
134 | *
|
---|
135 | * @param e The {@link IterationEvent} object.
|
---|
136 | */
|
---|
137 | public void fireTerminationEvent(final IterationEvent e) {
|
---|
138 | for (IterationListener l : listeners) {
|
---|
139 | l.terminationPerformed(e);
|
---|
140 | }
|
---|
141 | }
|
---|
142 |
|
---|
143 | /**
|
---|
144 | * Returns the number of iterations of this solver, 0 if no iterations has
|
---|
145 | * been performed yet.
|
---|
146 | *
|
---|
147 | * @return the number of iterations.
|
---|
148 | */
|
---|
149 | public int getIterations() {
|
---|
150 | return iterations.getCount();
|
---|
151 | }
|
---|
152 |
|
---|
153 | /**
|
---|
154 | * Returns the maximum number of iterations.
|
---|
155 | *
|
---|
156 | * @return the maximum number of iterations.
|
---|
157 | */
|
---|
158 | public int getMaxIterations() {
|
---|
159 | return iterations.getMaximalCount();
|
---|
160 | }
|
---|
161 |
|
---|
162 | /**
|
---|
163 | * Increments the iteration count by one, and throws an exception if the
|
---|
164 | * maximum number of iterations is reached. This method should be called at
|
---|
165 | * the beginning of a new iteration.
|
---|
166 | *
|
---|
167 | * @throws MaxCountExceededException if the maximum number of iterations is
|
---|
168 | * reached.
|
---|
169 | */
|
---|
170 | public void incrementIterationCount()
|
---|
171 | throws MaxCountExceededException {
|
---|
172 | iterations.increment();
|
---|
173 | }
|
---|
174 |
|
---|
175 | /**
|
---|
176 | * Removes the specified iteration listener from the list of listeners
|
---|
177 | * currently attached to {@code this} object. Attempting to remove a
|
---|
178 | * listener which was <em>not</em> previously registered does not cause any
|
---|
179 | * error.
|
---|
180 | *
|
---|
181 | * @param listener The {@link IterationListener} to be removed.
|
---|
182 | */
|
---|
183 | public void removeIterationListener(final IterationListener listener) {
|
---|
184 | listeners.remove(listener);
|
---|
185 | }
|
---|
186 |
|
---|
187 | /**
|
---|
188 | * Sets the iteration count to 0. This method must be called during the
|
---|
189 | * initial phase.
|
---|
190 | */
|
---|
191 | public void resetIterationCount() {
|
---|
192 | iterations = iterations.withStart(0);
|
---|
193 | }
|
---|
194 | }
|
---|