/*
 * (C) Copyright 2013 Nuxeo SA (http://nuxeo.com/) and others.
 *
 * 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.
 *
 * Contributors:
 *     Thomas Roger
 */
package org.nuxeo.ecm.platform.query.api;

import java.io.Serializable;
import java.util.List;
import java.util.Map;

import org.nuxeo.ecm.core.api.DocumentModel;
import org.nuxeo.ecm.core.api.SortInfo;

/**
 * Basic interface for a page provider, independent of type of items in the list
 * <p>
 * Provides APIs to navigate between result pages
 *
 * @param <T> any Serializable item
 * @since 5.4
 * @author arussel
 * @author Anahide Tchertchian
 */
public interface PageProvider<T> extends Serializable {

    public static final String DEFAULT_MAX_PAGE_SIZE_RUNTIME_PROP = "nuxeo.pageprovider.default-max-page-size";

    /**
     * Constant to express that the total number of result elements is unknown (usually because the query has not been
     * done yet).
     */
    public static final long UNKNOWN_SIZE = -1;

    /**
     * Constant to express that the total number of result elements is unknown even after performing a query.
     *
     * @since 5.5
     */
    public static final long UNKNOWN_SIZE_AFTER_QUERY = -2;

    /**
     * Default maximum page size value.
     *
     * @since 6.0, default value is 1000.
     */
    public static final long DEFAULT_MAX_PAGE_SIZE = 1000;

    /**
     * Page limit unknown.
     *
     * @since 5.8
     */
    public static final long PAGE_LIMIT_UNKNOWN = -1;

    /**
     * Returns the provider identifier
     */
    String getName();

    /**
     * Sets the provider identifier
     */
    void setName(String name);

    /**
     * Gets properties set on the provider.
     * <p>
     * Useful to retrieve a provider specific field attributes after instantiation. Other contextual parameters can be
     * passed through API constructing the result provider.
     */
    Map<String, Serializable> getProperties();

    /**
     * Sets properties set on the provider.
     * <p>
     * Useful to initialize a provider specific field attributes after instantiation. Other contextual parameters can be
     * passed through API constructing the result provider.
     */
    void setProperties(Map<String, Serializable> properties);

    Object[] getParameters();

    void setParameters(Object[] parameters);

    /**
     * Returns the number of results per page. 0 means no pagination unless {@link #getMaxPageSize()} is greater than
     * this value, it will be taken into account instead.
     */
    long getPageSize();

    /**
     * Sets the number of results per page. 0 means no pagination unless {@link #getMaxPageSize()} is greater than this
     * value, it will be taken into account instead.
     */
    void setPageSize(long pageSize);

    /**
     * Returns the max number of results per page. 0 means no pagination.
     * <p>
     * If page size is greater than this maximum value, it will be taken into account instead.
     *
     * @since 5.4.2
     */
    long getMaxPageSize();

    /**
     * Sets the max number of results per page. 0 means no pagination.
     * <p>
     * If page size is greater than this maximum value, it will be taken into account instead.
     *
     * @since 5.4.2
     */
    void setMaxPageSize(long pageSize);

    /**
     * Returns a list of available page size options to display in the page size selector.
     * <p>
     * Uses an hardcoded list of values, and adds up the page provider initial and current page sizes.
     *
     * @since 7.3
     */
    List<Long> getPageSizeOptions();

    /**
     * Sets the page size options.
     *
     * @since 7.3
     */
    void setPageSizeOptions(List<Long> options);

    /**
     * Returns the number of result elements if available or a negative value if it is unknown:
     * <code>UNKNOWN_SIZE</code> if it is unknown as query was not done, and since 5.5,
     * <code>UNKNOWN_SIZE_AFTER_QUERY</code> if it is still unknown after query was done.
     */
    long getResultsCount();

    /**
     * Sets the results count.
     *
     * @since 5.5
     */
    void setResultsCount(long resultsCount);

    /**
     * Returns the total number of pages or 0 if number of pages is unknown.
     */
    long getNumberOfPages();

    /**
     * Returns the page limit. The n first page we know they exist.
     *
     * @since 5.7.3
     */
    long getPageLimit();

    /**
     * Returns the current page of results.
     * <p>
     * This method is designed to be called from higher levels. It therefore ensures cheapness of repeated calls, rather
     * than data consistency. There is a refresh() method for that.
     * <p>
     *
     * @return the current page
     */
    List<T> getCurrentPage();

    /**
     * Returns the current page of results wrapped in a {@link PageSelection} item.
     * <p>
     * By default, no entry is selected, unless {@link #setSelectedEntries(List)} has been called before.
     */
    PageSelections<T> getCurrentSelectPage();

    /**
     * Sets the list of selected entries to take into account in {@link #getCurrentSelectPage()}.
     */
    void setSelectedEntries(List<T> entries);

    /**
     * Sets the current page offset.
     * <p>
     * If the provider keeps information linked to the current page, they should be reset after calling this method.
     *
     * @since 5.5
     */
    public void setCurrentPageOffset(long offset);

    /**
     * Sets the current page of results to the required one.
     *
     * @param currentPageIndex the page index, starting from 0
     * @since 5.7.3
     */
    void setCurrentPageIndex(long currentPageIndex);

    /**
     * Sets the current page of results to the required one and return it.
     *
     * @param page the page index, starting from 0
     */
    List<T> setCurrentPage(long page);

    /**
     * Forces refresh of the current page.
     */
    void refresh();

    /**
     * Returns a boolean expressing if there are further pages.
     */
    boolean isNextPageAvailable();

    /**
     * Returns a boolean expressing if the last page can be displayed.
     *
     * @since 5.5
     */
    boolean isLastPageAvailable();

    /**
     * Returns a boolean expressing if there is a previous page.
     */
    boolean isPreviousPageAvailable();

    /**
     * Returns the number of elements in current page.
     */
    long getCurrentPageSize();

    /**
     * Returns the offset (starting from 0) of the first element in the current page or <code>UNKNOWN_SIZE</code>.
     */
    long getCurrentPageOffset();

    /**
     * Returns the current page index as a zero-based integer.
     */
    long getCurrentPageIndex();

    /**
     * Returns a simple formatted string for current pagination status.
     */
    String getCurrentPageStatus();

    /**
     * Go to the first page
     */
    void firstPage();

    /**
     * Go to the previous page
     */
    void previousPage();

    /**
     * Go to the next page
     */
    void nextPage();

    /**
     * Go to the last page. Does not do anything if there is only one page displayed, or if the number of results is
     * unknown.
     */
    void lastPage();

    /**
     * Returns the current entry.
     */
    T getCurrentEntry();

    /**
     * Sets the current entry.
     */
    void setCurrentEntry(T entry);

    /**
     * Sets the current entry index.
     */
    void setCurrentEntryIndex(long index);

    /**
     * Returns true if there is a next entry.
     * <p>
     * The next entry might be in next page, except if results count is unknown.
     */
    boolean isNextEntryAvailable();

    /**
     * Returns true if there is a previous entry.
     * <p>
     * The previous entry might be in previous page.
     */
    boolean isPreviousEntryAvailable();

    /**
     * Move the current entry to the previous one, if applicable.
     * <p>
     * No exception: this method is intended to be plugged directly at the UI layer. In case there's no previous entry,
     * nothing will happen.
     */
    void previousEntry();

    /**
     * Move the current entry to the next one, if applicable.
     * <p>
     * If needed and possible, the provider will forward to next page. No special exceptions: this method is intended to
     * be plugged directly at the UI layer. In case there's no next entry, nothing happens.
     */
    void nextEntry();

    /**
     * Returns if this provider is sortable
     */
    boolean isSortable();

    void setSortable(boolean sortable);

    /**
     * Returns the complete list of sorting info for this provider
     */
    List<SortInfo> getSortInfos();

    /**
     * Returns the first sorting info for this provider
     * <p>
     * Also kept for compatibility with existing code.
     */
    SortInfo getSortInfo();

    /**
     * Sets the complete list of sorting info for this provider
     */
    void setSortInfos(List<SortInfo> sortInfo);

    /**
     * Sets the first and only sorting info for this provider.
     * <p>
     * Also kept for compatibility with existing code.
     */
    void setSortInfo(SortInfo sortInfo);

    /**
     * Sets the first and only sorting info for this provider if parameter removeOtherSortInfos is true. Otherwise, adds
     * or changes the sortAscending information according to given direction.
     */
    void setSortInfo(String sortColumn, boolean sortAscending, boolean removeOtherSortInfos);

    /**
     * Add the given sort info to the list of sorting infos.
     */
    void addSortInfo(String sortColumn, boolean sortAscending);

    /**
     * Returns a positive 0-based integer if given sort information is found on the set sort infos, indicating the sort
     * index, or -1 if this sort information is not found.
     */
    int getSortInfoIndex(String sortColumn, boolean sortAscending);

    DocumentModel getSearchDocumentModel();

    void setSearchDocumentModel(DocumentModel doc);

    boolean hasError();

    String getErrorMessage();

    Throwable getError();

    void setDefinition(PageProviderDefinition providerDefinition);

    PageProviderDefinition getDefinition();

    /**
     * Sets the {@link PageProviderChangedListener} for this {@code PageProvider}.
     *
     * @since 5.7
     */
    void setPageProviderChangedListener(PageProviderChangedListener listener);

    /**
     * Test if provider parameters have changed
     *
     * @since 5.7
     */
    boolean hasChangedParameters(Object[] parameters);

    /**
     * @since 6.0
     */
    List<AggregateDefinition> getAggregateDefinitions();

    /**
     * @since 6.0
     */
    Map<String, Aggregate<? extends Bucket>> getAggregates();

    /**
     * @since 6.0
     */
    boolean hasAggregateSupport();

    /**
     * @since 8.4
     */
    List<QuickFilter> getQuickFilters();

    /**
     * @since 8.4
     */
    void setQuickFilters(List<QuickFilter> quickFilters);

    /**
     * @since 8.4
     */
    void addQuickFilter(QuickFilter quickFilter);

    /**
     * @since 8.4
     */
    List<QuickFilter> getAvailableQuickFilters();

}