Package com.cmobilecom.af.model.pagination

Class PageableEntityList<T extends PersistenceEntity>

  • Type Parameters:
    T - PersistenceEntity
    All Implemented Interfaces:
    java.io.Serializable
    Direct Known Subclasses:
    MemoryEntityList, QueryCriteriaEntityList
    public abstract class PageableEntityList<T extends PersistenceEntity>
extends java.lang.Object
implements java.io.Serializable
    PageableEntityList: pageable entity list. A page is a window to a possibly very large result set.
    Since:
    1.0
    See Also:
    Serialized Form

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected int currentPageIndex
      Current page index starting from zero
      protected java.lang.Integer currentPageLeadingStatisticsEntityCount
      If variable pageSize is supported, the number of leading statistics entities in current page.
      protected java.lang.Integer currentPageOffset
      If variable pageSize is supported, current page entity start index within the whole entity list, excluding embedded statistics entities.
      protected java.lang.Integer currentPageSize
      If variable pageSize is supported, the number of entities in current page, excluding embedded statistics entities.
      protected boolean entitiesAddedOrDeleted
      Has any entity been added or deleted to this pageable entity list? If true, applyChange command will be rendered for saving changes.
      protected EntityListBackingBean<T> entityListBackingBean
      The EntityListBackingBean to manage this pageable entity list
      protected boolean fillBlankRowsIfAdjustForward
      If variable pageSize is supported, whether to fill rows from next page if there is not enough entities for the current page.
      static int LAST_PAGE
      Last page
      protected java.util.List<T> nextPageStartEntities
      If variable pageSize is supported, The list of entities that will be shown at the beginning of the next page
      protected java.lang.Integer pageCount
      Total number of pages, null for unknown
      protected PageListener pageListener
      A pageListener that is called when page data is loaded or page size is adjusted
      protected java.lang.Integer pageSize
      Page size, rows per page.
      protected java.lang.Integer size
      Total number of rows (entities), null for unknown
      protected T statisticsEntity
      The statistics values of the whole entity list
      protected java.util.Map<java.lang.String,​java.lang.Object> statisticsMismatchedValueMap
      Property statistics values that does not match property types.
      protected boolean supportVariablePageSize
      Whether variable pageSize is supported? If supported, statistics entities can be embedded to current page and keep the same rows on all pages for rendering on device.

    • Field Detail

      • currentPageIndex

        protected int currentPageIndex
        Current page index starting from zero

      • pageSize

        protected java.lang.Integer pageSize
        Page size, rows per page. If null: infinite, so total one page

      • pageCount

        protected java.lang.Integer pageCount
        Total number of pages, null for unknown

      • size

        protected java.lang.Integer size
        Total number of rows (entities), null for unknown

      • supportVariablePageSize

        protected boolean supportVariablePageSize
        Whether variable pageSize is supported? If supported, statistics entities can be embedded to current page and keep the same rows on all pages for rendering on device.

      • currentPageLeadingStatisticsEntityCount

        protected java.lang.Integer currentPageLeadingStatisticsEntityCount
        If variable pageSize is supported, the number of leading statistics entities in current page.

      • currentPageOffset

        protected java.lang.Integer currentPageOffset
        If variable pageSize is supported, current page entity start index within the whole entity list, excluding embedded statistics entities.

      • currentPageSize

        protected java.lang.Integer currentPageSize
        If variable pageSize is supported, the number of entities in current page, excluding embedded statistics entities.

      • nextPageStartEntities

        protected java.util.List<T extends PersistenceEntity> nextPageStartEntities
        If variable pageSize is supported, The list of entities that will be shown at the beginning of the next page

      • fillBlankRowsIfAdjustForward

        protected boolean fillBlankRowsIfAdjustForward
        If variable pageSize is supported, whether to fill rows from next page if there is not enough entities for the current page. default is true.

      • pageListener

        protected PageListener pageListener
        A pageListener that is called when page data is loaded or page size is adjusted

      • statisticsEntity

        protected T extends PersistenceEntity statisticsEntity
        The statistics values of the whole entity list

      • statisticsMismatchedValueMap

        protected java.util.Map<java.lang.String,​java.lang.Object> statisticsMismatchedValueMap
        Property statistics values that does not match property types. A map from propertyName to statistics value.

      • entitiesAddedOrDeleted

        protected boolean entitiesAddedOrDeleted
        Has any entity been added or deleted to this pageable entity list? If true, applyChange command will be rendered for saving changes.

    • Constructor Detail

      • PageableEntityList

        protected PageableEntityList()
        Default constructor. not initialized.

      • PageableEntityList

        public PageableEntityList​(PageableEntityList<T> pageableEntityList)
        Copy constructor
        Parameters:
        pageableEntityList - the PageableEntityList to copy from

    • Method Detail

      • getPageEntityList

        public abstract java.util.List<T> getPageEntityList()
        Get current page entity list
        Returns:
        a list of entities in the current page.

      • getCurrentPageIndex

        public int getCurrentPageIndex()
        Get current page index
        Returns:
        page index starting from 0.

      • setCurrentPageIndex

        protected abstract void setCurrentPageIndex​(int pageIndex,
                                            java.lang.Integer pageOffset,
                                            java.lang.Integer maxResults,
                                            PageableEntityList.PaginationChangeReason reason)
                                     throws SystemException
        Set current page index.
        Parameters:
        pageIndex - the new page index
        pageOffset - the first entity index to fetch for the page. if null, default to pageSize * pageIndex.
        maxResults - the max number of entities for the page. if null, default to pageSize.
        reason - the reason for pagination
        Throws:
        SystemException - throw if an error occurs in pagination

      • paginationChanged

        public void paginationChanged​(java.lang.Integer pageCount,
                              int currentPageIndex,
                              PageableEntityList.PaginationChangeReason reason)
                       throws SystemException
        Pagination Listener: called when pageCount or currentPageIndex is changed or pageCount is recalculated because of entities added or deleted.

        This method will delegate to EntityBackingBean.paginationChanged(...) that can be overridden.

        Parameters:
        pageCount - page count
        currentPageIndex - current page index
        reason - the reason of pagination
        Throws:
        SystemException - throw if an error occurs

      • getPageSize

        public java.lang.Integer getPageSize()
        Get page size(number of entities)
        Returns:
        page size

      • setPageSize

        public void setPageSize​(java.lang.Integer pageSize,
                        java.lang.Integer pageIndex,
                        PageableEntityList.PaginationChangeReason reason)
                 throws SystemException
        Set page size and page index.
        Parameters:
        pageSize - new page size
        pageIndex - new page index. if null, keep the current page index
        reason - the reason for the change of page size
        Throws:
        SystemException - throw if an error occurs

      • getPageCount

        public java.lang.Integer getPageCount()
        Get the total number of pages.
        Returns:
        page count. return null if unknown.

      • getCurrentPageFirstEntityIndex

        public int getCurrentPageFirstEntityIndex()
        Get the first entity index excluding embedded statistics entities
        Returns:
        the entity index within the whole entity list

      • getCurrentPageEntityCount

        public abstract int getCurrentPageEntityCount()
        Get the number of entities in the current page excluding embedded statistics entities.
        Returns:
        entity count

      • getCurrentPageLastEntityIndex

        public int getCurrentPageLastEntityIndex()
        Get the last entity index in the current page excluding embedded statistics entities
        Returns:
        the entity index within the whole entity list

      • isInCurrentPage

        public boolean isInCurrentPage​(int entityIndex)
        Is the entity index in the current page?
        Parameters:
        entityIndex - entity index within the whole entity list
        Returns:
        true if the entity index is in the current page

      • getEntityIndex

        public int getEntityIndex​(int entityIndexWithinCurrentPage)
        Convert the entity index within current page to the entity index within the whole entity list
        Parameters:
        entityIndexWithinCurrentPage - entity index within the current page(starting from 0)
        Returns:
        the entity index within the whole entity list

      • getIndexWithinCurrentPage

        protected int getIndexWithinCurrentPage​(int entityIndexWithinWholeList)
        Convert the entity index within whole list to the index within current page.
        Parameters:
        entityIndexWithinWholeList - entity index within whole list
        Returns:
        entity index within current page

      • getPageIndex

        public int getPageIndex​(int entityIndexWithinWholeList)
        Get pageIndex for entity index
        Parameters:
        entityIndexWithinWholeList - entity index within whole list
        Returns:
        page index

      • isHasPreviousPage

        public boolean isHasPreviousPage()
        Does this pageable entity list has a previous page? If current page index is 0, return false.
        Returns:
        true if this pageable entity list has a previous page.

      • isHasNextPage

        public boolean isHasNextPage()
        Does this pageable entity list has a next page?
        Returns:
        true if this pageable entity list has a next page.

      • isFirstPage

        public boolean isFirstPage()
        Is current page the first page of this pageable entity list?
        Returns:
        true if current page is the first page

      • firstPage

        public void firstPage()
               throws SystemException
        Set current page to the first page, and fetch entities from persistence.
        Throws:
        SystemException - throw if an error occurs in pagination

      • lastPage

        public void lastPage()
              throws SystemException
        Set current page to the last page, and fetch entities from persistence.
        Throws:
        SystemException - throw if an error occurs in pagination

      • nextPage

        public void nextPage​(boolean circle,
                     boolean fullPageRequired)
              throws SystemException
        Set current page to the next page, and fetch entities from persistence.
        Parameters:
        circle - if true, go back to the first page after the last page
        fullPageRequired - if true, go to the next page only if it is a full size page
        Throws:
        SystemException - throw if an error occurs in pagination

      • isAnyEntityChanged

        public boolean isAnyEntityChanged​(boolean notPersistedAsChanged,
                                  boolean allPages)
        Is any entity changed? PersistenceEntity.isChanged() return true if changed.
        Parameters:
        notPersistedAsChanged - whether not-persisted entities are regarded as changed.
        allPages - current page or all pages. Valid for MemoryEntityList only.
        Returns:
        true if any entity is changed, false otherwise
        Since:
        5.8

      • getEntityList

        public java.util.List<T> getEntityList​(boolean allPages)
        Get all the entities of the current page or all pages. For QueryCriteriaEntityList, return the entities in current page.
        Parameters:
        allPages - true for all pages, false for current page
        Returns:
        entity list
        Since:
        5.8

      • previousPage

        public void previousPage()
                  throws SystemException
        Set current page to the previous page, and fetch entities from persistence.
        Throws:
        SystemException - throw if an error occurs in pagination

      • isLastPage

        public boolean isLastPage()
        Whether current page is the last page
        Returns:
        true for last page

      • getEntity

        public abstract T getEntity​(int index)
                     throws SystemException
        Get the entity at the specified position. Load page first if the entity is not in the current page. This method will change current page index.
        Parameters:
        index - entity index in the whole entity list
        Returns:
        the entity at the index
        Throws:
        SystemException - throw if an error occurs

      • getEntityOfCurrentPage

        public T getEntityOfCurrentPage​(int indexOfCurrentPage)
                         throws SystemException
        Get the entity at the specified position of current page
        Parameters:
        indexOfCurrentPage - index within current page starting from zero.
        Returns:
        entity at the index
        Throws:
        SystemException - throw if an error occurs

      • peekEntity

        public abstract T peekEntity​(int index)
                      throws SystemException
        Peek the entity at the specified position without changing current page index.
        Parameters:
        index - entity index in the whole entity list
        Returns:
        the entity at the index
        Throws:
        SystemException - throw if an error occurs

      • getSize

        public java.lang.Integer getSize()
        Get total number of entities in the whole entity list.
        Returns:
        total entity count

      • fastForwardPages

        public void fastForwardPages​(int pages)
                      throws SystemException
        Go forward the number of pages
        Parameters:
        pages - the number of page to go forward
        Throws:
        SystemException - throw if an error occurs in pagination

      • fastRewindPages

        public void fastRewindPages​(int pages)
                     throws SystemException
        Go back the number of pages
        Parameters:
        pages - the number of pages to go back
        Throws:
        SystemException - throw if an error occurs in pagination

      • jumpToPage

        public void jumpToPage​(int pageIndex)
                throws SystemException
        Jump to the page and load the page as the current page.
        Parameters:
        pageIndex - the index of the page to go
        Throws:
        SystemException - throw if an error occurs in pagination

      • addEntity

        public abstract void addEntity​(T entity)
                        throws SystemException
        Add the entity to the end of current page.
        Parameters:
        entity - the entity to add
        Throws:
        SystemException - throw if an error occurs

      • addAll

        public abstract void addAll​(java.lang.Integer position,
                            java.util.List<T> entityList)
                     throws SystemException
        Insert the entity list at the position.
        Parameters:
        position - the position within current page. If null, append the entities to the end of current page.
        entityList - the list of entities to add
        Throws:
        SystemException - throw if an error occurs

      • removeSelectedEntitiesFromMemory

        public abstract java.util.List<T> removeSelectedEntitiesFromMemory()
                                                            throws SystemException
        Remove the selected entities from current page in memory. Assume that the entities have been deleted from persistence.
        Returns:
        the list of entities removed
        Throws:
        SystemException - throw if an error occurs

      • removeEntitiesFromMemory

        public abstract void removeEntitiesFromMemory​(java.util.List<T> entitiesToRemove)
                                       throws SystemException
        Remove the entities from entity list in memory.

        For memoryEntityList, the entities to be removed can be in different pages. Recalculate page count and statistics.

        For QueryCriteriaEntityList, the entities to be removed are in current page. If there is not changes after the entities are removed, refresh current page, recalculate page count and statistics.

        Parameters:
        entitiesToRemove - the entities to remove
        Throws:
        SystemException - throw if an error occurs in calculating page count and statistics.

      • removeEntity

        public abstract T removeEntity​(int index)
                        throws SystemException
        Remove the entity at the index in memory without updating persistence. Assume that the entity has been removed from persistence
        Parameters:
        index - the entity index in the whole list
        Returns:
        the removed entity if exist, null otherwise
        Throws:
        SystemException - throw if an error occurs

      • removeEntityOfCurrentPage

        public T removeEntityOfCurrentPage​(int entityIndex)
                            throws SystemException
        Remove the entity at the index in memory without updating persistence. Assume that the entity has been removed from persistence
        Parameters:
        entityIndex - the entity index in the current page
        Returns:
        the removed entity if exist, null otherwise
        Throws:
        SystemException - throw if an error occurs

      • removeEntity

        public abstract void removeEntity​(T entity)
                           throws SystemException
        Remove the entity from current page in memory without updating persistence.
        Parameters:
        entity - the entity to be removed
        Throws:
        SystemException - throw if an error occurs

      • setEntity

        public abstract void setEntity​(int index,
                               T entity)
                        throws SystemException
        Set the entity at the index in memory without updating persistence. If the entity is not in the current page, change current page to the page that contains the entity.
        Parameters:
        index - the entity index in the whole list
        entity - the new entity to set
        Throws:
        SystemException - throw if an error occurs

      • setEntityOfCurrentPage

        public abstract void setEntityOfCurrentPage​(int entityIndex,
                                            T entity)
                                     throws SystemException
        Set the entity at the index in memory without updating persistence
        Parameters:
        entityIndex - the entity index within current page starting from 0
        entity - the entity to set
        Throws:
        SystemException - throw if an error occurs

      • getTitle

        public abstract ParameterizedMessage getTitle()
        Get the title of this PageableEntityList as the title of its EntityListBackingBean.
        Returns:
        ParameterizedMessage instance

      • getDataDescriptor

        public abstract DataDescriptor getDataDescriptor()
        Get the DataDescriptor of this pageable entity list.
        Returns:
        DataDescriptor instance

      • reload

        public abstract void reload()
                     throws SystemException
        Reload the entities from persistence. The entities in memory may become stale and not usable possibly due to the transaction exception.
        Throws:
        SystemException - throw if an error occurs in reloading entities

      • clear

        public abstract void clear()
                    throws SystemException
        Clear the whole entity list in memory.
        Throws:
        SystemException - throw if an error occurs in updating page count and statistics

      • refresh

        public abstract void refresh​(java.lang.Integer pageIndex,
                             PageableEntityList.PaginationChangeReason reason)
                      throws SystemException
        Refresh the page by reloading from persistence. Called when underlying database or query criteria is changed, which may have affected search results.
        Parameters:
        pageIndex - the index of the page to refresh. if null, default to the current page index.
        reason - PaginationChangeReason
        Throws:
        SystemException - throw if an error occurs in reloading entities

      • getStatisticsEntity

        public T getStatisticsEntity()
        Get the statistics entity for all the entities. A statistics entity contains the values for property group functions such as sum and average.
        Returns:
        statistics entity

      • setStatisticsEntity

        public void setStatisticsEntity​(T statisticsEntity)
        Set the statistics entity for all the entities. A statistics entity contains the values for property group functions such as sum and average.
        Parameters:
        statisticsEntity - statistics entity

      • getStatisticsMismatchedValue

        public java.lang.Object getStatisticsMismatchedValue​(java.lang.String propertyName)
        Get the statistics value of the property. The value type does not match the property type, and thus it can not be set to the statistics entity. For example, property type is Integer, the result of group function avg(average) can be a double value.
        Parameters:
        propertyName - property name
        Returns:
        statistics value

      • getResultsLimit

        public java.lang.Integer getResultsLimit()
        Get the maximum number of search results.
        Returns:
        max search results. return null if unlimited.

      • getResultsLimitReason

        public PageableEntityList.ResultsLimitReason getResultsLimitReason()
        Get the reason why search results is limited.
        Returns:
        ResultsLimitReason. return null if unlimited

      • getPageListener

        public PageListener getPageListener()
        Get the PageListener that will be called when page data is loaded from persistence or page size is adjusted.
        Returns:
        PageListener instance.

      • setPageListener

        public void setPageListener​(PageListener pageListener)
        Get the PageListener that will be called when page data is loaded from persistence or page size is adjusted.
        Parameters:
        pageListener - PageListener instance.

      • selectAllEntitiesOfCurrentPage

        public java.util.List<T> selectAllEntitiesOfCurrentPage​(boolean select)
        Select or deselect all the entities in the current page.
        Parameters:
        select - true to select, false to deselect.
        Returns:
        the entity list in the current page

      • getEntityIndexOfCurrentPage

        public int getEntityIndexOfCurrentPage​(java.lang.Long entityId)
        Get the index of the entity with the id in the current page.
        Parameters:
        entityId - entity id
        Returns:
        entity index in the current page, starting with 0. return -1 if not found.

      • getEntityOfCurrentPage

        public T getEntityOfCurrentPage​(java.lang.Long entityId)
        Get the entity with the id in the current page.
        Parameters:
        entityId - entity id
        Returns:
        the entity with the id. return null if not found.

      • getEntityListBackingBean

        public EntityListBackingBean<T> getEntityListBackingBean()
        Get the EntityListBackingBean to which this pageable entity list belongs.
        Returns:
        EntityListBackingBean instance

      • setEntityListBackingBean

        public void setEntityListBackingBean​(EntityListBackingBean<T> entityListBackingBean)
                              throws SystemException
        Set the EntityListBackingBean to which this pageable entity list belongs.
        Parameters:
        entityListBackingBean - an EntityListBackingBean instance
        Throws:
        SystemException - throw if an error occurs

      • getShownPageIndexList

        public java.util.List<java.lang.Integer> getShownPageIndexList()
        Get the list of page index to show on paginator
        Returns:
        page index list

      • isEmpty

        public boolean isEmpty()
        Is this pageable entity list empty?
        Returns:
        true if empty.

      • isSupportVariablePageSize

        public boolean isSupportVariablePageSize()
        Can page size(entities per page) be different from page to page?
        Returns:
        true if variable page size is supported.

      • setSupportVariablePageSize

        public void setSupportVariablePageSize​(boolean supportVariablePageSize)
        Set whether page size(entities per page) can be different from page to page?
        Parameters:
        supportVariablePageSize - true if variable page size is supported.

      • getCurrentPageSize

        public java.lang.Integer getCurrentPageSize()
        Get current page size for variable page size support.
        Returns:
        page size (the number of entities on the current page)

      • setCurrentPageSize

        public void setCurrentPageSize​(java.lang.Integer currentPageSize)
        Set current page size for variable page size support.
        Parameters:
        currentPageSize - the number of entities on the current page

      • getNextPageStartEntities

        public java.util.List<T> getNextPageStartEntities()
        Get the entities that will be shown on the next page for variable page size support.
        Returns:
        a list of entities

      • setNextPageStartEntities

        public void setNextPageStartEntities​(java.util.List<T> nextPageStartEntities)
        Set the entities that will be shown on the next page for variable page size support.
        Parameters:
        nextPageStartEntities - a list of entities

      • isFillBlankRowsIfAdjustForward

        public boolean isFillBlankRowsIfAdjustForward()
        For variable page size support, whether to fill rows from next page if there is not enough entities for the current page.
        Returns:
        true if filling blank rows. default is true.

      • setFillBlankRowsIfAdjustForward

        public void setFillBlankRowsIfAdjustForward​(boolean fillBlankRowsIfAdjustForward)
        For variable page size support, set whether to fill rows from next page if there is not enough entities for the current page.
        Parameters:
        fillBlankRowsIfAdjustForward - true if filling blank rows

      • updateStatisticsEntityPropertyValue

        public abstract void updateStatisticsEntityPropertyValue​(java.lang.String propertyName)
                                                  throws SystemException
        Calculate the statistics for the specified property
        Parameters:
        propertyName - the name of the property whose statistics will be recalculated
        Throws:
        SystemException - throw if an error occurs

      • calculateStatistics

        public abstract void calculateStatistics()
                                  throws SystemException
        Calculate the statistics for all the statistics properties
        Throws:
        SystemException - throw if an error occurs

      • isLastPageFull

        public java.lang.Boolean isLastPageFull()
        Is the last page a full page of entities?
        Returns:
        null if it can not be determined. In case of variablePageSize, it is unknown.

      • isEntitiesAddedOrDeleted

        public boolean isEntitiesAddedOrDeleted()
        Has any entity been added or deleted to this pageable entity list? if true, applyChange command will be rendered for saving changes.
        Returns:
        true if added or deleted

      • setEntitiesAddedOrDeleted

        public void setEntitiesAddedOrDeleted​(boolean entitiesAddedOrDeleted)
        Set whether any entity has been added or deleted to this pageable entity list. If true, applyChange command will be rendered for saving changes.
        Parameters:
        entitiesAddedOrDeleted - true if added or deleted