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}