gishur.core
Class ListView

java.lang.Object
  |
  +--gishur.core.ListView

public class ListView
extends java.lang.Object

A ListView object permits (restricted) read access to a list. If a method, for example, has to receive any sort of list structure as input, the exact type of the structure must be known if ListView is not used, because BasicList does not allow any access to its data.
If a structure overrides the method BasicList.getListView() and returns a ListView object, read access to that structure can be granted.
ListView can determine different restrictions to the read access.
A properly functioning ListView object can only be created from the structure, belonging to the ListView - if it implements BasicList.getListView() correctly. ListView performs requests to the structure using the Owner interface.
The read access functions correspond mainly to the functions of SimpleList. If the underlying structure has restricted a function, ListView generates a ListException, when this function is accessed; a ListException is also thrown when trying an illegal instanciation.

Version:
1.0
Author:
Thomas Wolf
See Also:
BasicList, SimpleList

Field Summary
static int ALLOW_COMPARITORS
          Permits the use of comparitor objects for searching etc.
static int ALLOW_CONVERSIONS
          Permits copying of selected data to other structures
static int ALLOW_FIND
          Permits search for certain objects (dependant on SHOW_KEYS etc.)
static int ALLOW_NAVIGATION
          Permits complete navigation: ALLOW_NEXTPREV | ALLOW_STATISTICS | SHOW_FIRST | SHOW_LAST | SHOW_ITEMS
static int ALLOW_NEXTPREV
          Permits navigation between the list elements
static int ALLOW_STATISTICS
          Permits access to 'statistics' likethe number of objects contained in the structure
static int FULL_READ_ACCESS
          Full read access
static int LISTVIEW_ACCESS
          Constant for access to the BasicList object
static int NO_ACCESS
          No access at all
static int SHOW_FIRST
          Access to the first ListItem
static int SHOW_ITEMS
          Access to the ListItems
static int SHOW_KEYS
          Access to the keys
static int SHOW_LAST
          Access to the last ListItem
static int SHOW_VALUES
          Access to the values
 
Constructor Summary
ListView(BasicList L, int accessmode)
          Constructor.
 
Method Summary
 ListItem at(int index)
          Returns the ListItem at the index index.
 boolean checkAccess(int access)
          Returns true, if all the rights contained within access are permitted for this ListView object, otherwise this method returns false.
 boolean contains(ListItem item)
          Returns true, if the ListItem item is contained in the list.
 boolean contains(java.lang.Object object)
          Returns true, if the object object is contained in the list.
 java.lang.Object[] convertKeysToArray()
          Inserts the keys of the ListItems into an array.
 java.lang.Object[] convertValuesToArray()
          Inserts the values of the ListItems into an array.
 ListItem cyclicRelative(ListItem base, int count)
          Returns the ListItem, which is count steps away from base considering the list as cyclic list (or null, if base does not belong to the list).
 java.lang.Object cyclicRelativeValue(ListItem base, int count)
          Returns the value of the ListItem, which is count steps away from base considering the list as cyclic list (or null, if base does not belong to the list).
 boolean empty()
          Returns true, if the list is empty
required access: ALLOW_STATISTICS
 ListItem find(ListItem item)
          Searches for the ListItem item and returns it, if it was found, otherwise null is returned.
 ListItem find(java.lang.Object O)
          Returns the ListItem containing the object O, i.e. for which equals(O) returns true.
 ListItem find(java.lang.Object O, ListItem start)
          Returns the first ListItem after start containing the object O, i.e. for which equals(O) returns true.
 ListItem findBigger(java.lang.Object key, Comparitor comparitor)
          Searches the list for the smallest ListItem, which is bigger than key, using the comparitor comparitor.
 ListItem findBigger(java.lang.Object key, Comparitor comparitor, ListItem start)
          Searches the list for the smallest ListItem, which is bigger than key, using the comparitor comparitor.
 ListItem findClass(java.lang.Class C)
          Returns the first ListItem containing an object of the class C.
 ListItem findClass(java.lang.Class C, ListItem start)
          Returns the first ListItem after start containing an object of the class C.
 ListItem findClass(java.lang.Class C, ListItem start, int i)
          Returns the ith ListItem after start containing an object of the class C.
 ListItem findSmaller(java.lang.Object key, Comparitor comparitor)
          Searches the list for the biggest ListItem, which is smaller than key, using the comparitor comparitor.
 ListItem findSmaller(java.lang.Object key, Comparitor comparitor, ListItem start)
          Searches the list for the biggest ListItem, which is smaller than key, using the comparitor comparitor.
 ListItem first()
          Returns the first ListItem of the list.
 java.lang.Object firstKey()
          Returns the first key stored within the list.
 java.lang.Object firstValue()
          Returns the first value stored within the list.
 int getAccessMode()
          Returns the access mode constant of the ListView.
 int getDistance(ListItem i, ListItem j)
          Returns the distance of the two ListItems i und j within the list.
 int getIndex(ListItem i)
          Calculates the index of the Listitem i within the list, counting from the first element.
 java.lang.Object getKeyAt(int index)
          Returns the key stored in the ListItem at the index index.
 java.lang.Object getValueAt(int index)
          Returns the value stored in the ListItem at the index index.
 java.lang.Object key(ListItem item)
          Returns the key of the ListItem item.
 java.util.Enumeration keys()
          Returns an enomerator object, that enumerates all the keys of the list elements.
 ListItem last()
          Returns the last ListItem of the list.
 java.lang.Object lastKey()
          Returns the last key stored within the list.
 java.lang.Object lastValue()
          Returns the last value stored within the list.
 int length()
          Returns the number of elements stored within the list.
 ListItem max(Comparitor comparitor)
          Searches for the biggest ListItem according to the order defined by the comparitor comparitor
required access: SHOW_ITEMS and SHOW_KEYS and ALLOW_FIND and ALLOW_COMPARITORS
 ListItem min(Comparitor comparitor)
          Searches for the smallest ListItem according to the order defined by the comparitor comparitor
required access: SHOW_ITEMS and SHOW_KEYS and ALLOW_FIND and ALLOW_COMPARITORS
 ListItem next(ListItem i)
          Returns the next ListItem after i in the list.
 ListItem next(ListItem base, int count)
          Returns the ListItem, which is count (count>0) steps away from base in forward direction (or null, if base does not belong to the list).
 BasicList owner()
          Returns the structure shown by ListView.
 ListItem prev(ListItem i)
          Returns the ListItem previous to i in the list.
 ListItem prev(ListItem base, int count)
          Returns the ListItem, which is count steps away from base in backward direction (or null, if base does not belong to the list).
 ListItem relative(ListItem base, int count)
          Returns the ListItem, which is count steps away from base (or null, if base does not belong to the list).
 java.lang.Object relativeValue(ListItem base, int count)
          Returns the value of the ListItem, which is count steps away from base (or null, if base does not belong to the list).
 java.lang.String toString()
          Overrides Object.toString().
 java.lang.Object value(ListItem item)
          Returns the value of the ListItem item.
 java.util.Enumeration values()
          Returns an enomerator object, that enumerates all the values of the list elements.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

LISTVIEW_ACCESS

public static final int LISTVIEW_ACCESS
Constant for access to the BasicList object

NO_ACCESS

public static final int NO_ACCESS
No access at all

FULL_READ_ACCESS

public static final int FULL_READ_ACCESS
Full read access

SHOW_KEYS

public static final int SHOW_KEYS
Access to the keys

SHOW_VALUES

public static final int SHOW_VALUES
Access to the values

SHOW_ITEMS

public static final int SHOW_ITEMS
Access to the ListItems

SHOW_FIRST

public static final int SHOW_FIRST
Access to the first ListItem

SHOW_LAST

public static final int SHOW_LAST
Access to the last ListItem

ALLOW_FIND

public static final int ALLOW_FIND
Permits search for certain objects (dependant on SHOW_KEYS etc.)

ALLOW_STATISTICS

public static final int ALLOW_STATISTICS
Permits access to 'statistics' likethe number of objects contained in the structure

ALLOW_NEXTPREV

public static final int ALLOW_NEXTPREV
Permits navigation between the list elements

ALLOW_COMPARITORS

public static final int ALLOW_COMPARITORS
Permits the use of comparitor objects for searching etc.

ALLOW_CONVERSIONS

public static final int ALLOW_CONVERSIONS
Permits copying of selected data to other structures

ALLOW_NAVIGATION

public static final int ALLOW_NAVIGATION
Permits complete navigation: ALLOW_NEXTPREV | ALLOW_STATISTICS | SHOW_FIRST | SHOW_LAST | SHOW_ITEMS
Constructor Detail

ListView

public ListView(BasicList L,
                int accessmode)
Constructor. Creates a ListView object for the list L with the access mode accessmode. The list object is asked for permission, using BasicList.requestAccess(int, java.lang.Object, java.lang.Object). The access type is the constant LISTVIEW_ACCESS. If access is not granted, a ListException is thrown.
Method Detail

owner

public final BasicList owner()
Returns the structure shown by ListView.
Returns:
related BasicList object

getAccessMode

public final int getAccessMode()
Returns the access mode constant of the ListView.
Returns:
access mode

checkAccess

public final boolean checkAccess(int access)
Returns true, if all the rights contained within access are permitted for this ListView object, otherwise this method returns false.
Parameters:
access - rights to be checked for
Returns:
true, if permitted, else false.

toString

public java.lang.String toString()
Overrides Object.toString().
Overrides:
toString in class java.lang.Object
See Also:
Object.toString()

length

public int length()
Returns the number of elements stored within the list.
required access: ALLOW_STATISTICS
Returns:
number of ListItems

empty

public boolean empty()
Returns true, if the list is empty
required access: ALLOW_STATISTICS
Returns:
true, if the list is empty

first

public ListItem first()
Returns the first ListItem of the list.
required access: SHOW_FIRST and SHOW_ITEMS
Returns:
first ListItem of the list

last

public ListItem last()
Returns the last ListItem of the list.
required access: SHOW_LAST and SHOW_ITEMS
Returns:
last ListItem of the list

firstKey

public java.lang.Object firstKey()
Returns the first key stored within the list. If the list is empty, a ListException is generated.
required access: SHOW_FIRST and SHOW_KEYS
Returns:
first key

lastKey

public java.lang.Object lastKey()
Returns the last key stored within the list. If the list is empty, a ListException is generated.
required access: SHOW_LAST and SHOW_KEYS
Returns:
last key

firstValue

public java.lang.Object firstValue()
Returns the first value stored within the list. If the list is empty, a ListException is generated.
required access: SHOW_FIRST and SHOW_VALUES
Returns:
first value

lastValue

public java.lang.Object lastValue()
Returns the last value stored within the list. If the list is empty, a ListException is generated.
required access: SHOW_LAST and SHOW_VALUES
Returns:
last value

contains

public boolean contains(ListItem item)
Returns true, if the ListItem item is contained in the list. The test performs in constant runtime.
required access: SHOW_ITEMS and ALLOW_FIND
Parameters:
item - ListItem to be tested
Returns:
true, if item is contained in the list.

contains

public boolean contains(java.lang.Object object)
Returns true, if the object object is contained in the list.
required access: SHOW_KEYS and ALLOW_FIND
Parameters:
object - to be searched for
Returns:
true, if object is contained in the list.

getIndex

public int getIndex(ListItem i)
Calculates the index of the Listitem i within the list, counting from the first element. If i is not contained in the list, -1 is returned.
required access: SHOW_ITEMS and ALLOW_NEXTPREV
Parameters:
i - ListItem, the index of which will be calculated

getDistance

public int getDistance(ListItem i,
                       ListItem j)
Returns the distance of the two ListItems i und j within the list. A positive return value indicates, that j can be reached from i by searching forward, a negative value means, that j can be reached from i by searching backward. If i or j is not contained in the list or if they are unreachable from each other for any other reason, Integer.MAX_VALUE is returned.
required access: SHOW_ITEMS and ALLOW_NEXTPREV
Parameters:
i,j - ListItems, the distance of which will be calculated.

key

public java.lang.Object key(ListItem item)
Returns the key of the ListItem item. If item is not contained within the list a ListException is generated.
required access: SHOW_ITEMS and SHOW_KEYS and ALLOW_FIND
Returns:
key stored in item

value

public java.lang.Object value(ListItem item)
Returns the value of the ListItem item. If item is not contained within the list a ListException is generated.
required access: SHOW_ITEMS and SHOW_KEYS and ALLOW_FIND
Returns:
value stored in item

next

public ListItem next(ListItem i)
Returns the next ListItem after i in the list. If i==null, the first item of the list is returned. If i is not contained in the list, the return value is null.
required access: SHOW_ITEMS and ALLOW_NEXTPREV
Parameters:
i - ListItem from the list
Returns:
next ListItem after i

next

public ListItem next(ListItem base,
                     int count)
Returns the ListItem, which is count (count>0) steps away from base in forward direction (or null, if base does not belong to the list). If base==null, base is set to the first list element.
required access: SHOW_ITEMS and ALLOW_NEXTPREV
Parameters:
base - ListItem to start with
count - (positive) distance
Returns:
ListItem count steps in forward direction from base

relative

public ListItem relative(ListItem base,
                         int count)
Returns the ListItem, which is count steps away from base (or null, if base does not belong to the list). If base==null, base is set to the first list element.
required access: SHOW_ITEMS and ALLOW_NEXTPREV
Parameters:
base - ListItem to start with
count - distance
Returns:
ListItem in distance count from base

relativeValue

public java.lang.Object relativeValue(ListItem base,
                                      int count)
Returns the value of the ListItem, which is count steps away from base (or null, if base does not belong to the list). If base==null, base is set to the first list element.
required access: SHOW_VALUES and ALLOW_NEXTPREV

cyclicRelative

public ListItem cyclicRelative(ListItem base,
                               int count)
Returns the ListItem, which is count steps away from base considering the list as cyclic list (or null, if base does not belong to the list). If base==null, base is set to the first list element.
required access: SHOW_ITEMS and ALLOW_NEXTPREV

cyclicRelativeValue

public java.lang.Object cyclicRelativeValue(ListItem base,
                                            int count)
Returns the value of the ListItem, which is count steps away from base considering the list as cyclic list (or null, if base does not belong to the list). If base==null, base is set to the first list element.
required access: SHOW_VALUES and ALLOW_NEXTPREV

prev

public ListItem prev(ListItem base,
                     int count)
Returns the ListItem, which is count steps away from base in backward direction (or null, if base does not belong to the list). If base==null, base is set to the last list element.
required access: SHOW_ITEMS and ALLOW_NEXTPREV
Parameters:
base - ListItem to start with
count - (positive) distance
Returns:
ListItem count steps in backward direction from base

prev

public ListItem prev(ListItem i)
Returns the ListItem previous to i in the list. If i==null, the last item of the list is returned. If i is not contained in the list, the return value is null.
required access: SHOW_ITEMS and ALLOW_NEXTPREV
Parameters:
i - ListItem from the list
Returns:
ListItem previous to i

at

public ListItem at(int index)
Returns the ListItem at the index index.
required access: SHOW_ITEMS and ALLOW_NEXTPREV
Parameters:
index - index
Returns:
ListItem at index index

getValueAt

public java.lang.Object getValueAt(int index)
Returns the value stored in the ListItem at the index index.
required access: SHOW_VALUES and ALLOW_NEXTPREV
Parameters:
index - index
Returns:
value of the ListItem at index index

getKeyAt

public java.lang.Object getKeyAt(int index)
Returns the key stored in the ListItem at the index index.
required access: SHOW_KEYS and ALLOW_NEXTPREV
Parameters:
index - index
Returns:
key of the ListItem at index index

find

public ListItem find(ListItem item)
Searches for the ListItem item and returns it, if it was found, otherwise null is returned. The search runs in constant time. Sucht das ListItem item in der Liste und liefert es zurück, falls es
required access: SHOW_ITEMS and ALLOW_FIND
Parameters:
item - ListItem to be searched for
Returns:
item, if found, else null

find

public ListItem find(java.lang.Object O)
Returns the ListItem containing the object O, i.e. for which equals(O) returns true. The search runs in linear time.
required access: SHOW_ITEMS and SHOW_KEYS and ALLOW_FIND
Parameters:
O - object to be searched for
Returns:
the found ListItem or null

find

public ListItem find(java.lang.Object O,
                     ListItem start)
Returns the first ListItem after start containing the object O, i.e. for which equals(O) returns true. If srart==null, the search begins with the first list element. The search runs in linear time.
required access: SHOW_ITEMS and SHOW_KEYS and ALLOW_FIND
Parameters:
O - object to be searched for
start - ListItem the search begins with.
Returns:
the found ListItem or null

findClass

public ListItem findClass(java.lang.Class C)
Returns the first ListItem containing an object of the class C. The search runs in linear time.
required access: SHOW_ITEMS and SHOW_KEYS and ALLOW_FIND
Parameters:
C - object class to be searched for
Returns:
the found ListItem or null

findClass

public ListItem findClass(java.lang.Class C,
                          ListItem start)
Returns the first ListItem after start containing an object of the class C. If srart==null, the search begins with the first list element. The search runs in linear time.
required access: SHOW_ITEMS and SHOW_KEYS and ALLOW_FIND
Parameters:
C - object class to be searched for
start - ListItem the search begins with.
Returns:
the found ListItem or null

findClass

public ListItem findClass(java.lang.Class C,
                          ListItem start,
                          int i)
Returns the ith ListItem after start containing an object of the class C. If srart==null, the search begins with the first list element. The search runs in linear time.
required access: SHOW_ITEMS and SHOW_KEYS and ALLOW_FIND
Parameters:
C - object class to be searched for
start - ListItem the search begins with.
i - number of occurences
Returns:
the found ListItem or null

findBigger

public ListItem findBigger(java.lang.Object key,
                           Comparitor comparitor)
Searches the list for the smallest ListItem, which is bigger than key, using the comparitor comparitor. If key is a ListItem the ListItems are compared directly, otherwise the keys are compared.
If key==null, this method is equivalent to max(gishur.core.Comparitor)(comparitor).
If comparitor==null, a default comparitor is used.
required access: SHOW_ITEMS and SHOW_KEYS and ALLOW_FIND and ALLOW_COMPARITORS
Parameters:
key - object to be compared to
comparitor - comparitor object
Returns:
smallest ListItem, which is bigger than (or equal) key
See Also:
Comparitor

findBigger

public ListItem findBigger(java.lang.Object key,
                           Comparitor comparitor,
                           ListItem start)
Searches the list for the smallest ListItem, which is bigger than key, using the comparitor comparitor. The search begins with start.
required access: SHOW_ITEMS and SHOW_KEYS and ALLOW_FIND and ALLOW_COMPARITORS
Parameters:
key - object to be compared to
comparitor - comparitor object
Returns:
smallest ListItem after start, which is bigger than (or equal) key
See Also:
findBigger(Object, Comparitor)

findSmaller

public ListItem findSmaller(java.lang.Object key,
                            Comparitor comparitor)
Searches the list for the biggest ListItem, which is smaller than key, using the comparitor comparitor. If key is a ListItem the ListItems are compared directly, otherwise the keys are compared.
If key==null, this method is equivalent to min(gishur.core.Comparitor)(comparitor).
If comparitor==null, a default comparitor is used.
required access: SHOW_ITEMS and SHOW_KEYS and ALLOW_FIND and ALLOW_COMPARITORS
Parameters:
key - object to be compared to
comparitor - comparitor object
Returns:
biggest ListItem, which is smaller than (or equal) key
See Also:
Comparitor

findSmaller

public ListItem findSmaller(java.lang.Object key,
                            Comparitor comparitor,
                            ListItem start)
Searches the list for the biggest ListItem, which is smaller than key, using the comparitor comparitor. The search begins with start.
required access: SHOW_ITEMS and SHOW_KEYS and ALLOW_FIND and ALLOW_COMPARITORS
Parameters:
key - object to be compared to
comparitor - comparitor object
Returns:
biggest ListItem after start, which is smaller than (or equal) key
See Also:
findSmaller(Object, Comparitor)

min

public ListItem min(Comparitor comparitor)
Searches for the smallest ListItem according to the order defined by the comparitor comparitor
required access: SHOW_ITEMS and SHOW_KEYS and ALLOW_FIND and ALLOW_COMPARITORS
Parameters:
comparitor - comparitor object
Returns:
the smallest ListItem in the list

max

public ListItem max(Comparitor comparitor)
Searches for the biggest ListItem according to the order defined by the comparitor comparitor
required access: SHOW_ITEMS and SHOW_KEYS and ALLOW_FIND and ALLOW_COMPARITORS
Parameters:
comparitor - comparitor object
Returns:
the biggest ListItem in the list

convertKeysToArray

public java.lang.Object[] convertKeysToArray()
Inserts the keys of the ListItems into an array. If SimpleList was created with the default insert methods, then convertKeysToArray and convertValuesToArray both return the same array.
required access: SHOW_KEYS and ALLOW_CONVERSIONS
Returns:
object array
See Also:
convertValuesToArray()

convertValuesToArray

public java.lang.Object[] convertValuesToArray()
Inserts the values of the ListItems into an array. If SimpleList was created with the default insert methods, then convertKeysToArray and convertValuesToArray both return the same array.
required access: SHOW_VALUES and ALLOW_CONVERSIONS
Returns:
object array
See Also:
convertKeysToArray()

keys

public java.util.Enumeration keys()
Returns an enomerator object, that enumerates all the keys of the list elements. If SimpleList was created with the default insert methods, then keys() and values() both return the same enumeration object.
required access: SHOW_KEYS and ALLOW_CONVERSIONS
Returns:
enumeration with keys
See Also:
values()

values

public java.util.Enumeration values()
Returns an enomerator object, that enumerates all the values of the list elements. If SimpleList was created with the default insert methods, then keys() and values() both return the same enumeration object.
required access: SHOW_VALUES and ALLOW_CONVERSIONS
Returns:
enumeration with values
See Also:
keys()