com.gremwell.history
Class History

java.lang.Object
  com.gremwell.history.History

public class History
extends java.lang.Object

History class implements persistent and transient input history storage for use with autocomplete text components.

It keeps a list of strings that were entered by the user and allows to retrieve a subset based on a substring match. The input history items are weighted according to the number of times they were used. This allows to return the input history to the user in order of relevance - most often used items first.

An application can maintain multiple input histories. For example, you may want a different history for the street name and for postal code. To distinguish between different histories, this class uses historyKey property. Call setKey("street name") after instantiating a history to create a separate history for street names.

History uses Java preferences to store the input history between application invocations. If you don't want the history to persist, use setKey(null).

Constructor Summary

History()
Creates a new persistent history with the key "Default".

History(java.lang.String key)
Creates a new history with the specified history key.

Method Summary

void	addItem(java.lang.String item) Adds item to history.
void	clear() Clears the history.
java.util.List<java.lang.String>	getAll() Returns all items in the history, most used first
java.util.List<java.lang.String>	getFiltered(java.lang.String filter, boolean fromStart) Returns the history filtered by substring, sorted by usage
java.lang.String	getFilteredItem(int n, java.lang.String filter, boolean fromStart) Returns the nth most used item from the filtered history.
java.lang.String	getItem(int n) Returns one item in history, nth most used.
java.lang.String	getKey() Returns history key for this history.
void	setKey(java.lang.String key) Sets the history key for this history.

Methods inherited from class java.lang.Object

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

Constructor Detail

History

public History()

Creates a new persistent history with the key "Default". The history contents will be stored in user preferenced under the node "Default" The constructor will load history items if present in preferences.

History

public History(java.lang.String key)

Creates a new history with the specified history key. History key allows to distinguish between separate independent histories. Loads the history data for the specified history key.
If the key parameter is set to null, the history becomes non-persistent - it does not get stored in Java preferences and thus disappears when the application exits or the history object is garbage-collected.

Parameters:

key - - History key

Method Detail

getKey

public java.lang.String getKey()

Returns history key for this history.

Returns:

History key. May be null.

setKey

public void setKey(java.lang.String key)

Sets the history key for this history. If the history key is not null, attemtps to load the history items from Java preferences. If preferences are not available, reverts to being a transient history (stored in memory only) and sets the key to null

Parameters:

key - History key

getAll

public java.util.List<java.lang.String> getAll()

Returns all items in the history, most used first

Returns:

list of strings, sorted by number of uses, most used first

getItem

public java.lang.String getItem(int n)

Returns one item in history, nth most used. This method is mostly useful as getItem(0) to get the most used item

Parameters:

n -

Returns:

String representing the nth item

getFiltered

public java.util.List<java.lang.String> getFiltered(java.lang.String filter,
                                                    boolean fromStart)

Returns the history filtered by substring, sorted by usage

Parameters:

filter - String to match history items. Match is case-sensitive

fromStart - If fromStart is true, the filter is matched to the start of the history items, using item.startsWith(filter), otherwise it is matched anywhere in the item, using item.contains(filter)

Returns:

getFilteredItem

public java.lang.String getFilteredItem(int n,
                                        java.lang.String filter,
                                        boolean fromStart)

Returns the nth most used item from the filtered history. Most useful as getFilteredItem(0) to return the most used item from the historu matching the filter

Parameters:

n - Which item to return.

filter - String to match history items. Match is case-sensitive

fromStart - If fromStart is true, the filter is matched to the start of the history items, using item.startsWith(filter), otherwise it is matched anywhere in the item, using item.contains(filter)

Returns:

addItem

public void addItem(java.lang.String item)

Adds item to history. This method should be called by the component that uses the history object whenever an item from the history is selected and used. For example, in case of a combo-box whnever a user selects a history item from a drop-down box, this method should be called to add the selected item to the history. If the item already exists in the history, its use count is incremented thus keeping track of usage statistics.

Parameters:

item -

clear

public void clear()
           throws java.util.prefs.BackingStoreException

Clears the history. If the hostory is persistent, the persistent storage is cleared too

Throws:

java.util.prefs.BackingStoreException