org.apache.commons.math3.util.Incrementor Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of cf4j-recsys Show documentation
A Java's Collaborative Filtering library to carry out experiments in research of Collaborative Filtering based Recommender Systems. The library has been designed from researchers to researchers.
The newest version!
/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.commons.math3.util;

import org.apache.commons.math3.exception.MaxCountExceededException;
import org.apache.commons.math3.exception.NullArgumentException;

/**
 * Utility that increments a counter until a maximum is reached, at
 * which point, the instance will by default throw a
 * {@link MaxCountExceededException}.
 * However, the user is able to override this behaviour by defining a
 * custom {@link MaxCountExceededCallback callback}, in order to e.g.
 * select which exception must be thrown.
 *
 * @since 3.0
 * @deprecated Use {@link IntegerSequence.Incrementor} instead.
 */
@Deprecated
public class Incrementor {
    /**
     * Upper limit for the counter.
     */
    private int maximalCount;
    /**
     * Current count.
     */
    private int count = 0;
    /**
     * Function called at counter exhaustion.
     */
    private final MaxCountExceededCallback maxCountCallback;

    /**
     * Default constructor.
     * For the new instance to be useful, the maximal count must be set
     * by calling {@link #setMaximalCount(int) setMaximalCount}.
     */
    public Incrementor() {
        this(0);
    }

    /**
     * Defines a maximal count.
     *
     * @param max Maximal count.
     */
    public Incrementor(int max) {
        this(max,
             new MaxCountExceededCallback() {
                 /** {@inheritDoc} */
                 public void trigger(int max) throws MaxCountExceededException {
                     throw new MaxCountExceededException(max);
                 }
             });
    }

    /**
     * Defines a maximal count and a callback method to be triggered at
     * counter exhaustion.
     *
     * @param max Maximal count.
     * @param cb Function to be called when the maximal count has been reached.
     * @throws NullArgumentException if {@code cb} is {@code null}
     */
    public Incrementor(int max, MaxCountExceededCallback cb)
        throws NullArgumentException {
        if (cb == null){
            throw new NullArgumentException();
        }
        maximalCount = max;
        maxCountCallback = cb;
    }

    /**
     * Sets the upper limit for the counter.
     * This does not automatically reset the current count to zero (see
     * {@link #resetCount()}).
     *
     * @param max Upper limit of the counter.
     */
    public void setMaximalCount(int max) {
        maximalCount = max;
    }

    /**
     * Gets the upper limit of the counter.
     *
     * @return the counter upper limit.
     */
    public int getMaximalCount() {
        return maximalCount;
    }

    /**
     * Gets the current count.
     *
     * @return the current count.
     */
    public int getCount() {
        return count;
    }

    /**
     * Checks whether a single increment is allowed.
     *
     * @return {@code false} if the next call to {@link #incrementCount(int)
     * incrementCount} will trigger a {@code MaxCountExceededException},
     * {@code true} otherwise.
     */
    public boolean canIncrement() {
        return count < maximalCount;
    }

    /**
     * Performs multiple increments.
     * See the other {@link #incrementCount() incrementCount} method).
     *
     * @param value Number of increments.
     * @throws MaxCountExceededException at counter exhaustion.
     */
    public void incrementCount(int value) throws MaxCountExceededException {
        for (int i = 0; i < value; i++) {
            incrementCount();
        }
    }

    /**
     * Adds one to the current iteration count.
     * At counter exhaustion, this method will call the
     * {@link MaxCountExceededCallback#trigger(int) trigger} method of the
     * callback object passed to the
     * {@link #Incrementor(int,MaxCountExceededCallback) constructor}.
     * If not explictly set, a default callback is used that will throw
     * a {@code MaxCountExceededException}.
     *
     * @throws MaxCountExceededException at counter exhaustion, unless a
     * custom {@link MaxCountExceededCallback callback} has been set at
     * construction.
     */
    public void incrementCount() throws MaxCountExceededException {
        if (++count > maximalCount) {
            maxCountCallback.trigger(maximalCount);
        }
    }

    /**
     * Resets the counter to 0.
     */
    public void resetCount() {
        count = 0;
    }

    /**
     * Defines a method to be called at counter exhaustion.
     * The {@link #trigger(int) trigger} method should usually throw an exception.
     */
    public interface MaxCountExceededCallback {
        /**
         * Function called when the maximal count has been reached.
         *
         * @param maximalCount Maximal count.
         * @throws MaxCountExceededException at counter exhaustion
         */
        void trigger(int maximalCount) throws MaxCountExceededException;
    }

    /** Create an instance that delegates everything to a {@link IntegerSequence.Incrementor}.
     * 
     * This factory method is intended only as a temporary hack for internal use in
     * Apache Commons Math 3.X series, when {@code Incrementor} is required in
     * interface (as a return value or in protected fields). It should not
     * be used in other cases. The {@link IntegerSequence.Incrementor} class should
     * be used instead of {@code Incrementor}.
     * 
     * 
     * All methods are mirrored to the underlying {@link IntegerSequence.Incrementor},
     * as long as neither {@link #setMaximalCount(int)} nor {@link #resetCount()} are called.
     * If one of these two methods is called, the created instance becomes independent
     * of the {@link IntegerSequence.Incrementor} used at creation. The rationale is that
     * {@link IntegerSequence.Incrementor} cannot change their maximal count and cannot be reset.
     * 
     * @param incrementor wrapped {@link IntegerSequence.Incrementor}
     * @return an incrementor wrapping an {@link IntegerSequence.Incrementor}
     * @since 3.6
     */
    public static Incrementor wrap(final IntegerSequence.Incrementor incrementor) {
        return new Incrementor() {

            /** Underlying incrementor. */
            private IntegerSequence.Incrementor delegate;

            {
                // set up matching values at initialization
                delegate = incrementor;
                super.setMaximalCount(delegate.getMaximalCount());
                super.incrementCount(delegate.getCount());
            }

            /** {@inheritDoc} */
            @Override
            public void setMaximalCount(int max) {
                super.setMaximalCount(max);
                delegate = delegate.withMaximalCount(max);
            }

            /** {@inheritDoc} */
            @Override
            public void resetCount() {
                super.resetCount();
                delegate = delegate.withStart(0);
            }

            /** {@inheritDoc} */
            @Override
            public void incrementCount() {
                super.incrementCount();
                delegate.increment();
            }

        };
    }

}