001/*
002 * (C) Copyright 2013 Nuxeo SA (http://nuxeo.com/) and contributors.
003 *
004 * All rights reserved. This program and the accompanying materials
005 * are made available under the terms of the GNU Lesser General Public License
006 * (LGPL) version 2.1 which accompanies this distribution, and is available at
007 * http://www.gnu.org/licenses/lgpl-2.1.html
008 *
009 * This library is distributed in the hope that it will be useful,
010 * but WITHOUT ANY WARRANTY; without even the implied warranty of
011 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
012 * Lesser General Public License for more details.
013 *
014 * Contributors:
015 *     Thomas Roger
016 */
017package org.nuxeo.ecm.platform.query.api;
018
019import java.io.Serializable;
020import java.util.List;
021import java.util.Map;
022
023import org.nuxeo.ecm.core.api.DocumentModel;
024import org.nuxeo.ecm.core.api.SortInfo;
025
026/**
027 * Basic interface for a page provider, independent of type of items in the list
028 * <p>
029 * Provides APIs to navigate between result pages
030 *
031 * @param <T> any Serializable item
032 * @since 5.4
033 * @author arussel
034 * @author Anahide Tchertchian
035 */
036public interface PageProvider<T> extends Serializable {
037
038    public static final String DEFAULT_MAX_PAGE_SIZE_RUNTIME_PROP = "nuxeo.pageprovider.default-max-page-size";
039
040    /**
041     * Constant to express that the total number of result elements is unknown (usually because the query has not been
042     * done yet).
043     */
044    public static final long UNKNOWN_SIZE = -1;
045
046    /**
047     * Constant to express that the total number of result elements is unknown even after performing a query.
048     *
049     * @since 5.5
050     */
051    public static final long UNKNOWN_SIZE_AFTER_QUERY = -2;
052
053    /**
054     * Default maximum page size value.
055     *
056     * @since 6.0, default value is 1000.
057     */
058    public static final long DEFAULT_MAX_PAGE_SIZE = 1000;
059
060    /**
061     * Page limit unknown.
062     *
063     * @since 5.8
064     */
065    public static final long PAGE_LIMIT_UNKNOWN = -1;
066
067    /**
068     * Returns the provider identifier
069     */
070    String getName();
071
072    /**
073     * Sets the provider identifier
074     */
075    void setName(String name);
076
077    /**
078     * Gets properties set on the provider.
079     * <p>
080     * Useful to retrieve a provider specific field attributes after instantiation. Other contextual parameters can be
081     * passed through API constructing the result provider.
082     */
083    Map<String, Serializable> getProperties();
084
085    /**
086     * Sets properties set on the provider.
087     * <p>
088     * Useful to initialize a provider specific field attributes after instantiation. Other contextual parameters can be
089     * passed through API constructing the result provider.
090     */
091    void setProperties(Map<String, Serializable> properties);
092
093    Object[] getParameters();
094
095    void setParameters(Object[] parameters);
096
097    /**
098     * Returns the number of results per page. 0 means no pagination unless {@link #getMaxPageSize()} is greater than
099     * this value, it will be taken into account instead.
100     */
101    long getPageSize();
102
103    /**
104     * Sets the number of results per page. 0 means no pagination unless {@link #getMaxPageSize()} is greater than this
105     * value, it will be taken into account instead.
106     */
107    void setPageSize(long pageSize);
108
109    /**
110     * Returns the max number of results per page. 0 means no pagination.
111     * <p>
112     * If page size is greater than this maximum value, it will be taken into account instead.
113     *
114     * @since 5.4.2
115     */
116    long getMaxPageSize();
117
118    /**
119     * Sets the max number of results per page. 0 means no pagination.
120     * <p>
121     * If page size is greater than this maximum value, it will be taken into account instead.
122     *
123     * @since 5.4.2
124     */
125    void setMaxPageSize(long pageSize);
126
127    /**
128     * Returns a list of available page size options to display in the page size selector.
129     * <p>
130     * Uses an hardcoded list of values, and adds up the page provider initial and current page sizes.
131     *
132     * @since 7.3
133     */
134    List<Long> getPageSizeOptions();
135
136    /**
137     * Sets the page size options.
138     *
139     * @since 7.3
140     */
141    void setPageSizeOptions(List<Long> options);
142
143    /**
144     * Returns the number of result elements if available or a negative value if it is unknown:
145     * <code>UNKNOWN_SIZE</code> if it is unknown as query was not done, and since 5.5,
146     * <code>UNKNOWN_SIZE_AFTER_QUERY</code> if it is still unknown after query was done.
147     */
148    long getResultsCount();
149
150    /**
151     * Sets the results count.
152     *
153     * @since 5.5
154     */
155    void setResultsCount(long resultsCount);
156
157    /**
158     * Returns the total number of pages or 0 if number of pages is unknown.
159     */
160    long getNumberOfPages();
161
162    /**
163     * Returns the page limit. The n first page we know they exist.
164     *
165     * @since 5.7.3
166     */
167    long getPageLimit();
168
169    /**
170     * Returns the current page of results.
171     * <p>
172     * This method is designed to be called from higher levels. It therefore ensures cheapness of repeated calls, rather
173     * than data consistency. There is a refresh() method for that.
174     * <p>
175     *
176     * @return the current page
177     */
178    List<T> getCurrentPage();
179
180    /**
181     * Returns the current page of results wrapped in a {@link PageSelection} item.
182     * <p>
183     * By default, no entry is selected, unless {@link #setSelectedEntries(List)} has been called before.
184     */
185    PageSelections<T> getCurrentSelectPage();
186
187    /**
188     * Sets the list of selected entries to take into account in {@link #getCurrentSelectPage()}.
189     */
190    void setSelectedEntries(List<T> entries);
191
192    /**
193     * Sets the current page offset.
194     * <p>
195     * If the provider keeps information linked to the current page, they should be reset after calling this method.
196     *
197     * @since 5.5
198     */
199    public void setCurrentPageOffset(long offset);
200
201    /**
202     * Sets the current page of results to the required one.
203     *
204     * @param currentPageIndex the page index, starting from 0
205     * @since 5.7.3
206     */
207    void setCurrentPageIndex(long currentPageIndex);
208
209    /**
210     * Sets the current page of results to the required one and return it.
211     *
212     * @param page the page index, starting from 0
213     */
214    List<T> setCurrentPage(long page);
215
216    /**
217     * Forces refresh of the current page.
218     */
219    void refresh();
220
221    /**
222     * Returns a boolean expressing if there are further pages.
223     */
224    boolean isNextPageAvailable();
225
226    /**
227     * Returns a boolean expressing if the last page can be displayed.
228     *
229     * @since 5.5
230     */
231    boolean isLastPageAvailable();
232
233    /**
234     * Returns a boolean expressing if there is a previous page.
235     */
236    boolean isPreviousPageAvailable();
237
238    /**
239     * Returns the number of elements in current page.
240     */
241    long getCurrentPageSize();
242
243    /**
244     * Returns the offset (starting from 0) of the first element in the current page or <code>UNKNOWN_SIZE</code>.
245     */
246    long getCurrentPageOffset();
247
248    /**
249     * Returns the current page index as a zero-based integer.
250     */
251    long getCurrentPageIndex();
252
253    /**
254     * Returns a simple formatted string for current pagination status.
255     */
256    String getCurrentPageStatus();
257
258    /**
259     * Go to the first page
260     */
261    void firstPage();
262
263    /**
264     * Go to the previous page
265     */
266    void previousPage();
267
268    /**
269     * Go to the next page
270     */
271    void nextPage();
272
273    /**
274     * Go to the last page. Does not do anything if there is only one page displayed, or if the number of results is
275     * unknown.
276     */
277    void lastPage();
278
279    /**
280     * Returns the current entry.
281     */
282    T getCurrentEntry();
283
284    /**
285     * Sets the current entry.
286     */
287    void setCurrentEntry(T entry);
288
289    /**
290     * Sets the current entry index.
291     */
292    void setCurrentEntryIndex(long index);
293
294    /**
295     * Returns true if there is a next entry.
296     * <p>
297     * The next entry might be in next page, except if results count is unknown.
298     */
299    boolean isNextEntryAvailable();
300
301    /**
302     * Returns true if there is a previous entry.
303     * <p>
304     * The previous entry might be in previous page.
305     */
306    boolean isPreviousEntryAvailable();
307
308    /**
309     * Move the current entry to the previous one, if applicable.
310     * <p>
311     * No exception: this method is intended to be plugged directly at the UI layer. In case there's no previous entry,
312     * nothing will happen.
313     */
314    void previousEntry();
315
316    /**
317     * Move the current entry to the next one, if applicable.
318     * <p>
319     * If needed and possible, the provider will forward to next page. No special exceptions: this method is intended to
320     * be plugged directly at the UI layer. In case there's no next entry, nothing happens.
321     */
322    void nextEntry();
323
324    /**
325     * Returns if this provider is sortable
326     */
327    boolean isSortable();
328
329    void setSortable(boolean sortable);
330
331    /**
332     * Returns the complete list of sorting info for this provider
333     */
334    List<SortInfo> getSortInfos();
335
336    /**
337     * Returns the first sorting info for this provider
338     * <p>
339     * Also kept for compatibility with existing code.
340     */
341    SortInfo getSortInfo();
342
343    /**
344     * Sets the complete list of sorting info for this provider
345     */
346    void setSortInfos(List<SortInfo> sortInfo);
347
348    /**
349     * Sets the first and only sorting info for this provider.
350     * <p>
351     * Also kept for compatibility with existing code.
352     */
353    void setSortInfo(SortInfo sortInfo);
354
355    /**
356     * Sets the first and only sorting info for this provider if parameter removeOtherSortInfos is true. Otherwise, adds
357     * or changes the sortAscending information according to given direction.
358     */
359    void setSortInfo(String sortColumn, boolean sortAscending, boolean removeOtherSortInfos);
360
361    /**
362     * Add the given sort info to the list of sorting infos.
363     */
364    void addSortInfo(String sortColumn, boolean sortAscending);
365
366    /**
367     * Returns a positive 0-based integer if given sort information is found on the set sort infos, indicating the sort
368     * index, or -1 if this sort information is not found.
369     */
370    int getSortInfoIndex(String sortColumn, boolean sortAscending);
371
372    DocumentModel getSearchDocumentModel();
373
374    void setSearchDocumentModel(DocumentModel doc);
375
376    boolean hasError();
377
378    String getErrorMessage();
379
380    Throwable getError();
381
382    void setDefinition(PageProviderDefinition providerDefinition);
383
384    PageProviderDefinition getDefinition();
385
386    /**
387     * Sets the {@link PageProviderChangedListener} for this {@code PageProvider}.
388     *
389     * @since 5.7
390     */
391    void setPageProviderChangedListener(PageProviderChangedListener listener);
392
393    /**
394     * Test if provider parameters have changed
395     *
396     * @since 5.7
397     */
398    boolean hasChangedParameters(Object[] parameters);
399
400    /**
401     * @since 6.0
402     */
403    List<AggregateDefinition> getAggregateDefinitions();
404
405    /**
406     * @since 6.0
407     */
408    Map<String, Aggregate<? extends Bucket>> getAggregates();
409
410    /**
411     * @since 6.0
412     */
413    boolean hasAggregateSupport();
414
415}