org.ceryle.util
Class FrequencyModel

java.lang.Object
  javax.swing.AbstractListModel
      javax.swing.DefaultComboBoxModel
          org.ceryle.util.FrequencyModel

All Implemented Interfaces:

Serializable, Iterable, Collection, Set, ComboBoxModel, ListModel, MutableComboBoxModel

public class FrequencyModel
extends DefaultComboBoxModel
implements Set, ListModel, MutableComboBoxModel, Serializable

Extends the default model for ComboBoxes, DefaultComboBoxModel, using a Vector treated as a Set (ie., checking uniqueness of entries upon adding) as the data store to insure that items in the list are unique. This class is similar to SetModel, except that it wraps each stored Object in a SortableObject container, in order to maintain the rank order of each Object in the list in terms of the frequency of access, i.e., the most accessed objects move towards the top of the list.

An item's rank (an int value) can also be moved to the top or bottom of the list, or to an explicit position (though only using the ranking scheme). This can be done automatically on access to the list (when autoRank is true), or the default, by explicitly calling action(Object).

Because this implements Set, attempts to add Objects to the list that already are members does not add a duplicate Object, but does decrement (i.e., move towards the top of the list) that Object's rank within the list accordingly.

Note that the beginning (or top) of the list has the lowest int value, whereas the end (or bottom) of the list has the highest. There is no particular significance to the relative values of the list rankings, as they will tend to change during usage. This means that any change to the list may change an Object's ranking, and the exact value should not be relied upon; it is an implementation side-effect and is only used for sorting.

Autotrim

When set true, this will automatically trim the size of the model to the maximum size set by setMaximumSize(int). If set false trimModel() will have to be called manually. Note that if autotrim has been set true manual calls to trimModel() are ignored.

Since:

JDK1.4

Author:

Murray Altheim

See Also:

SetModel, SortableObject, DefaultComboBoxModel, DefaultListModel, Serialized Form

Field Summary

static boolean

autoRank When true, automatically alters the ranking on access to the model.

Fields inherited from class javax.swing.AbstractListModel

listenerList

Constructor Summary

FrequencyModel()
Constructs an empty FrequencyModel and no maximum size.

FrequencyModel(int maxsize)
Constructs an empty FrequencyModel and a maximum size of maxsize.

FrequencyModel(Object[] items, int maxsize)
Constructs a FrequencyModel object initialized with an array of objects and a maximum size of maxsize.

FrequencyModel(Vector vector, int maxsize)
Constructs a FrequencyModel object initialized with a Vector and a maximum size of maxsize.

Method Summary

void	action(Object o) Decrements the rank of Object o and then resorts the list, indicating activity on the Object.
boolean	add(Object o) Adds the Object o to the end (bottom) of this FrequencyModel, returning true if the addition was successful.
boolean	addAll(Collection collection) Adds all unique elements of the Collection collection to this FrequencyModel, returning true if all were successfully added.
void	addElement(Object o) Implements javax.swing.MutableComboBoxModel.
void	addElements(Collection collection) Adds all unique elements of the Collection collection to this FrequencyModel.
void	changedElementAt(int index) Notifies any listeners that the element at index has changed.
void	clear() Removes all the elements of this FrequencyModel.
boolean	contains(Object o) Returns true if the specified Object exists within the list.
boolean	containsAll(Collection c) Returns true if this FrequencyModel contains all of the elements of the provided Collection.
Object	get(int index) Implements javax.swing.AbstractList.
Object	getElementAt(int index) Implements javax.swing.ListModel.
Object	getFirstElement() Returns the first Element of the model, null if empty.
int	getIndexOf(Object o) Returns the index position of the specified object in the list.
Object	getLastElement() Returns the last Element of the model, null if empty.
int	getMaximumRank() Returns the current maximum ranking.
int	getMaximumSize() Return the current maximum size setting.
int	getMinimumRank() Returns the current minimum ranking.
Object	getSelectedItem() Implements javax.swing.ComboBoxModel.
int	getSize() Implements javax.swing.ListModel.
int	indexOf(Object o) Returns the index position of the specified object in the list.
int	indexOf(Object o, int index) Returns the index position of the specified object in the list, beginning the search at index.
void	insertElementAt(Object o, int index) This inserts the Object o at position index, by ranking the object and adding it to the list.
boolean	isEmpty() Returns true if the contents of this FrequencyModel are empty.
Iterator	iterator() Returns an iterator over the contents of this FrequencyModel, null if empty.
boolean	moveToBeginning(Object o) Moves the Object o to the first element (top) position in the model.
int	rankOf(Object o) Returns the current ranking of Object o as an int.
Object	remove(int index) Implementation method of java.util.List.
boolean	remove(Object o) Implements java.util.List.
boolean	removeAll(Collection c) Removes all the elements of this FrequencyModel that are contained within the provided Collection.
void	removeAllElements() Empties the list.
void	removeElement(Object o) Implements javax.swing.MutableComboBoxModel.
void	removeElementAt(int index) Removes the element at position index.
void	removeWeight() Does not change the sequence of the Objects within the model, but eliminates the weighting acrued (the number of "hits") by each.
boolean	retainAll(Collection c) Retains only the elements in this FrequencyModel that are contained within the provided Collection.
void	setMaximumSize(int max) If the maximum size is set (by default it is -1), the list will be auto-trimmed to limit, from the bottom (least popular).
void	setSelectedItem(Object o) Implements javax.swing.ComboBoxModel.
int	size() Implements java.util.Collection.
void	sort() Sorts the values of the list, and reassigns rank numbers.
Object[]	toArray() Returns an array containing all the elements in their current sequence.
Object[]	toArray(Object[] array) Returns an array containing all the elements in their current sequence, with the runtime type of the returned array that of the provided array.
String	toString()
List	trimModel() Trims the size of the model to fit within its maximum size limit, if this has been set.

Methods inherited from class javax.swing.AbstractListModel

addListDataListener, fireContentsChanged, fireIntervalAdded, fireIntervalRemoved, getListDataListeners, getListeners, removeListDataListener

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Set

equals, hashCode

Field Detail

autoRank

public static boolean autoRank

When true, automatically alters the ranking on access to the model. When false, relies on explicit calls to action(Object). Default is false.

Constructor Detail

FrequencyModel

public FrequencyModel()

Constructs an empty FrequencyModel and no maximum size.

FrequencyModel

public FrequencyModel(int maxsize)

Constructs an empty FrequencyModel and a maximum size of maxsize.

FrequencyModel

public FrequencyModel(Object[] items,
                      int maxsize)

Constructs a FrequencyModel object initialized with an array of objects and a maximum size of maxsize.

Parameters:

items - an array of Object objects

maxsize - the maximum size of the cache before trimming; if less than one no autotrim occurs.

FrequencyModel

public FrequencyModel(Vector vector,
                      int maxsize)

Constructs a FrequencyModel object initialized with a Vector and a maximum size of maxsize.

Parameters:

vector - the Vector object

maxsize - the maximum size of the cache before trimming; if less than one no autotrim occurs.

Method Detail

action

public void action(Object o)

Decrements the rank of Object o and then resorts the list, indicating activity on the Object.

add

public boolean add(Object o)

Adds the Object o to the end (bottom) of this FrequencyModel, returning true if the addition was successful. If the object already exists in the list, nothing happens, returns false. If an Object is already in the list, its rank is decremented. This is identical to the method addElement(Object) except for the return type.

Specified by:

add in interface Collection

Specified by:

add in interface Set

addAll

public boolean addAll(Collection collection)

Adds all unique elements of the Collection collection to this FrequencyModel, returning true if all were successfully added. If an Object already exists in the list, it is not added again (and the method returns false, even if some were added). If an Object is already in the list, its rank is decremented. If the provided collection is empty, returns true. This is identical to the method addElements(Collection) except for the return type.

Specified by:

addAll in interface Collection

Specified by:

addAll in interface Set

addElement

public void addElement(Object o)

Implements javax.swing.MutableComboBoxModel. If the Object is already in the list, its rank is decremented.

Specified by:

addElement in interface MutableComboBoxModel

Overrides:

addElement in class DefaultComboBoxModel

addElements

public void addElements(Collection collection)

Adds all unique elements of the Collection collection to this FrequencyModel. If the Object is already in the list, it is not added again, but its rank is decremented.

changedElementAt

public void changedElementAt(int index)

Notifies any listeners that the element at index has changed.

clear

public void clear()

Removes all the elements of this FrequencyModel. This is a synonym for removeAllElements().

Specified by:

clear in interface Collection

Specified by:

clear in interface Set

contains

public boolean contains(Object o)

Returns true if the specified Object exists within the list.

Specified by:

contains in interface Collection

Specified by:

contains in interface Set

Parameters:

o - the specified Object

Returns:

true if the list contains the Object.

containsAll

public boolean containsAll(Collection c)

Returns true if this FrequencyModel contains all of the elements of the provided Collection.

Specified by:

containsAll in interface Collection

Specified by:

containsAll in interface Set

get

public Object get(int index)

Implements javax.swing.AbstractList.

getElementAt

public Object getElementAt(int index)

Implements javax.swing.ListModel.

Specified by:

getElementAt in interface ListModel

Overrides:

getElementAt in class DefaultComboBoxModel

getFirstElement

public Object getFirstElement()

Returns the first Element of the model, null if empty.

getIndexOf

public int getIndexOf(Object o)

Returns the index position of the specified object in the list.

Overrides:

getIndexOf in class DefaultComboBoxModel

Parameters:

o - the specified Object.

Returns:

an int representing the index position, where 0 is the first position.

getLastElement

public Object getLastElement()

Returns the last Element of the model, null if empty.

getMaximumRank

public int getMaximumRank()

Returns the current maximum ranking. If empty, returns 0.

getMaximumSize

public int getMaximumSize()

Return the current maximum size setting.

getMinimumRank

public int getMinimumRank()

Returns the current minimum ranking. If empty, returns 0.

getSelectedItem

public Object getSelectedItem()

Implements javax.swing.ComboBoxModel.

Specified by:

getSelectedItem in interface ComboBoxModel

Overrides:

getSelectedItem in class DefaultComboBoxModel

getSize

public int getSize()

Implements javax.swing.ListModel.

Specified by:

getSize in interface ListModel

Overrides:

getSize in class DefaultComboBoxModel

indexOf

public int indexOf(Object o)

Returns the index position of the specified object in the list.

Parameters:

o - the specified Object.

Returns:

true if the list contains the Object.

indexOf

public int indexOf(Object o,
                   int index)

Returns the index position of the specified object in the list, beginning the search at index. This tests for equality using the equals() method, and also tests for null.

Parameters:

o - the specified Object.

index - the non-negative index to start searching from.

Returns:

true if the list contains the Object.

Throws:

IndexOutOfBoundsException - if index is negative.

insertElementAt

public void insertElementAt(Object o,
                            int index)

This inserts the Object o at position index, by ranking the object and adding it to the list. Note that it does not re-sort the list; the position of the Object within the list is not established until a sort occurs. If the Object is already in the list, its rank is decremented.

Because this mixes the original usage of this method (i.e., dealing with Objects in the list via their index position) with FrequencyModel's ranking methodology, this should be used with caution.

Implements javax.swing.MutableComboBoxModel.

Specified by:

insertElementAt in interface MutableComboBoxModel

Overrides:

insertElementAt in class DefaultComboBoxModel

isEmpty

public boolean isEmpty()

Returns true if the contents of this FrequencyModel are empty.

Specified by:

isEmpty in interface Collection

Specified by:

isEmpty in interface Set

iterator

public Iterator iterator()

Returns an iterator over the contents of this FrequencyModel, null if empty.

Specified by:

iterator in interface Iterable

Specified by:

iterator in interface Collection

Specified by:

iterator in interface Set

moveToBeginning

public boolean moveToBeginning(Object o)

Moves the Object o to the first element (top) position in the model. If the model doesn't already contain the Object, it is added. Returns true if the object was new to the list. If the item was not in the list previously, a message is fired to the listener.

Note that in SetModel, this required a delete and an insert, whereas in this class it involves a change to the Object's rank and a resort.

Returns:

true if the Object is new to the list.

rankOf

public int rankOf(Object o)

Returns the current ranking of Object o as an int. This may change with any accesses or modifications to the list, though the ranking is not affected by this method. If the Object is not in this FrequencyModel, returns -1.

remove

public Object remove(int index)

Implementation method of java.util.List.

Returns:

the removed Object

remove

public boolean remove(Object o)

Implements java.util.List. If the element does not exist in the FrequencyModel, nothing happens.

Specified by:

remove in interface Collection

Specified by:

remove in interface Set

removeAll

public boolean removeAll(Collection c)

Removes all the elements of this FrequencyModel that are contained within the provided Collection.

Specified by:

removeAll in interface Collection

Specified by:

removeAll in interface Set

Returns:

true if this FrequencyModel contained all of the elements within the provided Collection

removeAllElements

public void removeAllElements()

Empties the list.

Overrides:

removeAllElements in class DefaultComboBoxModel

removeElement

public void removeElement(Object o)

Implements javax.swing.MutableComboBoxModel. If the element does not exist in the FrequencyModel, nothing happens.

Specified by:

removeElement in interface MutableComboBoxModel

Overrides:

removeElement in class DefaultComboBoxModel

removeElementAt

public void removeElementAt(int index)

Removes the element at position index.

Because this mixes the original usage of this method (i.e., dealing with Objects in the list via their index position) with FrequencyModel's ranking methodology, this should be used with caution.

Implements javax.swing.MutableComboBoxModel.

Specified by:

removeElementAt in interface MutableComboBoxModel

Overrides:

removeElementAt in class DefaultComboBoxModel

removeWeight

public void removeWeight()

Does not change the sequence of the Objects within the model, but eliminates the weighting acrued (the number of "hits") by each.

Note that if a maximum size is set, this method is called upon each addition to the list in order to allow new items to gain in popularity.

retainAll

public boolean retainAll(Collection c)

Retains only the elements in this FrequencyModel that are contained within the provided Collection.

Specified by:

retainAll in interface Collection

Specified by:

retainAll in interface Set

Returns:

true if this FrequencyModel contained all of the elements within the provided Collection

setMaximumSize

public void setMaximumSize(int max)

If the maximum size is set (by default it is -1), the list will be auto-trimmed to limit, from the bottom (least popular). Setting to a number less than 1 disables the feature again.

Parameters:

max - the maximum size of the cache before trimming; if less than one no autotrim occurs.

setSelectedItem

public void setSelectedItem(Object o)

Implements javax.swing.ComboBoxModel. If the Object is not currently contained within the list, nothing happens.

Specified by:

setSelectedItem in interface ComboBoxModel

Overrides:

setSelectedItem in class DefaultComboBoxModel

size

public int size()

Implements java.util.Collection.

Specified by:

size in interface Collection

Specified by:

size in interface Set

sort

public void sort()

Sorts the values of the list, and reassigns rank numbers.

toArray

public Object[] toArray()

Returns an array containing all the elements in their current sequence.

Specified by:

toArray in interface Collection

Specified by:

toArray in interface Set

toArray

public Object[] toArray(Object[] array)

Returns an array containing all the elements in their current sequence, with the runtime type of the returned array that of the provided array.

Specified by:

toArray in interface Collection

Specified by:

toArray in interface Set

toString

public String toString()

Overrides:

toString in class Object

trimModel

public List trimModel()

Trims the size of the model to fit within its maximum size limit, if this has been set. If a maximum size is not set this method does nothing (just returning an empty List);

Returns:

the List of objects removed.