messif.buckets
Class Bucket

java.lang.Object
  extended by messif.buckets.Bucket
All Implemented Interfaces:
ObjectProvider<LocalAbstractObject>
Direct Known Subclasses:
LocalBucket

public abstract class Bucket
extends java.lang.Object
implements ObjectProvider<LocalAbstractObject>

A data area that hold a collection of AbstractObjects. A bucket can represent a metric space partition or it is used just as a generic object storage. The bucket provides methods for inserting one or more objects, deleting them, retrieving all objects or just a particular one (providing its ID). It also has a method for evaluating queries, which pushes all objects from the bucket to the sequential scan implementation of the respective query (if not overriden). Every bucket is also automatically assigned a unique ID used for addressing the bucket.

See Also:
LocalBucket, messif.netbucket.RemoteBucket

Constructor Summary
Bucket()
           
 
Method Summary
abstract  void addObject(LocalAbstractObject object)
          Insert a new object into this bucket.
 BucketErrorCode addObjectErrCode(LocalAbstractObject object)
          Insert a new object into this bucket and returns error code instead of exception.
 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.
abstract  int deleteAllObjects()
          Delete all objects from this bucket.
 int deleteObject(LocalAbstractObject object)
          Delete all objects from this bucket that are data-equals to the specified object.
abstract  int deleteObject(LocalAbstractObject object, int deleteLimit)
          Delete all objects from this bucket that are data-equals to the specified object.
abstract  LocalAbstractObject deleteObject(UniqueID objectID)
          Delete object with the specified ID from this bucket.
 AbstractObjectList<LocalAbstractObject> deleteObjects(java.util.Collection<? extends UniqueID> objectIDs, boolean removeDeletedIDs)
          Delete multiple objects with specified IDs.
abstract  AbstractObjectIterator<LocalAbstractObject> getAllObjects()
          Returns iterator over all objects from this bucket.
abstract  int getBucketID()
          Returns the unique ID of this bucket.
abstract  LocalAbstractObject getObject(AbstractObjectKey key)
          Retrieve an object with the specified key from this bucket.
abstract  LocalAbstractObject getObject(java.lang.String locator)
          Retrieve an object with the specified locator from this bucket.
abstract  LocalAbstractObject getObject(UniqueID objectID)
          Retrieves an object with the specified ID from this bucket.
 int processQuery(QueryOperation<?> query)
          Process a query operation on objects from this bucket.
 AbstractObjectIterator<LocalAbstractObject> provideObjects()
          The iterator for provided objects for ObjectProvider interface.
 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 java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Bucket

public Bucket()
Method Detail

getBucketID

public abstract int getBucketID()
Returns the unique ID of this bucket.

Returns:
this bucket ID

addObject

public abstract void addObject(LocalAbstractObject object)
                        throws BucketStorageException
Insert a new object into this bucket.

Parameters:
object - a new object to be inserted
Throws:
BucketStorageException - if the object cannot be inserted into the bucket

addObjectErrCode

public BucketErrorCode addObjectErrCode(LocalAbstractObject object)
Insert a new object into this bucket and returns error code instead of exception.

Parameters:
object - the new object to be inserted
Returns:
the success/failure error code of the object insertion

addObjects

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

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
Insert several new objects to this bucket. This method can be overriden if there is more efficient implementation available at the storage level.

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 abstract LocalAbstractObject deleteObject(UniqueID objectID)
                                          throws java.util.NoSuchElementException,
                                                 BucketStorageException
Delete object with the specified ID from this bucket.

Parameters:
objectID - the ID of the object to delete
Returns:
the object deleted from this bucket
Throws:
java.util.NoSuchElementException - if there is no object with the specified ID in this bucket
BucketStorageException - if the object cannot be deleted from the bucket

deleteObject

public abstract int deleteObject(LocalAbstractObject object,
                                 int deleteLimit)
                          throws BucketStorageException
Delete all objects from this bucket that are data-equals to the specified object. If deleteLimit is greater than zero, only the first deleteLimit data-equal objects found are deleted.

Parameters:
object - the object to match against
deleteLimit - the maximal number of deleted objects (zero means unlimited)
Returns:
the number of deleted objects
Throws:
BucketStorageException - if there was an object that cannot be deleted from the bucket

deleteObject

public int deleteObject(LocalAbstractObject object)
                 throws BucketStorageException
Delete all objects from this bucket that are data-equals to the specified object.

Parameters:
object - the object to match against
Returns:
the number of deleted objects
Throws:
BucketStorageException - if the object cannot be deleted from the bucket

deleteObjects

public AbstractObjectList<LocalAbstractObject> deleteObjects(java.util.Collection<? extends UniqueID> objectIDs,
                                                             boolean removeDeletedIDs)
                                                      throws BucketStorageException
Delete multiple objects with specified IDs. This method can be overriden if there is more efficient implementation available at the storage level.

Parameters:
objectIDs - List of object IDs to be deleted
removeDeletedIDs -
Returns:
list of objects that were delete from this bucket
Throws:
BucketStorageException - if the object cannot be deleted from the bucket

deleteAllObjects

public abstract int deleteAllObjects()
                              throws BucketStorageException
Delete all objects from this bucket. This method can be overriden if there is more efficient implementation available at the storage level.

Returns:
the number of deleted objects
Throws:
BucketStorageException - if there was an object that cannot be deleted from the bucket

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. Objects from this bucket are examined using the policy's matcher method. Based on the integer value returned the objects are separated into new buckets. The new buckets are added to their position in targetBuckets parameters. The position is the value returned by the policy's matcher method. The parameter whoStays denotes the partition that corresponds to this bucket, i.e., the objects marked with this number (whoStays) by the policy's matcher are left in this bucket and not moved to any new bucket. As a result, the whoStays index in targetBuckets is null (if this index existed in targetBuckets, it is left untouched). The list targetBuckets is extended to contain all getPartitionsCount() items. The items correponding to indexes that have not been returned by matcher for any object are initialized to null (or left untouched if the index have already existed). If targetBuckets is not initialized with references to buckets, the bucketCreator must be able to create additional buckets. Remark: to partition all objects to new buckets pass an empty instance of list in targetBuckets and set whoStays to a negative value since the matcher returns non-negative values only.

Parameters:
policy - the split policy used to split this bucket
targetBuckets - the list of target buckets to split the objects to
bucketCreator - the bucket dispatcher to use when creating target buckets; can be null if the targetBuckets has enough 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 during objects between buckets (including capacity overflow or underflow) during object move; warning: the split is interrupted and should be reinitialized

getObject

public abstract LocalAbstractObject getObject(UniqueID objectID)
                                       throws java.util.NoSuchElementException
Retrieves an object with the specified ID from this bucket.

Parameters:
objectID - the ID of the object to retrieve
Returns:
object an object with the specified ID
Throws:
java.util.NoSuchElementException - if there is no object with the specified ID in this bucket

getObject

public abstract LocalAbstractObject getObject(java.lang.String locator)
                                       throws java.util.NoSuchElementException
Retrieve an object with the specified locator from this bucket.

Parameters:
locator - the locator URI of the object to retrieve
Returns:
object with specified locator from this bucket
Throws:
java.util.NoSuchElementException - This exception is thrown if there is no object with the specified locator in this bucket

getObject

public abstract LocalAbstractObject getObject(AbstractObjectKey key)
                                       throws java.util.NoSuchElementException
Retrieve an object with the specified key from this bucket.

Parameters:
key - the key of the object to retrieve
Returns:
object with specified key from this bucket
Throws:
java.util.NoSuchElementException - This exception is thrown if there is no object with the specified key in this bucket

getAllObjects

public abstract AbstractObjectIterator<LocalAbstractObject> getAllObjects()
Returns iterator over all objects from this bucket.

Returns:
iterator over all objects from this bucket

processQuery

public int processQuery(QueryOperation<?> query)
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. Default implementation calls the evaluation method of the query operation. Override this method if the underlying storage structure supports effective evaluation of query operations.

Parameters:
query - query operation that is to be processed on this bucket
Returns:
the number of objects that were added to answer

provideObjects

public AbstractObjectIterator<LocalAbstractObject> provideObjects()
The iterator for provided objects for ObjectProvider interface.

Specified by:
provideObjects in interface ObjectProvider<LocalAbstractObject>
Returns:
iterator for provided objects