net.sf.ivmaidns.storage
Class Storage

java.lang.Object
  extended by net.sf.ivmaidns.util.ObservedCore
      extended by net.sf.ivmaidns.storage.Storage
All Implemented Interfaces:
java.lang.Cloneable, MultiObservable, ReallyCloneable, Sortable, TrimToSizeable, Verifiable
Direct Known Subclasses:
FilterStorage, IntStorage, ObjectStorage

public abstract class Storage
extends ObservedCore
implements ReallyCloneable, Sortable

Root abstract class for storage of objects.

Version:
2.0
Author:
Ivan Maidanski

Constructor Summary
Storage()
           
 
Method Summary
 int add(java.lang.Object value, boolean unique)
          NOTE: If value == null then ArrayStoreException is thrown.
 int addAll(java.lang.Object[] array, int offset, int len, boolean unique)
          NOTE: If exception is thrown then nothing is changed.
 int addAll(Storage storage, int storagePrevLocation, boolean unique)
          NOTE: If unique is true and this storage has already contained value then it is skipped.
abstract  int childLocation(int parentLocation, boolean forward)
          NOTE: If parentLocation !
 void clear()
          NOTE: Must be synchronized outside.
 java.lang.Object clone()
          NOTE: Must be synchronized outside.
 boolean contains(java.lang.Object value)
          NOTE: value may be == null.
 int containsAll(java.lang.Object[] array, int offset, int len)
          NOTE: If exception is thrown then nothing is changed.
 int containsAll(Storage storage, int storagePrevLocation)
          NOTE: Result is either 0 or location of the first element in storage (after storagePrevLocation) at which value is not contained here.
 int containsCount(java.lang.Object value)
          NOTE: value may be == null.
abstract  int emptyLocation()
          NOTE: Result is an empty location (result > 0).
 boolean equals(java.lang.Object obj)
          NOTE: Storage state is not altered.
abstract  int findLessGreater(java.lang.Object value, boolean greater, int prevLocation, boolean forward)
          NOTE: If prevLocation !
abstract  java.lang.Object getAt(int location)
          NOTE: Result !
 boolean greaterThan(java.lang.Object obj)
          NOTE: The first found non-equal elements pair is compared through GComparator INSTANCE.
 boolean hasChildren(int parentLocation)
          NOTE: parentLocation may be == 0.
 int hashCode()
          NOTE: Storage state is not altered.
abstract  int insertAt(int prevLoc, int emptyLocation, java.lang.Object value)
          NOTE: If prevLoc !
 int insertAtAll(int prevLoc, java.lang.Object[] array, int offset, int len)
          NOTE: If exception is thrown then nothing is changed.
 int insertAtAll(int prevLoc, Storage storage, int storagePrevLocation)
          NOTE: Result is either 0 or location of the first element in storage (after storagePrevLocation) at which value insertion has failed here. storage and its elements are not modified.
 void integrityCheck()
          NOTE: Shallow check for integrity of this object.
abstract  boolean isValidAt(int location)
          NOTE: Result is true if and only if location is "valid" (only not "empty" locations may be "valid").
abstract  int locationOf(java.lang.Object value, int prevLocation, boolean forward)
          NOTE: If prevLocation !
protected abstract  void minimizeCapacity()
          NOTE: The effectiveness is linear.
 int nextLocation(int prevLocation, boolean forward)
          NOTE: prevLocation may be == 0.
protected  void notifyObservers(int prevLoc, int location, java.lang.Object oldValue)
          NOTE: This method must be called after any atomary changes committed (inside insertAt/setAt operations mainly).
 void notifyObservers(MultiObservable observed, java.lang.Object argument)
          NOTE: It is a dummy method which hides the same method in the superclass.
abstract  int parentLocation(int location)
          NOTE: If location is "empty" then IllegalArgumentException is thrown.
 int remove(java.lang.Object value)
          NOTE: value may be == null.
 int removeAll(java.lang.Object[] array, int offset, int len)
          NOTE: If exception is thrown then nothing is changed.
 int removeAll(Storage storage, int storagePrevLocation)
          NOTE: Result is either 0 (normally) or location of the first element in storage (after storagePrevLocation) at which value removal has failed here. storage and its elements are not modified.
 java.lang.Object removeAt(int location)
          NOTE: If 0 >= location then IllegalArgumentException is thrown.
abstract  java.lang.Object setAt(int location, java.lang.Object value)
          NOTE: If 0 >= location then IllegalArgumentException is thrown.
abstract  int siblingLocation(int location, boolean forward)
          NOTE: If location is "empty" then IllegalArgumentException is thrown.
 java.lang.Object[] toArray()
          NOTE: Result is exact instanceof Object[] with non-null elements.
 java.lang.String toInlineString(ToString converter)
          NOTE: To separate storage values ", " is used, to represent tree layout/hierarchy " {" and " }" are used. converter must be !
 java.lang.String toOutlineString(ToString converter)
          NOTE: To separate storage values "\n" is used, to represent tree layout/hierarchy "`", "|" and "-- " are used. converter must be !
 java.lang.String toString()
          NOTE: Result !
 void trimToSize()
          NOTE: Shallow "trim-to-size" is performed.
 
Methods inherited from class net.sf.ivmaidns.util.ObservedCore
addObserver, hasObservers, removeObserver
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Storage

public Storage()
Method Detail

trimToSize

public void trimToSize()
NOTE: Shallow "trim-to-size" is performed. Must be synchronized outside.

Specified by:
trimToSize in interface TrimToSizeable
Overrides:
trimToSize in class ObservedCore
See Also:
ObservedCore.addObserver(net.sf.ivmaidns.util.Notifiable), ObservedCore.removeObserver(net.sf.ivmaidns.util.Notifiable)

minimizeCapacity

protected abstract void minimizeCapacity()
NOTE: The effectiveness is linear. Locations are not re-ordered. If OutOfMemoryError is thrown then storage remains unchanged. Must be synchronized outside.


clear

public final void clear()
NOTE: Must be synchronized outside.


emptyLocation

public abstract int emptyLocation()
NOTE: Result is an empty location (result > 0). Storage state is not altered. The effectiveness is constant (typically). The order of empty locations is undefined. Requires no synchronization.


notifyObservers

protected final void notifyObservers(int prevLoc,
                                     int location,
                                     java.lang.Object oldValue)
NOTE: This method must be called after any atomary changes committed (inside insertAt/setAt operations mainly). If location > 0 then storage event is addition or modification (if oldValue != null) at location. Else if -location > 0 and oldValue != null then storage event is removal of oldValue after prevLoc (if 0 >= prevLoc then first child of -prevLoc is removed else next sibling of prevLoc is removed) at -location.


notifyObservers

public final void notifyObservers(MultiObservable observed,
                                  java.lang.Object argument)
NOTE: It is a dummy method which hides the same method in the superclass.

Overrides:
notifyObservers in class ObservedCore
Parameters:
observed - the observed object (may be null, but normally this).
argument - the argument (may be null), describing the occurred event.
See Also:
ObservedCore.addObserver(net.sf.ivmaidns.util.Notifiable)

insertAt

public abstract int insertAt(int prevLoc,
                             int emptyLocation,
                             java.lang.Object value)
                      throws java.lang.IllegalArgumentException,
                             java.lang.ArrayStoreException
NOTE: If prevLoc != 0 and (prevLoc > 0 ? prevLoc : -prevLoc) is an "empty" (including negative) location then IllegalArgumentException is thrown. If 0 > emptyLocation or emptyLocation is not an "empty" location then IllegalArgumentException is thrown. emptyLocation is the location of the inserted value unless emptyLocation == 0 (means any empty location). If value == null or insertion is impossible then ArrayStoreException is thrown. Enough capacity is ensured before any changes. New value is inserted as a first child node of -prevLoc (if 0 >= prevLoc) or as a next sibling node of prevLoc (if prevLoc > 0). Result is the location of the inserted value (result is a "valid" location if prevLoc == 0 or (prevLoc > 0 ? prevLoc : -prevLoc) is a "valid" location). Alters storage state. value itself is not modified. The effectiveness is constant (typically). Observers notification is performed. Must be synchronized outside. If exception is thrown then storage remains unchanged.

Throws:
java.lang.IllegalArgumentException
java.lang.ArrayStoreException

setAt

public abstract java.lang.Object setAt(int location,
                                       java.lang.Object value)
                                throws java.lang.IllegalArgumentException,
                                       java.lang.ArrayStoreException
NOTE: If 0 >= location then IllegalArgumentException is thrown. value may be == null (if accepted semantically), result (oldValue) may be == null. If operation is impossible (according to the storage semantics) then ArrayStoreException is thrown. Enough capacity is ensured before any changes. Alters storage state. value itself is not modified. The effectiveness is constant (typically) or logarithmic (or linear when deleting an inner tree node). Observers notification is performed. Must be synchronized outside. If exception is thrown then storage remains unchanged.

Throws:
java.lang.IllegalArgumentException
java.lang.ArrayStoreException

getAt

public abstract java.lang.Object getAt(int location)
NOTE: Result != null if and only if location is not "empty" (only positive locations may be not "empty"). Storage state is not altered. The effectiveness is constant. Requires no synchronization.


isValidAt

public abstract boolean isValidAt(int location)
NOTE: Result is true if and only if location is "valid" (only not "empty" locations may be "valid"). Storage state is not altered. The effectiveness is constant. Must be synchronized outside.


add

public final int add(java.lang.Object value,
                     boolean unique)
              throws java.lang.ArrayStoreException
NOTE: If value == null then ArrayStoreException is thrown. If unique is false or this storage has not contained the specified value yet then value is added to the storage. Anyway, its location is returned. Must be synchronized outside.

Throws:
java.lang.ArrayStoreException

remove

public final int remove(java.lang.Object value)
                 throws java.lang.ArrayStoreException
NOTE: value may be == null. Only first found value occurance is removed. If removal is denied then ArrayStoreException is thrown. Result is either 0 (not found) or an "empty" location of removed value. Must be synchronized outside.

Throws:
java.lang.ArrayStoreException

removeAt

public final java.lang.Object removeAt(int location)
                                throws java.lang.IllegalArgumentException,
                                       java.lang.ArrayStoreException
NOTE: If 0 >= location then IllegalArgumentException is thrown. If removal is denied then ArrayStoreException is thrown. Must be synchronized outside.

Throws:
java.lang.IllegalArgumentException
java.lang.ArrayStoreException

insertAtAll

public final int insertAtAll(int prevLoc,
                             java.lang.Object[] array,
                             int offset,
                             int len)
                      throws java.lang.NullPointerException,
                             java.lang.ArrayIndexOutOfBoundsException,
                             java.lang.IllegalArgumentException
NOTE: If exception is thrown then nothing is changed. Result is remainder of len (that is, result is the count of not processed values due to ArrayStoreException). array and its elements are not modified. Must be synchronized outside.

Throws:
java.lang.NullPointerException
java.lang.ArrayIndexOutOfBoundsException
java.lang.IllegalArgumentException

addAll

public final int addAll(java.lang.Object[] array,
                        int offset,
                        int len,
                        boolean unique)
                 throws java.lang.NullPointerException,
                        java.lang.ArrayIndexOutOfBoundsException
NOTE: If exception is thrown then nothing is changed. If unique is true and this storage has already contained value then it is skipped. Result is remainder of len (that is, result is the count of not processed values due to null or ArrayStoreException). array and its elements are not modified. Must be synchronized outside.

Throws:
java.lang.NullPointerException
java.lang.ArrayIndexOutOfBoundsException

removeAll

public final int removeAll(java.lang.Object[] array,
                           int offset,
                           int len)
                    throws java.lang.NullPointerException,
                           java.lang.ArrayIndexOutOfBoundsException
NOTE: If exception is thrown then nothing is changed. Result is remainder of len (that is, result is the count of not processed values due to ArrayStoreException). array and its elements are not modified. Must be synchronized outside.

Throws:
java.lang.NullPointerException
java.lang.ArrayIndexOutOfBoundsException

containsAll

public final int containsAll(java.lang.Object[] array,
                             int offset,
                             int len)
                      throws java.lang.NullPointerException,
                             java.lang.ArrayIndexOutOfBoundsException
NOTE: If exception is thrown then nothing is changed. Result is remainder of len (that is, result is the count of not processed values due to null or not found). array and its elements are not modified. Must be synchronized outside.

Throws:
java.lang.NullPointerException
java.lang.ArrayIndexOutOfBoundsException

insertAtAll

public final int insertAtAll(int prevLoc,
                             Storage storage,
                             int storagePrevLocation)
                      throws java.lang.NullPointerException,
                             java.lang.IllegalArgumentException
NOTE: Result is either 0 or location of the first element in storage (after storagePrevLocation) at which value insertion has failed here. storage and its elements are not modified. Must be synchronized outside, storage must be synchronized too.

Throws:
java.lang.NullPointerException
java.lang.IllegalArgumentException

addAll

public final int addAll(Storage storage,
                        int storagePrevLocation,
                        boolean unique)
                 throws java.lang.NullPointerException,
                        java.lang.IllegalArgumentException
NOTE: If unique is true and this storage has already contained value then it is skipped. Result is either 0 or location of the first element in storage (after storagePrevLocation) at which value addition has failed here. storage and its elements are not modified. Must be synchronized outside, storage must be synchronized too.

Throws:
java.lang.NullPointerException
java.lang.IllegalArgumentException

removeAll

public final int removeAll(Storage storage,
                           int storagePrevLocation)
                    throws java.lang.NullPointerException,
                           java.lang.IllegalArgumentException
NOTE: Result is either 0 (normally) or location of the first element in storage (after storagePrevLocation) at which value removal has failed here. storage and its elements are not modified. Must be synchronized outside, storage must be synchronized too.

Throws:
java.lang.NullPointerException
java.lang.IllegalArgumentException

containsAll

public final int containsAll(Storage storage,
                             int storagePrevLocation)
                      throws java.lang.NullPointerException,
                             java.lang.IllegalArgumentException
NOTE: Result is either 0 or location of the first element in storage (after storagePrevLocation) at which value is not contained here. Must be synchronized outside, storage must be synchronized too.

Throws:
java.lang.NullPointerException
java.lang.IllegalArgumentException

childLocation

public abstract int childLocation(int parentLocation,
                                  boolean forward)
                           throws java.lang.IllegalArgumentException
NOTE: If parentLocation != 0 and parentLocation is "empty" then IllegalArgumentException is thrown. Result is either 0 (not found) or a found (not "empty") location. If (parentLocation == 0 or is "valid") and result != 0 then result is a "valid" location. Storage state is not altered. The effectiveness is constant. Must be synchronized outside.

Throws:
java.lang.IllegalArgumentException

siblingLocation

public abstract int siblingLocation(int location,
                                    boolean forward)
                             throws java.lang.IllegalArgumentException
NOTE: If location is "empty" then IllegalArgumentException is thrown. Result is either 0 (not found) or a found (not "empty") location. If location is "valid" and result != 0 then result is a "valid" location. Storage state is not altered. The effectiveness is constant (typically). Must be synchronized outside.

Throws:
java.lang.IllegalArgumentException

parentLocation

public abstract int parentLocation(int location)
                            throws java.lang.IllegalArgumentException
NOTE: If location is "empty" then IllegalArgumentException is thrown. Result is either 0 (not found) or a found (not "empty") location. If location is "valid" and result != 0 then result is a "valid" location. Storage state is not altered. The effectiveness is constant. Must be synchronized outside.

Throws:
java.lang.IllegalArgumentException

hasChildren

public final boolean hasChildren(int parentLocation)
                          throws java.lang.IllegalArgumentException
NOTE: parentLocation may be == 0. Must be synchronized outside.

Throws:
java.lang.IllegalArgumentException

nextLocation

public final int nextLocation(int prevLocation,
                              boolean forward)
                       throws java.lang.IllegalArgumentException
NOTE: prevLocation may be == 0. If result == 0 then no next location. This method is used for iteration on storage elements. Must be synchronized outside.

Throws:
java.lang.IllegalArgumentException

locationOf

public abstract int locationOf(java.lang.Object value,
                               int prevLocation,
                               boolean forward)
                        throws java.lang.IllegalArgumentException
NOTE: If prevLocation != 0 and prevLocation is an "empty" location then IllegalArgumentException is thrown. If value == null then 0 is returned. Else search is started after/before prevLocation. Result is either 0 (no more values) or a (not "empty") location of the first found element, which is equal to value. If (prevLocation == 0 or prevLocation is "valid") and result != 0 then result is a "valid" location. Storage state is not altered. The effectiveness is linear (typically), logarithmic or constant. Must be synchronized outside.

Throws:
java.lang.IllegalArgumentException

findLessGreater

public abstract int findLessGreater(java.lang.Object value,
                                    boolean greater,
                                    int prevLocation,
                                    boolean forward)
                             throws java.lang.IllegalArgumentException
NOTE: If prevLocation != 0 and prevLocation is an "empty" location then IllegalArgumentException is thrown. If value == null then 0 is returned. Search is started after/before prevLocation. Result is either 0 (no more values) or a (not "empty") location of the first found element, which is (greater ? 'greater' : 'less') than value. If (prevLocation == 0 or prevLocation is "valid") and result != 0 then result is a "valid" location. Storage state is not altered. The effectiveness is linear (typically), logarithmic or constant. Must be synchronized outside.

Throws:
java.lang.IllegalArgumentException

contains

public final boolean contains(java.lang.Object value)
NOTE: value may be == null. Must be synchronized outside.


containsCount

public final int containsCount(java.lang.Object value)
NOTE: value may be == null. Result >= 0. Must be synchronized outside.


toArray

public java.lang.Object[] toArray()
NOTE: Result is exact instanceof Object[] with non-null elements. Must be synchronized outside.


clone

public java.lang.Object clone()
NOTE: Must be synchronized outside.

Specified by:
clone in interface ReallyCloneable
Overrides:
clone in class ObservedCore
Returns:
a copy (may be null) of this instance.

hashCode

public int hashCode()
NOTE: Storage state is not altered. Must be synchronized outside.

Overrides:
hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object obj)
NOTE: Storage state is not altered. Must be synchronized outside, obj must be synchronized too if not null.

Overrides:
equals in class java.lang.Object

greaterThan

public boolean greaterThan(java.lang.Object obj)
NOTE: The first found non-equal elements pair is compared through GComparator INSTANCE. Storage state is not altered. Must be synchronized outside, obj must be synchronized too if not null.

Specified by:
greaterThan in interface Sortable
Parameters:
obj - the second compared object (may be null).
Returns:
true if obj is comparable with this and this object is greater than obj, else false.

toInlineString

public final java.lang.String toInlineString(ToString converter)
                                      throws java.lang.NullPointerException
NOTE: To separate storage values ", " is used, to represent tree layout/hierarchy " {" and " }" are used. converter must be != null. Result != null, result is 'in-line' (of course, if values toString() are 'in-line' too). Storage state is not altered. Must be synchronized outside.

Throws:
java.lang.NullPointerException

toOutlineString

public final java.lang.String toOutlineString(ToString converter)
                                       throws java.lang.NullPointerException
NOTE: To separate storage values "\n" is used, to represent tree layout/hierarchy "`", "|" and "-- " are used. converter must be != null. Result != null. Storage state is not altered. Must be synchronized outside.

Throws:
java.lang.NullPointerException

toString

public java.lang.String toString()
NOTE: Result != null, result is 'out-line' here. This method may be overridden in subclasses if needed. Must be synchronized outside.

Overrides:
toString in class java.lang.Object

integrityCheck

public void integrityCheck()
NOTE: Shallow check for integrity of this object. The effectiveness is linear. Should be overridden in subclasses. Must be synchronized outside. For debug purpose only.

Specified by:
integrityCheck in interface Verifiable
Overrides:
integrityCheck in class ObservedCore