vaadin-framework/client/src/main/java/com/vaadin/client/data/DataSource.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 java.util.function.Consumer;

import com.vaadin.shared.Range;
import com.vaadin.shared.Registration;

/**
 * Source of data for widgets showing lazily loaded data based on indexable
 * items (e.g. rows) of a specified type. The data source is a lazy view into a
 * larger data set.
 *
 * @since 7.4
 * @author Vaadin Ltd
 * @param <T>
 *            the row type
 */
public interface DataSource<T> {

    /**
     * A handle that contains information on whether a row should be
     * {@link #pin() pinned} or {@link #unpin() unpinned}, and also always the
     * most recent representation for that particular row.
     *
     * @param <T>
     *            the row type
     */
    public abstract class RowHandle<T> {
        /**
         * Gets the most recent representation for the row this handle
         * represents.
         *
         * @return the most recent representation for the row this handle
         *         represents
         * @throws IllegalStateException
         *             if this row handle isn't currently pinned
         * @see #pin()
         */
        public abstract T getRow() throws IllegalStateException;

        /**
         * Marks this row as pinned.
         * <p>
         * <em>Note:</em> Pinning a row multiple times requires an equal amount
         * of unpins to free the row from the "pinned" status.
         * <p>
         * <em>Technical Note:</em> Pinning a row makes sure that the row object
         * for a particular set of data is always kept as up to date as the data
         * source is able to. Since the DataSource might create a new instance
         * of an object, object references aren't necessarily kept up-to-date.
         * This is a technical work-around for that.
         *
         * @see #unpin()
         */
        public abstract void pin();

        /**
         * Marks this row as unpinned.
         * <p>
         * <em>Note:</em> Pinning a row multiple times requires an equal amount
         * of unpins to free the row from the "pinned" status.
         * <p>
         * <em>Technical Note:</em> Pinning a row makes sure that the row object
         * for a particular set of data is always kept as up to date as the data
         * source is able to. Since the DataSource might create a new instance
         * of an object, object references aren't necessarily kept up-to-date.
         * This is a technical work-around for that.
         *
         * @throws IllegalStateException
         *             if this row handle has not been pinned before
         * @see #pin()
         */
        public abstract void unpin() throws IllegalStateException;

        /**
         * Informs the DataSource that the row data represented by this
         * RowHandle has been updated. DataChangeHandler for the DataSource
         * should be informed that parts of data have been updated.
         *
         * @see DataChangeHandler#dataUpdated(int, int)
         */
        public abstract void updateRow();

        /**
         * An explicit override for {@link Object#equals(Object)}. This method
         * should be functionally equivalent to a properly implemented equals
         * method.
         * <p>
         * Having a properly implemented equals method is imperative for
         * RowHandle to function. Because Java has no mechanism to force an
         * override of an existing method, we're defining a new method for that
         * instead.
         *
         * @param obj
         *            the reference object with which to compare
         * @return {@code true} if this object is the same as the obj argument;
         *         {@code false} otherwise.
         */
        protected abstract boolean equalsExplicit(Object obj);

        /**
         * An explicit override for {@link Object#hashCode()}. This method
         * should be functionally equivalent to a properly implemented hashCode
         * method.
         * <p>
         * Having a properly implemented hashCode method is imperative for
         * RowHandle to function. Because Java has no mechanism to force an
         * override of an existing method, we're defining a new method for that
         * instead.
         *
         * @return a hash code value for this object
         */
        protected abstract int hashCodeExplicit();

        @Override
        public int hashCode() {
            return hashCodeExplicit();
        }

        @Override
        public boolean equals(Object obj) {
            return equalsExplicit(obj);
        }
    }

    /**
     * Informs the data source that data for the given range is needed. A data
     * source only has one active region at a time, so calling this method
     * discards the previously set range.
     * <p>
     * This method triggers lazy loading of data if necessary. The change
     * handler registered using {@link #addDataChangeHandler(DataChangeHandler)}
     * is informed when new data has been loaded.
     * <p>
     * After any possible lazy loading and updates are done, the change handler
     * is informed that new data is available.
     *
     * @param firstRowIndex
     *            the index of the first needed row
     * @param numberOfRows
     *            the number of needed rows
     */
    public void ensureAvailability(int firstRowIndex, int numberOfRows);

    /**
     * Retrieves the data for the row at the given index. If the row data is not
     * available, returns <code>null</code>.
     * <p>
     * This method does not trigger loading of unavailable data.
     * {@link #ensureAvailability(int, int)} should be used to signal what data
     * will be needed.
     *
     * @param rowIndex
     *            the index of the row to retrieve data for
     * @return data for the row; or <code>null</code> if no data is available
     */
    public T getRow(int rowIndex);

    /**
     * Returns the number of rows in the data source.
     *
     * @return the current size of the data source
     */
    public int size();

    /**
     * Sets a data change handler to inform when data is updated, added or
     * removed.
     *
     * @param dataChangeHandler
     *            the data change handler
     *
     * @return registration for removing the handler
     */
    public Registration addDataChangeHandler(
            DataChangeHandler dataChangeHandler);

    /**
     * Sets a simple data change handler for a widget without lazy loading.
     * Refresh method should reset all the data in the widget.
     *
     * @param refreshMethod
     *            a method to refresh all data in the widget
     *
     * @return registration for removing the handler
     */
    public default Registration addDataChangeHandler(
            Consumer<Range> refreshMethod) {
        return addDataChangeHandler(
                new SimpleDataChangeHandler(this, refreshMethod));
    }

    /**
     * Gets a {@link RowHandle} of a row object in the cache.
     *
     * @param row
     *            the row object for which to retrieve a row handle
     * @return a non-<code>null</code> row handle of the given row object
     * @throw IllegalStateException if this data source cannot be sure whether
     *        or not the given row exists. <em>In practice</em> this usually
     *        means that the row is not currently in this data source's cache.
     */
    public RowHandle<T> getHandle(T row);

    /**
     * Checks whether this data source is currently waiting for more rows to
     * become available.
     *
     * @return <code>true</code> if waiting for data; otherwise
     *         <code>false</code>
     * @since 7.7.2
     */
    public boolean isWaitingForData();
}