org.vostok.lang
Class PriorityList

java.lang.Object
  extended by org.vostok.lang.PriorityList
All Implemented Interfaces:
java.lang.Iterable<Entry>, java.util.Collection<Entry>

public class PriorityList
extends java.lang.Object
implements java.util.Collection<Entry>

A List that reorders its childs according to the frequence of access.

A priority list should be used when target element position's cannot be determined in advence, so a sequencial iteration must be used but the deviation is narrow. Each time a request is done for a specific element, its position change, up on the list, therefore, when doing a sequencial iteration it's likely to be checked sooner.

Version:
1.0
Author:
levreau.jerome@vostoksystem.eu

Field Summary
protected  Entry[] array
          internal array of data, ordered : first = most used
static int DEFAULT_GROW_STEP
          Default growing step for the internal array when adding new element
static float DEFAULT_ITEM_RELOCATION_DEPRECIATION
          when a match is found outside the priority zone, the item must be relocated up. 1.0f mean directly up to the top, 0.0f mean no relocation at all !
static float DEFAULT_PRIORITY_ZONE
          if a matching glob is found into this percent of the array, it's known to be into the priority zone, therefore, no need of relocation . default 15%
static float DEFAULT_PRIORITY_ZONE_DEPRECIATION
          every time the array grow (actuallualy at every grow step), the area covered by the priority zone is depreciate.
static int DEFAULT_SIZE
          the initial size of the array
protected  int growStep
           
protected  float initialPriorityZone
           
protected  int initialSize
           
protected  float itemDepreciation
           
protected  float priorityDepreciation
           
protected  float priorityZone
           
protected  int size
          real number of slot actually used
 
Constructor Summary
PriorityList()
          Create a new List, with default values
PriorityList(int initialSize, int growStep, float priorityZone, float priorityDepreciation, float itemDepreciation)
          Create a new list
 
Method Summary
 boolean add(Entry e)
          add new entry to the list.
 boolean add(java.lang.String key)
          add an Entry where key == obj convenience method same as add(new Entry(key,key))
 boolean addAll(java.util.Collection<? extends Entry> c)
          add all Entry from c.
 void clear()
          erase all data from the list
 boolean contains(java.lang.Object o)
          return true if the list contain the element o
 boolean containsAll(java.util.Collection<?> c)
          method inherit from Collection.
 Entry find(java.lang.Comparable<Entry> comparable)
          Find en entry using a comparator.
 Entry find(Entry e)
          Find en entry using an Entry object. check is done against both hashkey, which only use their key.
 Entry find(java.lang.String key)
          Find entry by key.
 int findPosition(Entry o)
          find position of an entry.
 int findPosition(java.lang.String key)
          find position of an entry.
 boolean isEmpty()
          return true if the list is empty
 java.util.Iterator<Entry> iterator()
          return a new iterator on the list's elements
 boolean remove(java.lang.Object o)
          Remove entry using it's object as source.
 boolean removeAll(java.util.Collection<?> c)
          method inherit from Collection.
 boolean removeByKey(java.lang.String key)
          remove an entry from the list using it's key
 boolean retainAll(java.util.Collection<?> c)
          method inherit from Collection.
 int size()
          return the size of the list.
 java.lang.Object[] toArray()
           
<T> T[]
toArray(T[] a)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface java.util.Collection
equals, hashCode
 

Field Detail

DEFAULT_SIZE

public static final int DEFAULT_SIZE
the initial size of the array

See Also:
Constant Field Values

DEFAULT_GROW_STEP

public static final int DEFAULT_GROW_STEP
Default growing step for the internal array when adding new element

See Also:
Constant Field Values

DEFAULT_PRIORITY_ZONE

public static final float DEFAULT_PRIORITY_ZONE
if a matching glob is found into this percent of the array, it's known to be into the priority zone, therefore, no need of relocation . default 15%

See Also:
Constant Field Values

DEFAULT_PRIORITY_ZONE_DEPRECIATION

public static final float DEFAULT_PRIORITY_ZONE_DEPRECIATION
every time the array grow (actuallualy at every grow step), the area covered by the priority zone is depreciate. That mean every time the array grown the priority zone too, but in a lower percentage. This is done in order to keep the priority zone short value from 0.0f* to 1.0f (no priorityDepreciation) Nota : min value for priorityDepreciation depend of the initial size of the array and the increase. A minimal value must be maintained in order to avoid a thrinking of the priority zone ! (initial/(initial+increase)

See Also:
Constant Field Values

DEFAULT_ITEM_RELOCATION_DEPRECIATION

public static final float DEFAULT_ITEM_RELOCATION_DEPRECIATION
when a match is found outside the priority zone, the item must be relocated up. 1.0f mean directly up to the top, 0.0f mean no relocation at all !

See Also:
Constant Field Values

array

protected Entry[] array
internal array of data, ordered : first = most used


initialSize

protected final int initialSize

initialPriorityZone

protected final float initialPriorityZone

growStep

protected final int growStep

priorityDepreciation

protected final float priorityDepreciation

itemDepreciation

protected final float itemDepreciation

priorityZone

protected float priorityZone

size

protected int size
real number of slot actually used

Constructor Detail

PriorityList

public PriorityList()
Create a new List, with default values


PriorityList

public PriorityList(int initialSize,
                    int growStep,
                    float priorityZone,
                    float priorityDepreciation,
                    float itemDepreciation)
             throws java.lang.IllegalArgumentException
Create a new list

Parameters:
initialSize - : initial size of the buffer, before it grows automatically of growStep
growStep - : Step the buffer must increase each time
priorityZone -
priorityDepreciation -
itemDepreciation -
Throws:
java.lang.IllegalArgumentException
Method Detail

find

public Entry find(java.lang.Comparable<Entry> comparable)
Find en entry using a comparator. comparaison stop when "comparable" return 0, priority for the entry increase, and it's returned

Parameters:
comparable -
Returns:
the entry matching, or null if not found

find

public Entry find(java.lang.String key)
Find entry by key.

Returns:
entry, or null if not found

find

public Entry find(Entry e)
Find en entry using an Entry object. check is done against both hashkey, which only use their key. If you do not have an Entry object, you should use find(String key) instead


findPosition

public int findPosition(java.lang.String key)
find position of an entry. this peration doesn't alter the state of the list. note this can take up to list.length operation to return

Parameters:
key -
Returns:
index of entry or the list, or -1 if not found

findPosition

public int findPosition(Entry o)
find position of an entry. this peration doesn't alter the state of the list. note this can take up to list.length operation to return

Parameters:
o -
Returns:
index of entry or the list, or -1 if not found

size

public int size()
return the size of the list.

Specified by:
size in interface java.util.Collection<Entry>
Returns:
number of element in the list

isEmpty

public boolean isEmpty()
return true if the list is empty

Specified by:
isEmpty in interface java.util.Collection<Entry>
Returns:

contains

public boolean contains(java.lang.Object o)
return true if the list contain the element o

Specified by:
contains in interface java.util.Collection<Entry>
Parameters:
o -
Returns:

iterator

public java.util.Iterator<Entry> iterator()
return a new iterator on the list's elements

Specified by:
iterator in interface java.lang.Iterable<Entry>
Specified by:
iterator in interface java.util.Collection<Entry>
Returns:
See Also:
PriorityListIterator

toArray

public java.lang.Object[] toArray()
Specified by:
toArray in interface java.util.Collection<Entry>

toArray

public <T> T[] toArray(T[] a)
Specified by:
toArray in interface java.util.Collection<Entry>

add

public boolean add(Entry e)
add new entry to the list. If en entry already exist with this key, do nothing

Specified by:
add in interface java.util.Collection<Entry>
Parameters:
e -
Returns:
true if entry added, false else (likely already exist)

add

public boolean add(java.lang.String key)
add an Entry where key == obj convenience method same as add(new Entry(key,key))

Parameters:
key -
Returns:

remove

public boolean remove(java.lang.Object o)
Remove entry using it's object as source. Note the Object equal method is used inherit from Collection, you should use the removeByKey method instead

Specified by:
remove in interface java.util.Collection<Entry>
Parameters:
o -
Returns:

removeByKey

public boolean removeByKey(java.lang.String key)
remove an entry from the list using it's key

Parameters:
key -
Returns:
true if an Entry has been removed, false else

containsAll

public boolean containsAll(java.util.Collection<?> c)
method inherit from Collection. Not supported

Specified by:
containsAll in interface java.util.Collection<Entry>
Parameters:
c -
Returns:

addAll

public boolean addAll(java.util.Collection<? extends Entry> c)
add all Entry from c. if an entry already exist (with this key) it's discarded

Specified by:
addAll in interface java.util.Collection<Entry>
Parameters:
c -
Returns:
allways return true

removeAll

public boolean removeAll(java.util.Collection<?> c)
method inherit from Collection. Not supported

Specified by:
removeAll in interface java.util.Collection<Entry>
Parameters:
c -
Returns:

retainAll

public boolean retainAll(java.util.Collection<?> c)
method inherit from Collection. Not supported

Specified by:
retainAll in interface java.util.Collection<Entry>
Parameters:
c -
Returns:

clear

public void clear()
erase all data from the list

Specified by:
clear in interface java.util.Collection<Entry>