net.algart.model3d.common.movement.model
Interface ItemSet

All Known Implementing Classes:

GridItemSet, SimpleItemSet

public interface ItemSet

Simple collection (list) of indexed non-null items. It is a simplified analog of ArrayList<Item>, allowing to perform only the basic operations (getting, setting, adding, removing items), but also offering an additional operation — finding all "neighbours", i.e. items which can interact with this one: getPossibleInteractingIndexes(int[], int) method. This operation is important for quick implementing the physical model, because we need to calculate interaction forces between every item and all other items at the any step of integrating differential equations of motion. So, it is very important to be able to quickly find all items, which are at enough short distance from the given one and can interact with it, by using "interaction radius" concept. This task should be solved as quick as possible, because, in sets of large number of items, usually most of other items do not affect to this one at all — only "nearest neighbours" can affect it.

This package offers 2 implementations of this interface:

• SimpleItemSet,
• GridItemSet.

The first class provides the simplest implementation of getPossibleInteractingIndexes(int[], int) method, which just searches all other items and checks whether they are near enough. It requires O(N) operations, N=size() is the total number of items. The second class uses a grid algorithm, which can provide much better performance, up to O(1) operations, if the items are distributed uniformly enough in some parallelepiped and most of them implement HavingInteractionRadius interface.

Both classes store the items in a standard java.util.List. But an instance of this list is created by ItemListBuilder interface, which can be passed to constructors. So, it you prefer some special ways for storing items, for example, in a database or in AlgART arrays, you can use the custom implementation of java.util.List interface, which provides the necessary functionality.

Note: this interface does not allow to store more than Integer.MAX_VALUE=2³¹−1 items.

Note: this interface does not allow to store null items.

Implementations of this interface are usually not thread-safe, but are thread-compatible and can be synchronized manually if multithread access is necessary. Also there is a guarantee that different threads can simultaneously call the following methods without synchronization:

• size(),
• get(int),
• set(int, Item),
• getPossibleInteractingIndexes(int[], int),

if each thread work with its own set of indexes, i.e. the different threads never access to the same item index. It allows multithreading optimization of processing on multiprocessing systems. All other methods require synchronization while multithreading.

AlgART Laboratory 2010

Since:

JDK 1.5

Version:

1.0

Author:

Daniel Alievsky

size

int size()

Returns the number of items in this item list.

Returns:

the number of items in this item list.

get

Item get(int itemIndex)

Returns the item with the given index (from 0 to size()−1).

Parameters:

itemIndex - index of the item to get.

Returns:

the item with the given index.

Throws:

java.lang.IndexOutOfBoundsException - if the index is out of range (index < 0 || index >= size()).

set

void set(int itemIndex,
         Item newItem)

Replaces the item with the given index (from 0 to size()−1) with the specified new one.

Parameters:

itemIndex - index of the item to replace.

newItem - new item to be stored at the specified index.

Throws:

java.lang.NullPointerException - if newItem is null.

java.lang.IndexOutOfBoundsException - if the index is out of range (index < 0 || index >= size()).

add

void add(Item newItem)

Appends the specified item to the end of this item list. The added item must not be null.

Parameters:

newItem - new item to be added to this item list.

Throws:

java.lang.NullPointerException - if newItem is null.

getAll

java.util.List<Item> getAll()

Returns the list of all items of this item list. The order of items in the resulting list is identical to the order in this collection: result.get(k)==thisInstance.get(k).

The returned list can be either newly created list, or an immutable view (Collections.unmodifiableList) of the internal collection, stored by this object. In any case, you cannot modify the set of items via the result of this method. But the returned list contains references to items, not their clones; so changes in the returned items (via setXxx methods) will be reflected in this collection.

Returns:

newly created list of all items.

getAll

<T extends Item> java.util.List<T> getAll(java.lang.Class<? extends T> requiredClass)

Returns newly created modifiable list of all items of this item list, implementing the specified interface (or extending the specified class). Usually the returned list is ArrayList.

The returned list is newly created, so changes in it do not affect to this object. But the returned list contains references to items, not their clones; so changes in the returned items (via setXxx methods) will be reflected in this collection.

Parameters:

requiredClass - the class of all returned items.

Returns:

newly created list of all items, implementing the specified interface (or extending class).

addAll

void addAll(java.util.Collection<? extends Item> newItems)

Appends all items from the specified collection to the end of this item list, in the order that they are returned by the specified collection's iterator. The added items must not be null.

Note: if some of added items are null, then part of them can be still added before throwing NullPointerException. In other words, this method can be non-atomic regarding this failure.

Parameters:

newItems - new items to be added to this item list.

Throws:

java.lang.NullPointerException - if newItems is null or if some of added items is null.

removeItems

void removeItems(int fromIndex,
                 int toIndex)

Removes all items with indexes fromIndex<=k<toIndex and shifts any subsequent items to the left (subtracts toIndex-fromIndex from their indexes).

Parameters:

fromIndex - starting index of removed items (inclusive).

toIndex - ending index of removed items (exclusive).

Throws:

java.lang.IndexOutOfBoundsException - for an illegal endpoint index value (fromIndex < 0 || toIndex > size() || fromIndex > toIndex).

getPossibleInteractingIndexes

int getPossibleInteractingIndexes(int[] result,
                                  int itemIndex)

Returns, in first K elements of result array, the indexes of all items, that can be interact with the item #itemIndex, according to HavingInteractionRadius.getMaxInteractionRadius() or, maybe, some analogous empiric rules. The number K of the found elements is returned in the result. The size of result array must be enough; the simplest way to guarantee it is to use an array of size() int elements.

This method may return indexes of some extra items, which really cannot interact with the given item. This method should be used for optimization only, namely, to reduce the number of calls of InteractionRule class.

Note: this method always returns the index itemIndex among the returned indexes. This method also always includes in the result the indexes of all items, which do not implement HavingInteractionRadius. At last, if the item #itemIndex does not implement HavingInteractionRadius, the result always contains all size() indexes 0,1,...,size()−1.

Note: if there is an extra space in result array, that is if result.length>K (K is the result of this method), then this method stores in result[K] element an additional debug information: the number of items, which were really checked while finding "neighbours". This value is always ≥K. This feature is used by in MovementIntegrator.getCounterOfCheckedNeighbours() method.

Parameters:

result - the indexes of "neighbours": items that can interact with the given item.

itemIndex - the index of the given item.

Returns:

the actual length K of the returned array: the required indexes are returned in the first K elements of the result.

Throws:

java.lang.NullPointerException - if result argument is null.

java.lang.IllegalStateException - if the length of result array is insufficient.

java.lang.IndexOutOfBoundsException - if the index is out of range (index < 0 || index >= size()).

preprocess

void preprocess()

Performs some preprocessing, which can optimize further getPossibleInteractingIndexes(int[], int) calls. Must be called after any changes in the item set, after which you want to use getPossibleInteractingIndexes(int[], int) method.

Usually, this method allocates and initialize some work memory, which can be used for optimization of getPossibleInteractingIndexes(int[], int) method. Of course, this method does not reallocate memory, if the same amount, that it needs now, was allocated while the previous call of this method.