Package com.smartgwt.client.data

Class RecordList

java.lang.Object
com.smartgwt.client.core.BaseClass
com.smartgwt.client.data.RecordList
All Implemented Interfaces:
HasHandlers, HasDataChangedHandlers
Direct Known Subclasses:
ResultSet, Tree
public class RecordList extends BaseClass implements HasDataChangedHandlers
An an ordered collection of Records.

This class is expected by list-oriented display components such as the ListGrid.

  • Field Details

  • Constructor Details

    • RecordList

      public RecordList()
      Construct a RecordList with no initial data. Use the various add* methods to add Records to this list.

    • RecordList

      public RecordList(Record[] data)
      Construct a RecordList with initial data.
      Parameters:
      data - initial Record data

    • RecordList

      public RecordList(List<? extends Record> data)

    • RecordList

      public RecordList(JavaScriptObject jsObj)

  • Method Details

    • isARecordList

      public static boolean isARecordList(Object obj)

    • getOrCreateRef

      public static RecordList getOrCreateRef(JavaScriptObject jsObj)

    • create

      protected JavaScriptObject create()
      Specified by:
      create in class BaseClass

    • getJsObj

      public JavaScriptObject getJsObj()
      Overrides:
      getJsObj in class BaseClass

    • isCreated

      public boolean isCreated()
      Overrides:
      isCreated in class BaseClass

    • getOrCreateJsObj

      public JavaScriptObject getOrCreateJsObj()
      Overrides:
      getOrCreateJsObj in class BaseClass

    • get

      public Record get(int pos)
      Return the item at a particular position
      Parameters:
      pos - position of the element to get
      Returns:
      whatever's at that position, null if not found

    • getLength

      public int getLength()
      Return the number of items in this list
      Returns:
      number of items in the list

    • isEmpty

      public Boolean isEmpty()
      Return whether or not this array is empty
      Returns:
      true == this array is empty, false == some items in the array

    • first

      public Record first()
      Return the first item in this list
      Returns:
      first item in the list

    • last

      public Record last()
      Return the last item in this list
      Returns:
      last item in the list

    • indexOf

      public int indexOf(Record record)
      Return the position in the list of the first instance of the specified object.

      If pos is specified, starts looking after that position.

      Returns -1 if not found.

      Parameters:
      record - object to look for
      Returns:
      position of the item, if found, -1 if not found

    • indexOf

      public int indexOf(Record record, int pos, int endPos)
      Return the position in the list of the first instance of the specified object.

      If pos is specified, starts looking after that position.

      Returns -1 if not found.

      Parameters:
      record - object to look for
      pos - earliest index to consider
      endPos - last index to consider
      Returns:
      position of the item, if found, -1 if not found

    • lastIndexOf

      public int lastIndexOf(Record record)
      Return the position in the list of the last instance of the specified object.

      If pos is specified, starts looking before that position.

      Returns -1 if not found.

      Parameters:
      record - object to look for
      Returns:
      position of the item, if found, -1 if not found

    • lastIndexOf

      public int lastIndexOf(Record record, int pos, int endPos)
      Return the position in the list of the last instance of the specified object.

      If pos is specified, starts looking before that position.

      Returns -1 if not found.

      Parameters:
      record - object to look for
      pos - last index to consider
      endPos - earliest index to consider
      Returns:
      position of the item, if found, -1 if not found

    • findIndex

      public int findIndex(Map properties)
      Find the index of the first Record where property == value in the object.

      Note: for string values, matches are case sensitive.

      Parameters:
      properties - set of properties and values to match
      Returns:
      index of the first matching Record or -1 if not found

    • findIndex

      public int findIndex(String propertyName, String value)
      Find the index of the first Record where property == value in the object.

      Note: for string values, matches are case sensitive.

      Parameters:
      propertyName - property to match
      value - value to compare against (if propertyName is a string)
      Returns:
      index of the first matching Record or -1 if not found

    • findIndex

      public int findIndex(String propertyName, int value)
      Find the index of the first Record where property == value in the object.
      Parameters:
      propertyName - property to match
      value - value to compare against (if propertyName is a string)
      Returns:
      index of the first matching Record or -1 if not found

    • findIndex

      public int findIndex(String propertyName, Long value)
      Find the index of the first Record where property == value in the object.

      Note: JavaScript has no long type, so the long value becomes a JavaScript Number, which has a lesser range than Java long. The range for integer numbers in Javascript is [-9007199254740992,9007199254740992] or [-Math.pow(2,53),Math.pow(2,53)].

      Parameters:
      propertyName - property to match
      value - value to compare against (if propertyName is a string)
      Returns:
      index of the first matching Record or -1 if not found

    • findIndex

      public int findIndex(String propertyName, float value)
      Find the index of the first Record where property == value in the object.
      Parameters:
      propertyName - property to match
      value - value to compare against (if propertyName is a string)
      Returns:
      index of the first matching Record or -1 if not found

    • findIndex

      public int findIndex(String propertyName, boolean value)
      Find the index of the first Record where property == value in the object.
      Parameters:
      propertyName - property to match
      value - value to compare against (if propertyName is a string)
      Returns:
      index of the first matching Record or -1 if not found

    • findIndex

      public int findIndex(String propertyName, Date value)
      Find the index of the first Record where property == value in the object.
      Parameters:
      propertyName - property to match
      value - value to compare against (if propertyName is a string)
      Returns:
      index of the first matching Record or -1 if not found

    • findNextIndex

      public int findNextIndex(int startIndex, String propertyName)
      Like findIndex(java.util.Map), but inspects a range from startIndex to endIndex.
      Parameters:
      startIndex - first index to consider
      propertyName - property to match
      Returns:
      index of the first matching Record or -1 if not found

    • findNextIndex

      public int findNextIndex(int startIndex, Map properties)
      Like findIndex(java.util.Map), but inspects a range from startIndex to endIndex.
      Parameters:
      startIndex - first index to consider
      properties - set of properties and values to match
      Returns:
      index of the first matching Record or -1 if not found

    • findNextIndex

      public int findNextIndex(int startIndex, String propertyName, String value, int endIndex)
      Like findIndex(java.util.Map), but inspects a range from startIndex to endIndex.
      Parameters:
      startIndex - first index to consider
      propertyName - property to match
      value - value to compare against (if propertyName is a string)
      endIndex - last index to consider
      Returns:
      index of the first matching Record or -1 if not found

    • findNextIndex

      public int findNextIndex(int startIndex, String propertyName, int value, int endIndex)
      Like findIndex(java.util.Map), but inspects a range from startIndex to endIndex.
      Parameters:
      startIndex - first index to consider
      propertyName - property to match
      value - value to compare against (if propertyName is a string)
      endIndex - last index to consider
      Returns:
      index of the first matching Record or -1 if not found

    • findNextIndex

      public int findNextIndex(int startIndex, String propertyName, Long value, int endIndex)
      Like findIndex(java.util.Map), but inspects a range from startIndex to endIndex.

      Note: JavaScript has no long type, so the long value becomes a JavaScript Number, which has a lesser range than Java long. The range for integer numbers in Javascript is [-9007199254740992,9007199254740992] or [-Math.pow(2,53),Math.pow(2,53)].

      Parameters:
      startIndex - first index to consider
      propertyName - property to match
      value - value to compare against (if propertyName is a string)
      endIndex - last index to consider
      Returns:
      index of the first matching Record or -1 if not found

    • findNextIndex

      public int findNextIndex(int startIndex, String propertyName, float value, int endIndex)
      Like findIndex(java.util.Map), but inspects a range from startIndex to endIndex.
      Parameters:
      startIndex - first index to consider
      propertyName - property to match
      value - value to compare against (if propertyName is a string)
      endIndex - last index to consider
      Returns:
      index of the first matching Record or -1 if not found

    • findNextIndex

      public int findNextIndex(int startIndex, String propertyName, boolean value, int endIndex)
      Like findIndex(java.util.Map), but inspects a range from startIndex to endIndex.
      Parameters:
      startIndex - first index to consider
      propertyName - property to match
      value - value to compare against (if propertyName is a string)
      endIndex - last index to consider
      Returns:
      index of the first matching Record or -1 if not found

    • findNextIndex

      public int findNextIndex(int startIndex, String propertyName, Date value, int endIndex)
      Like findIndex(java.util.Map), but inspects a range from startIndex to endIndex.
      Parameters:
      startIndex - first index to consider
      propertyName - property to match
      value - value to compare against (if propertyName is a string)
      endIndex - last index to consider
      Returns:
      index of the first matching Record or -1 if not found

    • find

      public Record find(String propertyName, Object value)
      Like findIndex(java.util.Map), but returns the object itself instead of its index.
      Parameters:
      propertyName - property to match
      value - value to compare against (if propertyName is a string)
      Returns:
      first matching object or null if not found

    • find

      public Record find(String propertyName, Date value)
      Like findIndex(java.util.Map), but returns the object itself instead of its index.
      Parameters:
      propertyName - property to match
      value - value to compare against (if propertyName is a string)
      Returns:
      first matching object or null if not found

    • find

      public Record find(String propertyName, Long value)
      Like findIndex(java.util.Map), but returns the object itself instead of its index.

      Note: JavaScript has no long type, so the long value becomes a JavaScript Number, which has a lesser range than Java long. The range for integer numbers in Javascript is [-9007199254740992,9007199254740992] or [-Math.pow(2,53),Math.pow(2,53)].

      Parameters:
      propertyName - property to match
      value - value to compare against (if propertyName is a string)
      Returns:
      first matching object or null if not found

    • find

      public Record find(String propertyName, Boolean value)
      Like findIndex(java.util.Map), but returns the object itself instead of its index.
      Parameters:
      propertyName - property to match
      value - value to compare against (if propertyName is a string)
      Returns:
      first matching object or null if not found

    • findAll

      public Record[] findAll(Map properties)
      Find all objects where property == value in the object
      Parameters:
      properties - set of properties and values to match
      Returns:
      all matching Objects or null if none found

    • findAll

      public Record[] findAll(String propertyName, String value)
      Find all objects where property == value in the object.
      Parameters:
      propertyName - property to match
      value - value to compare against (if propertyName is a string)
      Returns:
      all matching Objects or null if none found

    • findAll

      public Record[] findAll(String propertyName, int value)
      Find all objects where property == value in the object
      Parameters:
      propertyName - property to match
      value - value to compare against (if propertyName is a string)
      Returns:
      all matching Objects or null if none found

    • findAll

      public Record[] findAll(String propertyName, Long value)
      Find all objects where property == value in the object

      Note: JavaScript has no long type, so the long value becomes a JavaScript Number, which has a lesser range than Java long. The range for integer numbers in Javascript is [-9007199254740992,9007199254740992] or [-Math.pow(2,53),Math.pow(2,53)].

      Parameters:
      propertyName - property to match
      value - value to compare against (if propertyName is a string)
      Returns:
      all matching Objects or null if none found

    • findAll

      public Record[] findAll(String propertyName, float value)
      Find all objects where property == value in the object
      Parameters:
      propertyName - property to match
      value - value to compare against (if propertyName is a string)
      Returns:
      all matching Objects or null if none found

    • findAll

      public Record[] findAll(String propertyName, boolean value)
      Find all objects where property == value in the object.
      Parameters:
      propertyName - property to match
      value - value to compare against (if propertyName is a string)
      Returns:
      all matching Objects or null if none found

    • findAll

      public Record[] findAll(String propertyName, Date value)
      Find all objects where property == value in the object.
      Parameters:
      propertyName - property to match
      value - value to compare against (if propertyName is a string)
      Returns:
      all matching Objects or null if none found

    • findAll

      public Record[] findAll(AdvancedCriteria adCriteria)
      Filters all objects according to the AdvancedCriteria passed
      Parameters:
      adCriteria - AdvancedCriteria to use to filter results
      Returns:
      all matching Objects or null if none found

    • find

      public Record find(AdvancedCriteria adCriteria)
      Filters all objects according to the AdvancedCriteria passed and returns the first matching object or null if not found
      Parameters:
      adCriteria - AdvancedCriteria to use to filter results
      Returns:
      first matching object or null if not found

    • findIndex

      public int findIndex(AdvancedCriteria adCriteria)
      Finds the index of the first Record that matches with the AdvacendCriteria passed.
      Parameters:
      adCriteria - AdvancedCriteria to use to filter results
      Returns:
      index of the first matching Record or -1 if not found

    • findNextIndex

      public int findNextIndex(int startIndex, AdvancedCriteria adCriteria, int endIndex)
      Like findIndex(java.util.Map), but considering the startIndex and endIndex parameters.
      Parameters:
      startIndex - first index to consider
      adCriteria - AdvancedCriteria to use to filter results
      endIndex - last index to consider
      Returns:
      index of the first matching Record or -1 if not found

    • findNextIndex

      public int findNextIndex(int startIndex, AdvancedCriteria adCriteria)
      Like findIndex(java.util.Map), but considering the startIndex parameter.
      Parameters:
      startIndex - first index to consider
      adCriteria - AdvancedCriteria to use to filter results
      Returns:
      index of the first matching Record or -1 if not found

    • contains

      public Boolean contains(Record record)
      Return if this list contains the specified object.
      Parameters:
      record - item to look for
      Returns:
      true == item was found, false == not found

    • contains

      public Boolean contains(Record record, int pos)
      Return if this list contains the specified object.

      If pos is specified, starts looking after that position.

      Parameters:
      record - item to look for
      pos - optional position in the list to look after
      Returns:
      true == item was found, false == not found

    • containsAll

      public Boolean containsAll(RecordList list)
      Return whether this list contains all the item in the specified list.
      Parameters:
      list - items to look for
      Returns:
      whether all items were found

    • intersect

      public RecordList intersect(RecordList list)
      Return the list of items that are in both this list and the passed-in list.
      Parameters:
      list - list to intersect with
      Returns:
      intersection

    • equals

      public Boolean equals(RecordList list)
      Return whether this list is equal to another list.

      Two lists are equal only if they have the same length and all contained items are in the same order and are also equal.

      Parameters:
      list - list to check for equality
      Returns:
      whether the specified list is equal to this list

    • getItems

      public Record[] getItems(int[] itemList)
      Return the items at a list of specified positions.
      Parameters:
      itemList - array of positions
      Returns:
      subset of the array, in the same order as itemList

    • getRange

      public Record[] getRange(int start, int end)
      Return the items between position start and end, non-inclusive at the end.
      Parameters:
      start - start position
      end - end position
      Returns:
      subset of the array from start -> end-1

    • duplicate

      public Record[] duplicate()
      Return an Array that is a shallow copy of the list, that is, containing the same items.
      Returns:
      new array, pointing to the same items

    • set

      public Record set(int pos, Record record)
      Change the array element at a particular position.

      set() can be used to expand the length of the list.

      Parameters:
      pos - position in the list to change
      record - new value for that position
      Returns:
      whatever's at that position, null if not found

    • addAt

      public Record addAt(Record record, int pos)
      Add a single item to this array at a specific position in the list, sliding other items over to fit.
      Parameters:
      record - object to add
      pos - position in the list to add at
      Returns:
      object that was added

    • removeAt

      public Record removeAt(int pos)
      Remove the item at the specified position, rearranging all subsequent items to fill the gap
      Parameters:
      pos - position to remove
      Returns:
      item that was removed

    • add

      public void add(Record record)
      Add an object to this list, at the end
      Parameters:
      record - object to add

    • addList

      public void addList(Record[] list)
      Add a list of items to this array.

      Note: you can specify that a subset range be added by passing start and end indices

      Parameters:
      list - list of items to add

    • addList

      public void addList(Record[] list, int listStartRow, int listEndRow)
      Add a list of items to this array.

      Note: you can specify that a subset range be added by passing start and end indices

      Parameters:
      list - list of items to add
      listStartRow - optional start index in list
      listEndRow - optional end index in list (non-inclusive)

    • setLength

      public void setLength(int length)
      Set the length of this list.

      If the length of the list is shortened, any elements past the new length of the list are removed. If the length is increased, all positions past the old length have the value undefined.

      Parameters:
      length - new length

    • addListAt

      public void addListAt(Record[] list, int pos)
      Add list of items list to this array at item pos. All items after array[pos] will slide down to fit new items.
      Parameters:
      list - new array of items
      pos - position in this list to put the new items

    • remove

      public Boolean remove(Record record)
      Remove first instance of the passed object from this array, sliding other items around to fill gaps.
      Parameters:
      record - item to remove
      Returns:
      true if a matching object was found and removed, false if no matching object was found and the list remains unchanged.

    • removeList

      public void removeList(Record[] list)
      Remove all instances of objects in the specified list from this list, sliding the remaining objects around to fill gaps.
      Parameters:
      list - list of items to remove

    • sort

      public void sort()
      Sorts the elements of the List in place.

      The optional comparator function should take two parameters "a" and "b" which are the two list items to compare, and should return:

      • a value less than zero, if "a" is less than "b" such that "a" should appear earlier in the list
      • zero, if "a" and "b" are equal
      • a value greater than zero, if "a" is greater than "b" such that "b" should appear earlier in the list

    • sort

      public RecordList sort(Comparator<Record> comparator)
      Sorts the elements of the List in place.

      The optional comparator function should take two parameters "a" and "b" which are the two list items to compare, and should return:

      • a value less than zero, if "a" is less than "b" such that "a" should appear earlier in the list
      • zero, if "a" and "b" are equal
      • a value greater than zero, if "a" is greater than "b" such that "b" should appear earlier in the list
      Parameters:
      comparator - comparator function to use
      Returns:
      the list itself

    • getProperty

      public Object[] getProperty(String property)
      Return a new Array where the value of item i is the value of "property" of item i in this array. If an item doesn't have that property or is null, return item will be null.
      Parameters:
      property - name of the property to look for
      Returns:
      array of the values of property in each item of this list

    • sortByProperty

      public RecordList sortByProperty(String property, boolean up)
      Sort a list of objects by a given property of each item.

      The optional normalizer, if passed as a function, is called for each item in the List, and should return whatever value should be used for sorting, which does not have to agree with the property value. By passing a normalizer function you can achieve any kind of sorting you'd like, including sorting by multiple properties.

      NOTE: string sort is case INsensitive by default

      Parameters:
      property - name of the property to sort by
      up - true == sort ascending, false == sort descending
      Returns:
      the list itself

    • sortByProperty

      public void sortByProperty(String property, boolean up, RecordList.SortNormalizer normalizer)
      Sort this ResultSet by a property of each record.

      Sorting is performed on the client for a ResultSet that has a full cache for the current filter criteria. Otherwise, sorting is performed by the server, and changing the sort order will invalidate the cache.

      NOTE: normalizers are not supported by ResultSets in "paged" mode

      Parameters:
      property - name of the property to sort by
      up - true == sort ascending, false == sort descending
      normalizer - May be specified as a callbac with signature normalize(item, propertyName), where item is reference to the item in the array, propertyName is the property by which the array is being sorted. Normalizer function should return the value normalized for sorting.

    • setSort

      public void setSort(SortSpecifier... sortSpecifiers)
      Multi-Property sort. Sort this ResultSet by a list of SortSpecifier's.
      Parameters:
      sortSpecifiers - a list of SortSpecifier objects, one per sort-field and direction

    • getValueMap

      public Map getValueMap(String idField, String displayField)
      Get a map of the form { item[idField] -> item[displayField] }, for all items in the list. Note that if more than one item has the same idProperty, the value for the later item in the list will clobber the value for the earlier item.
      Parameters:
      idField - Property to use as ID (data value) in the valueMap
      displayField - Property to use a display value in the valueMap
      Returns:
      valueMap object

    • addDataChangedHandler

      public HandlerRegistration addDataChangedHandler(DataChangedHandler handler)
      Add a DataChanged handler.

      Notification fired when data changes in some way. Note that this will only fire when items are added, removed or rearranged. If a list contains objects, this method will not fire if changes are made to objects within the list without changing their position within the list

      Specified by:
      addDataChangedHandler in interface HasDataChangedHandlers
      Parameters:
      handler - the DataChanged handler
      Returns:
      HandlerRegistration used to remove this handler

    • toArray

      public Record[] toArray()
      Returns the records in this RecordList as an array.
      Returns:
      an array of records.

    • getRangeList

      public RecordList getRangeList(int start, int end)
      Return a RecordList with the items between position start and end, non-inclusive at the end.
      Parameters:
      start - start position
      end - end position
      Returns:
      a RecordList with the items from start -> end-1