Package name.matthewgreet.strutscommons.util

Class ListCache<M extends Serializable,K extends Serializable,T extends Serializable>

java.lang.Object
name.matthewgreet.strutscommons.util.ListCache<M,K,T>
All Implemented Interfaces:
Serializable
public class ListCache<M extends Serializable,K extends Serializable,T extends Serializable> extends Object implements Serializable

Template, record list framework that uses finder Strategies to lazy load lists, pages of a list, and details of the currently selected record as needed, and typically combined with others in a framework like AbstractCompositeCache. Such Strategies are typically set by a Struts action using form based search criteria, or by a framework to retrieve child lists of a selected master record. Struts actions can examine the list, usually the currently selected record, select a new record as the current selection, update items, or invalidate items or the entire list, so changed items or lists are refound and displayed.

Record data is partitioned into list data and, optionally, detail data. List data is displayed in list-based pages, such as search result pages, and list and page finders know how to retrieve them. List data is typically just the base record from a single table to avoid performance problems with table joins. Detail data, if any, is displayed in pages displaying the currently selected record in detail, as well as list data, often for editing, and single item finders know how to retrieve it (as well as list data). List and page finders need not retrieve any detail data, and usually don't for performance reasons. However, if detail data applies and no single item finder exists, list and page finders must retrieve details.

The record list itself may not be fully loaded and may lazy load pages from placeholder data as requested, depending on pagination mode. The pagination mode is set by setting the placeholder and page finders needed for the mode. Currently, four pagination modes are supported.

Type Method Usage Requires Notes
Base record list Loads all base records from single table, loads additional records of requested page Large result list with additional list data from related tables baseRecordlistFinder, pageExtensionAssembler pageExtensionChecker can also be set to filter record that don't need page extensions
Full list Loads entire list at once Small result list and no back-end pagination support listFinder
Page by ids Loads primary keys of entire list, loads records from primary keys of requested page Large result list where ids are quicker to read and order doesn't matter idListFinder, pageByIdsFinder
Page by index range Loads record count of entire list, loads records from index range of requested page Large result list where an index allows order by without reading entire list first listSizeFinder, pageByIndexRangeFinder listSizeFinder and pageByIndexRangeFinder must work in tandem, use setListSizeFinder(name.matthewgreet.strutscommons.util.ListSizeFinder<M>, name.matthewgreet.strutscommons.util.PageByIndexRangeFinder<M, T>) or setListSizeAndFinder(int, name.matthewgreet.strutscommons.util.ListSizeFinder<M>, name.matthewgreet.strutscommons.util.PageByIndexRangeFinder<M, T>) to set both
List Finder Types

Some caches can be slave lists, meaning their contents depends on a master record given to it by another combining framework. Such frameworks will invalidate slave lists if another master record is selected or it's reloaded.

Parameters are

M
Record type of master list or Object if this is the master list.
K
Record primary key or id type.
T
Record type.
See Also:

  • Constructor Details

  • Method Details

    • markChanged

      protected void markChanged()

    • notifyChanged

      protected void notifyChanged()
      Notification of change. This typically notifies the parent container.

    • addListCacheListener

      public void addListCacheListener(ListCacheListener<T> listener)

    • addItem

      public void addItem(T item) throws IllegalStateException, Exception
      Adds new item to end of list and sets it as selected item.
      Parameters:
      item - New item to add to end of list.
      Throws:
      IllegalStateException - List must be reloaded but list finder is missing.
      Exception - Failed to retrieve extensions.

    • forceReload

      public void forceReload() throws Exception
      Reloads list using currently set list finder, id list finder, or list size finder.
      Throws:
      Exception

    • getBaseRecordListFinder

      public ListFinder<M,T> getBaseRecordListFinder()
      Returns Strategy object used to retrieve list.

    • getHasDetails

      public boolean getHasDetails()
      Returns whether records must lazy load additional data for detail pages.

    • getIdListFinder

      public IdListFinder<M,K> getIdListFinder()
      Returns Strategy used to retrieve list.

    • getItemDeepCopier

      public UnaryOperator<T> getItemDeepCopier()
      Returns Strategy for creating a deep copy of an item, or null if none set.

    • getItemFinder

      public SingleItemFinder<K,T> getItemFinder()
      Returns Strategy used to retrieve single item of list, including any extensions, or null if not set.

    • getItemSorter

      public ListCacheRecordComparator<T> getItemSorter()
      Returns Strategy used to sort list, or null for no sorting.

    • getKeyExtractor

      public KeyExtractor<K,T> getKeyExtractor()
      Returns Strategy that extracts the primary key from a record.

    • getList

      public List<T> getList() throws Exception
      Returns entire record list, loading it if needed.
      Throws:
      Exception

    • getListeners

      public Collection<ListCacheListener<T>> getListeners()
      Returns all listeners of any change to this.

    • getListFinder

      public ListFinder<M,T> getListFinder()
      Returns Strategy object used to retrieve list.

    • getListSize

      public int getListSize() throws Exception
      Returns list size.
      Throws:
      Exception

    • getListSizeFinder

      public ListSizeFinder<M> getListSizeFinder()
      Returns Strategy object used to retrieve list size.

    • getMasterList

      public ListCache<?,?,M> getMasterList()
      Returns master list cache, where records of this slave list cache are related to selected record of master list cache, or null if this is not a slave list.

    • getName

      public String getName()

    • getPage

      public List<T> getPage() throws Exception
      Returns current page containing selected record, loading records if needed.
      Throws:
      Exception

    • getPageByIdsFinder

      public PageByIdsFinder<K,T> getPageByIdsFinder()
      Returns Strategy object used to retrieve page by their record primary keys.

    • getPageByIndexRangeFinder

      public PageByIndexRangeFinder<M,T> getPageByIndexRangeFinder()
      Returns Strategy object used to retrieve page by their indices.

    • getPageExtensionAssembler

      public PageExtensionAssembler<T> getPageExtensionAssembler()
      Returns Transfer Object Assembler for adding record extensions needed for requested page that is not loaded by a base record list finder. Only applies for base record list pagination mode.

    • getPageNo

      public int getPageNo() throws Exception
      Returns number of current page, starting at 1, containing selected record.
      Throws:
      Exception

    • getPageSize

      public int getPageSize() throws Exception
      Throws:
      Exception

    • getPaginationMode

      public ListCache.PaginationMode getPaginationMode()
      Returns how pages are retrieved.

    • getRange

      public List<T> getRange(int startIndex, int endIndex) throws Exception
      Returns range of records from cached list, loading them if needed. If the start or end are out of range, they are treated as the index of the nearest item. Thus, at least one item is always returned unless no items exist at all.
      Throws:
      Exception

    • getReload

      public boolean getReload()
      Indicates if record list must be reloaded.

    • getReSort

      public boolean getReSort()
      Indicates if record list must be sorted.

    • getSelected

      public T getSelected() throws Exception
      Returns selected item from list.
      Throws:
      Exception

    • getSelectedNoDetail

      public T getSelectedNoDetail() throws Exception
      Returns selected item from list, which won't automatically load details.
      Throws:
      IllegalStateException - List finder not set and reload required.
      Exception

    • getSelectedIndex

      public int getSelectedIndex() throws Exception
      Returns index of currently selected item, starting at 0, in list.
      Throws:
      Exception

    • getTotalPages

      public int getTotalPages()

    • markReload

      public void markReload()
      Marks record list as requiring a reload.

    • markReSort

      public void markReSort()
      Marks record list as requiring a re-sort.

    • markSelectedReload

      public void markSelectedReload()
      Marks single item in list as requiring a reload.

    • remove

      public T remove(int index) throws IllegalStateException, Exception
      Removes item from list at index position and returns it. Returns null if no item exists at index.
      Throws:
      IllegalStateException - List must be reloaded but list finder is missing.
      Exception - Failed to retrieve extensions.

    • removeListCacheListener

      public void removeListCacheListener(ListCacheListener<T> listener)

    • removeSelected

      public T removeSelected() throws IllegalStateException, Exception
      Removes currently, selected item from list and returns it.

      Returns null if the list is empty and there is no selected item.

      Throws:
      IllegalStateException - List must be reloaded but list finder is missing.
      Exception - Failed to retrieve extensions.

    • setBaseRecordListAndFinder

      public void setBaseRecordListAndFinder(List<T> list, ListFinder<M,T> baseRecordListFinder)
      Caches list already loaded, sets base record list finder Strategy used to load it, and sets base record list pagination mode.

    • setBaseRecordListFinder

      public void setBaseRecordListFinder(ListFinder<M,T> baseRecordListFinder)
      Sets base record list finder, marks list for reload, and sets base record list pagination mode..

    • setIdListAndFinder

      public void setIdListAndFinder(List<K> idList, IdListFinder<M,K> idListFinder)
      Caches id list already loaded, sets id list finder Strategy used to load it, and sets page by ids pagination mode.

    • setIdListFinder

      public void setIdListFinder(IdListFinder<M,K> idListFinder)
      Sets Strategy used to retrieve ids, sets page by ids pagination mode and marks list for reload.

    • setItemDeepCopier

      public void setItemDeepCopier(UnaryOperator<T> itemDeepCopier)

    • setItemFinder

      public void setItemFinder(SingleItemFinder<K,T> value)
      Sets Strategy for retrieving single item of list, including details.

    • setItemSorter

      public void setItemSorter(ListCacheRecordComparator<T> itemSorter)
      Sets Strategy for sorting list data, overriding the list order of a list finder, or null to preserve list order.

    • setKeyExtractor

      public void setKeyExtractor(KeyExtractor<K,T> keyExtractor)
      Sets Strategy that extracts the primary key from a record.

    • setListAndFinder

      public void setListAndFinder(List<T> list, ListFinder<M,T> listFinder)
      Caches list already loaded, sets full list Strategy used to load it, and sets full list pagination mode.

    • setListFinder

      public void setListFinder(ListFinder<M,T> listFinder)
      Sets full list Strategy to retrieve list when needed and sets full list pagination mode.

    • setListSizeAndFinder

      public void setListSizeAndFinder(int listSize, ListSizeFinder<M> listSizeFinder, PageByIndexRangeFinder<M,T> pageByIndexRangeFinder)
      Sets list size, the list size finder used to find that, page by index range finder that will be used to find pages from list, and sets page by index pagination mode.
      Parameters:
      listSize - Size of list to cache.
      listSizeFinder - Command that found list size.
      pageByIndexRangeFinder - Command that will load pages of list.

    • setListSizeFinder

      public void setListSizeFinder(ListSizeFinder<M> listSizeFinder, PageByIndexRangeFinder<M,T> pageByIndexRangeFinder)
      Sets the list size finder, sets accompanying page by index range finder that will be used to find pages from list, sets page by index pagination mode, and marks list for reload.
      Parameters:
      listSizeFinder - Command that found list size.
      pageByIndexRangeFinder - Command that will load pages of list..

    • setPageByIdsFinder

      public void setPageByIdsFinder(PageByIdsFinder<K,T> value)
      Sets Strategy used to retrieve page by their record ids.

    • setPageExtensionAssembler

      public void setPageExtensionAssembler(PageExtensionAssembler<T> pageExtensionAssembler)
      Sets Transfer Object Assembler for adding record extensions needed for requested page that is not loaded by a base record list finder. Only applies for base record list pagination mode.

    • setPageNo

      public void setPageNo(int pageNo)
      Sets index of currently selected item to be first item of page where pageNo starts at one.

    • setPageSize

      public void setPageSize(int pageSize)

    • setSelected

      public void setSelected(T value)
      Replaces selected item in list.

    • setSelectedIndex

      public void setSelectedIndex(int index)
      Sets currently selected item in list by index. Sets to last item if index exceeds last item. Sets no currently selected item if index is -1.