vaadin-framework/client/src/main/java/com/vaadin/client/data/CacheStrategy.java

/*
 * Copyright 2000-2016 Vaadin Ltd.
 *
 * Licensed 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 com.vaadin.client.data;

import com.vaadin.shared.Range;

/**
 * Determines what data an {@link AbstractRemoteDataSource} should fetch and
 * keep cached.
 *
 * @since 7.4
 * @author Vaadin Ltd
 */
public interface CacheStrategy {
    /**
     * A helper class for creating a simple symmetric cache strategy that uses
     * the same logic for both rows before and after the currently cached range.
     * <p>
     * This simple approach rules out more advanced heuristics that would take
     * the current scrolling direction or past scrolling behavior into account.
     */
    public static abstract class AbstractBasicSymmetricalCacheStrategy
            implements CacheStrategy {

        @Override
        public void onDataArrive(double roundTripTime, int rowCount) {
            // NOP
        }

        @Override
        public Range getMinCacheRange(Range displayedRange, Range cachedRange,
                Range estimatedAvailableRange) {
            int cacheSize = getMinimumCacheSize(displayedRange.length());

            return displayedRange.expand(cacheSize, cacheSize)
                    .restrictTo(estimatedAvailableRange);
        }

        @Override
        public Range getMaxCacheRange(Range displayedRange, Range cachedRange,
                Range estimatedAvailableRange) {
            int cacheSize = getMaximumCacheSize(displayedRange.length());

            return displayedRange.expand(cacheSize, cacheSize)
                    .restrictTo(estimatedAvailableRange);
        }

        /**
         * Gets the maximum number of extra items to cache in one direction.
         *
         * @param pageSize
         *            the current number of items used at once
         * @return maximum of items to cache
         */
        public abstract int getMaximumCacheSize(int pageSize);

        /**
         * Gets the the minimum number of extra items to cache in one direction.
         *
         * @param pageSize
         *            the current number of items used at once
         * @return minimum number of items to cache
         */
        public abstract int getMinimumCacheSize(int pageSize);
    }

    /**
     * The default cache strategy used by {@link AbstractRemoteDataSource},
     * using multiples of the page size for determining the minimum and maximum
     * number of items to keep in the cache. By default, at least three times
     * the page size both before and after the currently used range are kept in
     * the cache and items are discarded if there's yet another page size worth
     * of items cached in either direction.
     */
    public static class DefaultCacheStrategy
            extends AbstractBasicSymmetricalCacheStrategy {
        private final int minimumRatio;
        private final int maximumRatio;

        /**
         * Creates a DefaultCacheStrategy keeping between 3 and 4 pages worth of
         * data cached both before and after the active range.
         */
        public DefaultCacheStrategy() {
            this(3, 4);
        }

        /**
         * Creates a DefaultCacheStrategy with custom ratios for how much data
         * to cache. The ratios denote how many multiples of the currently used
         * page size are kept in the cache in each direction.
         *
         * @param minimumRatio
         *            the minimum number of pages to keep in the cache in each
         *            direction
         * @param maximumRatio
         *            the maximum number of pages to keep in the cache in each
         *            direction
         */
        public DefaultCacheStrategy(int minimumRatio, int maximumRatio) {
            this.minimumRatio = minimumRatio;
            this.maximumRatio = maximumRatio;
        }

        @Override
        public int getMinimumCacheSize(int pageSize) {
            return pageSize * minimumRatio;
        }

        @Override
        public int getMaximumCacheSize(int pageSize) {
            return pageSize * maximumRatio;
        }
    }

    /**
     * Called whenever data requested by the data source has arrived. This
     * information can e.g. be used for measuring how long it takes to fetch
     * different number of rows from the server.
     * <p>
     * A cache strategy implementation cannot use this information to keep track
     * of which items are in the cache since the data source might discard items
     * without notifying the cache strategy.
     *
     * @param roundTripTime
     *            the total number of milliseconds elapsed from requesting the
     *            data until the response was passed to the data source
     * @param rowCount
     *            the number of received rows
     */
    public void onDataArrive(double roundTripTime, int rowCount);

    /**
     * Gets the minimum row range that should be cached. The data source will
     * fetch new data if the currently cached range does not fill the entire
     * minimum cache range.
     *
     * @param displayedRange
     *            the range of currently displayed rows
     * @param cachedRange
     *            the range of currently cached rows
     * @param estimatedAvailableRange
     *            the estimated range of rows available for the data source
     *
     * @return the minimum range of rows that should be cached, should at least
     *         include the displayed range and should not exceed the total
     *         estimated available range
     */
    public Range getMinCacheRange(Range displayedRange, Range cachedRange,
            Range estimatedAvailableRange);

    /**
     * Gets the maximum row range that should be cached. The data source will
     * discard cached rows that are outside the maximum range.
     *
     * @param displayedRange
     *            the range of currently displayed rows
     * @param cachedRange
     *            the range of currently cached rows
     * @param estimatedAvailableRange
     *            the estimated range of rows available for the data source
     *
     * @return the maximum range of rows that should be cached, should at least
     *         include the displayed range and should not exceed the total
     *         estimated available range
     */
    public Range getMaxCacheRange(Range displayedRange, Range cachedRange,
            Range estimatedAvailableRange);
}