/*
* (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();
/**
* @since 9.1
*/
List<String> getHighlights();
/**
* @since 9.1
*/
void setHighlights(List<String> highlights);
}