messif.buckets.impl
Class AlgorithmStorageBucket

java.lang.Object
  extended by messif.buckets.Bucket
      extended by messif.buckets.LocalBucket
          extended by messif.buckets.impl.AlgorithmStorageBucket
All Implemented Interfaces:
java.io.Serializable, Addible<LocalAbstractObject>, Index<LocalAbstractObject>, ModifiableIndex<LocalAbstractObject>, ObjectProvider<LocalAbstractObject>

public class AlgorithmStorageBucket
extends LocalBucket
implements ModifiableIndex<LocalAbstractObject>

This is a LocalBucket that allows to create buckets backed by an Algorithm. The algorithm should be able to execute the following operations: InsertOperation DeleteOperation GetAllObjectsQueryOperation GetObjectQueryOperation All other query operations are first tried on the encapsulated algorithm and if they are not supported, they are evaluated by the standard mechanism.

See Also:
Serialized Form

Field Summary
 
Fields inherited from class messif.buckets.LocalBucket
counterBucketAddObject, counterBucketDelObject, counterBucketRead
 
Constructor Summary
AlgorithmStorageBucket(Algorithm algorithm, long capacity, long softCapacity, long lowOccupation, boolean occupationAsBytes)
          Creates a new instance of AlgorithmStorageBucket and setups all bucket limits.
 
Method Summary
 boolean add(LocalAbstractObject object)
          Stores the specified object in the encapsulated algorithm, i.e.
 int addObjects(java.util.Collection<? extends LocalAbstractObject> objects)
          Insert several new objects into this bucket.
 int addObjects(java.util.Iterator<? extends LocalAbstractObject> objects)
          Insert several new objects to this bucket.
protected static Algorithm createAlgorithmFromParams(java.lang.Class<? extends Algorithm> algClass, java.util.Map<java.lang.String,java.lang.Object> parameters)
          Creates an algorithm of the specified class with map of parameters.
protected static Algorithm createAlgorithmFromParams(java.lang.String algClassName, java.util.Map<java.lang.String,java.lang.Object> parameters)
          Creates an algorithm of the specified class with map of parameters.
 int deleteObject(LocalAbstractObject object, int deleteLimit)
          Removes the given object by calling DeleteOperation on the encapsulated algorithm.
 void destroy()
          Destroy this bucket.
 void finalize()
          Clean up bucket internals before deletion.
 Algorithm getAlgorithm()
          Return the instance of the algorithm encapsulated by this bucket
static AlgorithmStorageBucket getBucket(long capacity, long softCapacity, long lowOccupation, boolean occupationAsBytes, java.util.Map<java.lang.String,java.lang.Object> parameters)
          Creates a new algorithm bucket.
protected  ModifiableIndex<LocalAbstractObject> getModifiableIndex()
          Returns the index (including storage) for this bucket.
 int processQuery(QueryOperation query)
          Process a query operation on objects from this bucket.
 ModifiableSearch<LocalAbstractObject> search()
          Returns a search for all objects in this index.
<C> ModifiableSearch<LocalAbstractObject>
search(IndexComparator<? super C,? super LocalAbstractObject> comparator, C key)
          Returns a search for objects in this index that have any of the specified keys.
<C> ModifiableSearch<LocalAbstractObject>
search(IndexComparator<? super C,? super LocalAbstractObject> comparator, C from, C to)
          Returns a search for objects in this index that are within the specified key-range.
<C> ModifiableSearch<LocalAbstractObject>
search(IndexComparator<? super C,? super LocalAbstractObject> comparator, java.util.Collection<? extends C> keys)
          Returns a search for objects in this index that have any of the specified keys.
 int size()
          Returns current number of objects in this index.
 int split(SplitPolicy policy, java.util.List<Bucket> targetBuckets, BucketDispatcher bucketCreator, int whoStays)
          Splits this bucket according to the specified policy.
 
Methods inherited from class messif.buckets.LocalBucket
addObject, addObject, addObjectErrCode, deleteAllObjects, deleteObject, deleteObject, deregisterFilter, getAllObjects, getBucketID, getCapacity, getFilter, getIndex, getLowOccupation, getObject, getObject, getObject, getObjectCount, getOccupation, getOccupationRatio, getSoftCapacity, isBucketStandalone, isSoftCapacityExceeded, registerFilter, setLowOccupation, setSoftCapacity, toString
 
Methods inherited from class messif.buckets.Bucket
deleteObject, deleteObjects, provideObjects
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

AlgorithmStorageBucket

public AlgorithmStorageBucket(Algorithm algorithm,
                              long capacity,
                              long softCapacity,
                              long lowOccupation,
                              boolean occupationAsBytes)
Creates a new instance of AlgorithmStorageBucket and setups all bucket limits. Note that the algorithm should not contain objects.

Parameters:
algorithm - encapsulated algorithm that will actually do the job
capacity - maximal capacity of the bucket - cannot be exceeded
softCapacity - maximal soft capacity of the bucket
lowOccupation - a minimal occupation for deleting objects - cannot be lowered
occupationAsBytes - flag whether the occupation (and thus all the limits) are in bytes or number of objects
Method Detail

finalize

public void finalize()
              throws java.lang.Throwable
Clean up bucket internals before deletion. This method is called by bucket dispatcher when this bucket is removed or when the bucket is garbage collected. The method calls finalizer of the encapsulated algorithm.

Specified by:
finalize in interface ModifiableIndex<LocalAbstractObject>
Overrides:
finalize in class LocalBucket
Throws:
java.lang.Throwable - if there was an error during releasing resources

destroy

public void destroy()
             throws java.lang.Throwable
Description copied from class: LocalBucket
Destroy this bucket. This method releases all resources (transient and persistent) associated with this bucket (e.g. the statistics and all objects are deleted). After this method is called, the bucket methods' behavior is unpredictable. This method is called by the BucketDispatcher when the bucket is removed from the dispatcher.

Specified by:
destroy in interface ModifiableIndex<LocalAbstractObject>
Overrides:
destroy in class LocalBucket
Throws:
java.lang.Throwable - if there was an error while cleaning

getBucket

public static AlgorithmStorageBucket getBucket(long capacity,
                                               long softCapacity,
                                               long lowOccupation,
                                               boolean occupationAsBytes,
                                               java.util.Map<java.lang.String,java.lang.Object> parameters)
                                        throws java.lang.IllegalArgumentException
Creates a new algorithm bucket. The parameters for the algorithm constructor are specified in the parameters map. Recognized parameters: class - the algorithm class param.1 - the first argument for the algorithm constructor param.2 - etc.

Parameters:
capacity - maximal capacity of the bucket - cannot be exceeded
softCapacity - maximal soft capacity of the bucket
lowOccupation - a minimal occupation for deleting objects - cannot be lowered
occupationAsBytes - flag whether the occupation (and thus all the limits) are in bytes or number of objects
parameters - list of named parameters - this bucket supports "file" and "path" (see above)
Returns:
a new DiskBucket instance
Throws:
java.lang.IllegalArgumentException - if the parameters from the parameters map are invalid and the backing algorithm stub cannot be created

createAlgorithmFromParams

protected static Algorithm createAlgorithmFromParams(java.lang.Class<? extends Algorithm> algClass,
                                                     java.util.Map<java.lang.String,java.lang.Object> parameters)
                                              throws java.lang.IllegalArgumentException
Creates an algorithm of the specified class with map of parameters. The map should have keys of the format "param.1", "param.2", etc.

Parameters:
algClass - the class of the algorithm that is created
parameters - the parameters for the algorithm constructor
Returns:
a new instance of algorithm
Throws:
java.lang.IllegalArgumentException - if the parameter map contains invalid values or the instantiation of algorithm fails

createAlgorithmFromParams

protected static Algorithm createAlgorithmFromParams(java.lang.String algClassName,
                                                     java.util.Map<java.lang.String,java.lang.Object> parameters)
                                              throws java.lang.IllegalArgumentException
Creates an algorithm of the specified class with map of parameters. The map should have keys of the format "param.1", "param.2", etc.

Parameters:
algClassName - the name of the class of the algorithm that is created
parameters - the parameters for the algorithm constructor
Returns:
a new instance of algorithm
Throws:
java.lang.IllegalArgumentException - if the parameter map contains invalid values or the instantiation of algorithm fails

getModifiableIndex

protected ModifiableIndex<LocalAbstractObject> getModifiableIndex()
Description copied from class: LocalBucket
Returns the index (including storage) for this bucket. The index provides the access to the underlying storage of objects in this bucket.

Specified by:
getModifiableIndex in class LocalBucket
Returns:
the index for this bucket

size

public int size()
Description copied from interface: Index
Returns current number of objects in this index.

Specified by:
size in interface Index<LocalAbstractObject>
Returns:
current number of objects in this index

getAlgorithm

public Algorithm getAlgorithm()
Return the instance of the algorithm encapsulated by this bucket

Returns:
the instance of the algorithm encapsulated by this bucket

add

public boolean add(LocalAbstractObject object)
            throws BucketStorageException
Stores the specified object in the encapsulated algorithm, i.e. the InsertOperation is executed.

Specified by:
add in interface Addible<LocalAbstractObject>
Parameters:
object - The new object to be inserted
Returns:
error code - for details, see documentation of BucketErrorCode
Throws:
BucketStorageException - if there was an error storing the object to the encapsulated algorithm, e.g. the encapsulated algorithm does not support InsertOperation

addObjects

public int addObjects(java.util.Collection<? extends LocalAbstractObject> objects)
               throws BucketStorageException
Description copied from class: Bucket
Insert several new objects into this bucket. This method can be overriden if there is more efficient implementation available at the storage level.

Overrides:
addObjects in class Bucket
Parameters:
objects - the collection of new objects
Returns:
number of objects actually added to bucket
Throws:
BucketStorageException - if there was an object that cannot be inserted into the bucket

addObjects

public int addObjects(java.util.Iterator<? extends LocalAbstractObject> objects)
               throws BucketStorageException
Description copied from class: Bucket
Insert several new objects to this bucket. This method can be overriden if there is more efficient implementation available at the storage level.

Overrides:
addObjects in class Bucket
Parameters:
objects - iterator that provides the new objects to insert
Returns:
number of objects actually added to bucket
Throws:
BucketStorageException - if there was an object that cannot be inserted into the bucket

deleteObject

public int deleteObject(LocalAbstractObject object,
                        int deleteLimit)
                 throws BucketStorageException
Removes the given object by calling DeleteOperation on the encapsulated algorithm.

Overrides:
deleteObject in class LocalBucket
Parameters:
object - the object to delete
deleteLimit - the maximal number of deleted objects (zero means unlimited)
Returns:
the number of deleted objects
Throws:
BucketStorageException - if the algorithm does not support delete operation or there was an error deleting the object

search

public ModifiableSearch<LocalAbstractObject> search()
                                             throws java.lang.IllegalStateException
Description copied from interface: Index
Returns a search for all objects in this index.

Specified by:
search in interface Index<LocalAbstractObject>
Specified by:
search in interface ModifiableIndex<LocalAbstractObject>
Returns:
a search for all objects in this index
Throws:
java.lang.IllegalStateException - if there was an error initializing the search on this index

search

public <C> ModifiableSearch<LocalAbstractObject> search(IndexComparator<? super C,? super LocalAbstractObject> comparator,
                                                        C key)
                                             throws java.lang.IllegalStateException
Description copied from interface: Index
Returns a search for objects in this index that have any of the specified keys. The equality is checked exclusively by using the specified comparator, thus key need not necessarily be of the same class as the objects stored in this index and also consistency with equals is not required.

Note that objects are not necessarily returned in the order defined by the comparator

Specified by:
search in interface Index<LocalAbstractObject>
Specified by:
search in interface ModifiableIndex<LocalAbstractObject>
Type Parameters:
C - the type of the key used by the search
Parameters:
comparator - compares the key with the stored objects
key - the key to search for
Returns:
a search for objects in this index
Throws:
java.lang.IllegalStateException - if there was an error initializing the search on this index

search

public <C> ModifiableSearch<LocalAbstractObject> search(IndexComparator<? super C,? super LocalAbstractObject> comparator,
                                                        java.util.Collection<? extends C> keys)
                                             throws java.lang.IllegalStateException
Description copied from interface: Index
Returns a search for objects in this index that have any of the specified keys. The equality is checked exclusively by using the specified comparator, thus key need not necessarily be of the same class as the objects stored in this index and also consistency with equals is not required.

Note that objects are not necessarily returned in the order defined by the comparator

Specified by:
search in interface Index<LocalAbstractObject>
Specified by:
search in interface ModifiableIndex<LocalAbstractObject>
Type Parameters:
C - the type of the keys used by the search
Parameters:
comparator - compares the keys with the stored objects
keys - the keys to search for (at least one key must be given)
Returns:
a search for objects in this index
Throws:
java.lang.IllegalStateException - if there was an error initializing the search on this index

search

public <C> ModifiableSearch<LocalAbstractObject> search(IndexComparator<? super C,? super LocalAbstractObject> comparator,
                                                        C from,
                                                        C to)
                                             throws java.lang.IllegalStateException
Description copied from interface: Index
Returns a search for objects in this index that are within the specified key-range. The key boundaries [from, to] need not necessarily be of the same class as the objects stored in this index, however, the comparator must be able to compare the boundaries and the internal objects.

Note that objects are not returned in the order defined by the comparator

Specified by:
search in interface Index<LocalAbstractObject>
Specified by:
search in interface ModifiableIndex<LocalAbstractObject>
Type Parameters:
C - the type the boundaries used by the search
Parameters:
comparator - compares the boundaries [from, to] with the stored objects
from - the lower bound on the searched objects, i.e. objects greater or equal are returned
to - the upper bound on the searched objects, i.e. objects smaller or equal are returned
Returns:
a search for objects in this index
Throws:
java.lang.IllegalStateException - if there was an error initializing the search on this index

processQuery

public int processQuery(QueryOperation query)
                 throws java.lang.UnsupportedOperationException
Process a query operation on objects from this bucket. The query operation's answer is updated with objects from this bucket that satisfy the query. The query is first executed directly on the algorithm and if it is unsupported, the standard query evaluation is performed (i.e. getAllObjects is called and then the sequential scan is used).

Overrides:
processQuery in class Bucket
Parameters:
query - query operation that is to be processed on this bucket
Returns:
the number of objects that were added to answer
Throws:
java.lang.UnsupportedOperationException - if the specified query is not supported by the encapsulated algorithm

split

public int split(SplitPolicy policy,
                 java.util.List<Bucket> targetBuckets,
                 BucketDispatcher bucketCreator,
                 int whoStays)
          throws java.lang.IllegalArgumentException,
                 BucketStorageException
Splits this bucket according to the specified policy. If the encapsulated algorithm implements the SplittableAlgorithm interface and the bucketCreator is provided, the split method of the algorithm will be called to perform the split. Otherwise, the standard Bucket's Bucket.split(messif.buckets.split.SplitPolicy, java.util.List, messif.buckets.BucketDispatcher, int) is executed.

Overrides:
split in class Bucket
Parameters:
policy - the split policy used to split this bucket
targetBuckets - the list of target buckets that will receive the list of created buckets
bucketCreator - the bucket dispatcher to use when creating target buckets
whoStays - identification of a partition whose objects stay in this bucket.
Returns:
the number of objects moved
Throws:
java.lang.IllegalArgumentException - if there are too few target buckets
BucketStorageException - if there was a storage error (capacity overflow/underflow or filter reject) during split