messif.buckets
Class LocalBucket

java.lang.Object
  extended by messif.buckets.Bucket
      extended by messif.buckets.LocalBucket
All Implemented Interfaces:
java.io.Serializable, ObjectProvider<LocalAbstractObject>
Direct Known Subclasses:
AlgorithmStorageBucket, DiskBlockBucket, MemoryStorageBucket, OrderedLocalBucket

public abstract class LocalBucket
extends Bucket
implements java.io.Serializable

This class represents the Bucket that is maintained locally (i.e. on the current computer). The local bucket maintains statistics for number of reads, inserts and deletions. This class provides most of the implementation using a naive approach, minimal implementation of the underlying class must have at least methods getObjectCount, storeObject and iterator. Getting an object and removing one is done through the methods of the iterator. More effective implementations can override other methods as well. For deletion, you need to override method iterator:removeInternal().

See Also:
Serialized Form

Field Summary
protected static StatisticRefCounter counterBucketAddObject
          Number of object inserts statistic per bucket
protected static StatisticRefCounter counterBucketDelObject
          Number of object deletions statistic per bucket
protected static StatisticRefCounter counterBucketRead
          Number of bucket reads statistic per bucket
 
Constructor Summary
protected LocalBucket(long capacity, long softCapacity, long lowOccupation, boolean occupationAsBytes)
          Constructs a new LocalBucket instance and setups all bucket limits
 
Method Summary
 void addObject(LocalAbstractObject object)
          Insert a new object into this bucket.
protected  void addObject(LocalAbstractObject object, Addible<LocalAbstractObject> addible)
          Check if the object object can added to this bucket.
 BucketErrorCode addObjectErrCode(LocalAbstractObject object)
          Insert a new object into this bucket and returns error code instead of exception.
 int deleteAllObjects()
          Delete all objects from this bucket.
 int deleteObject(LocalAbstractObject object, int deleteLimit)
          Delete all objects from this bucket that are data-equals to the specified object.
protected  void deleteObject(Removable<LocalAbstractObject> removable)
          Check if the object can be deleted from this bucket.
 LocalAbstractObject deleteObject(UniqueID objectID)
          Delete object with the specified ID from this bucket.
 void deregisterFilter(BucketFilter filter)
          Remove a filter from the filter chain
 void destroy()
          Destroy this bucket.
 void finalize()
          Finalize this bucket.
 AbstractObjectIterator<LocalAbstractObject> getAllObjects()
          Returns iterator over all objects from this bucket.
 int getBucketID()
          Returns the unique ID of this bucket.
 long getCapacity()
          Returns the maximal capacity of this bucket.
<T extends BucketFilter>
T
getFilter(java.lang.Class<T> filterClass)
          Returns the first registered filter that has the specified class
 Index<LocalAbstractObject> getIndex()
          Returns the index defined on this bucket that can be used for searching.
 long getLowOccupation()
          Returns the minimal occupation of this bucket.
protected abstract  ModifiableIndex<LocalAbstractObject> getModifiableIndex()
          Returns the index (including storage) for this bucket.
 LocalAbstractObject getObject(AbstractObjectKey key)
          Retrieve an object with the specified key from this bucket.
 LocalAbstractObject getObject(java.lang.String locator)
          Retrieve an object with the specified locator from this bucket.
 LocalAbstractObject getObject(UniqueID objectID)
          Retrieves an object with the specified ID from this bucket.
 int getObjectCount()
          Returns current number of objects stored in this bucket.
 long getOccupation()
          Returns the current occupation of this bucket.
 double getOccupationRatio()
          Returns an occupation ratio with respect to the bucket's soft capacity, i.e. the current occupation divided by the soft capacity.
 long getSoftCapacity()
          Returns the soft capacity of this bucket.
 boolean isBucketStandalone()
          Returns whether this bucket is standalone bucket or if it is maintained by a bucket dispatcher.
 boolean isSoftCapacityExceeded()
          Returns true if the soft-capacity of the bucket has been exceeded.
 void registerFilter(BucketFilter filter)
          Append a new filter to the filter chain.
 void setLowOccupation(long lowOccupation)
          Set param "low occupeation" for thsi bucket
 void setSoftCapacity(long softCapacity)
          Set new soft capacity for this bucket
 java.lang.String toString()
          Returns a string representation of this bucket.
 
Methods inherited from class messif.buckets.Bucket
addObjects, addObjects, deleteObject, deleteObjects, processQuery, provideObjects, split
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

counterBucketRead

protected static final StatisticRefCounter counterBucketRead
Number of bucket reads statistic per bucket


counterBucketAddObject

protected static final StatisticRefCounter counterBucketAddObject
Number of object inserts statistic per bucket


counterBucketDelObject

protected static final StatisticRefCounter counterBucketDelObject
Number of object deletions statistic per bucket

Constructor Detail

LocalBucket

protected LocalBucket(long capacity,
                      long softCapacity,
                      long lowOccupation,
                      boolean occupationAsBytes)
Constructs a new LocalBucket instance and setups all bucket limits

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
Method Detail

finalize

public void finalize()
              throws java.lang.Throwable
Finalize this bucket. All transient resources associated with this bucket are released. After this method is called, the bucket methods' behavior is unpredictable. This method is called by the BucketDispatcher when it is finalized.

Overrides:
finalize in class java.lang.Object
Throws:
java.lang.Throwable - if there was an error while cleaning

destroy

public void destroy()
             throws java.lang.Throwable
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.

Throws:
java.lang.Throwable - if there was an error while cleaning

getBucketID

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

Specified by:
getBucketID in class Bucket
Returns:
this bucket ID

isBucketStandalone

public boolean isBucketStandalone()
Returns whether this bucket is standalone bucket or if it is maintained by a bucket dispatcher.

Returns:
true

setLowOccupation

public void setLowOccupation(long lowOccupation)
Set param "low occupeation" for thsi bucket

Parameters:
lowOccupation - new low occupation.

setSoftCapacity

public void setSoftCapacity(long softCapacity)
Set new soft capacity for this bucket

Parameters:
softCapacity - new soft capacity param

getCapacity

public long getCapacity()
Returns the maximal capacity of this bucket. This limit cannot be exceeded.

Returns:
the maximal capacity of bucket

getSoftCapacity

public long getSoftCapacity()
Returns the soft capacity of this bucket. This limit can be exceeded, but insert operations will return BucketErrorCode.SOFTCAPACITY_EXCEEDED.

Returns:
the soft capacity of this bucket

getLowOccupation

public long getLowOccupation()
Returns the minimal occupation of this bucket. Whenever a deletion of an object is tried, that would result in undeflow, an OccupationLowException exception is thrown.

Returns:
the minimal occupation of this bucket

getOccupation

public long getOccupation()
Returns the current occupation of this bucket.

Returns:
the current occupation of this bucket

getOccupationRatio

public double getOccupationRatio()
Returns an occupation ratio with respect to the bucket's soft capacity, i.e. the current occupation divided by the soft capacity.

Returns:
the occupation ratio of this bucket

isSoftCapacityExceeded

public boolean isSoftCapacityExceeded()
Returns true if the soft-capacity of the bucket has been exceeded.

Returns:
true if the soft-capacity of the bucket has been exceeded or false otherwise

getObjectCount

public int getObjectCount()
Returns current number of objects stored in this bucket.

Returns:
current number of objects stored in this bucket

getModifiableIndex

protected abstract ModifiableIndex<LocalAbstractObject> getModifiableIndex()
Returns the index (including storage) for this bucket. The index provides the access to the underlying storage of objects in this bucket.

Returns:
the index for this bucket

getIndex

public Index<LocalAbstractObject> getIndex()
Returns the index defined on this bucket that can be used for searching.

Returns:
the index for this bucket

registerFilter

public void registerFilter(BucketFilter filter)
Append a new filter to the filter chain.

Parameters:
filter - the new filter to append

deregisterFilter

public void deregisterFilter(BucketFilter filter)
Remove a filter from the filter chain

Parameters:
filter - the filter to remove

getFilter

public <T extends BucketFilter> T getFilter(java.lang.Class<T> filterClass)
                                 throws java.util.NoSuchElementException
Returns the first registered filter that has the specified class

Type Parameters:
T - the class of the filter
Parameters:
filterClass - filter class to search for
Returns:
the first registered filter that has the specified class
Throws:
java.util.NoSuchElementException - if there was no filter with the specified class

addObject

protected void addObject(LocalAbstractObject object,
                         Addible<LocalAbstractObject> addible)
                  throws BucketStorageException
Check if the object object can added to this bucket.

Parameters:
object - the object to add
addible - the Addible that actually stores the object
Throws:
BucketStorageException - if there was an error adding the object

deleteObject

protected void deleteObject(Removable<LocalAbstractObject> removable)
                     throws BucketStorageException
Check if the object can be deleted from this bucket. This includes the pre-checks of the filters and also the low-occupation check.

Parameters:
removable - the object that is going to be removed
Throws:
BucketStorageException - if the object cannot be removed (reason is stored in the exception)

addObject

public void addObject(LocalAbstractObject object)
               throws BucketStorageException
Description copied from class: Bucket
Insert a new object into this bucket.

Specified by:
addObject in class Bucket
Parameters:
object - a new object to be inserted
Throws:
BucketStorageException - if the object cannot be inserted into the bucket

addObjectErrCode

public final BucketErrorCode addObjectErrCode(LocalAbstractObject object)
Description copied from class: Bucket
Insert a new object into this bucket and returns error code instead of exception.

Overrides:
addObjectErrCode in class Bucket
Parameters:
object - the new object to be inserted
Returns:
the success/failure error code of the object insertion

deleteObject

public LocalAbstractObject deleteObject(UniqueID objectID)
                                 throws java.util.NoSuchElementException,
                                        BucketStorageException
Description copied from class: Bucket
Delete object with the specified ID from this bucket.

Specified by:
deleteObject in class 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 int deleteObject(LocalAbstractObject object,
                        int deleteLimit)
                 throws BucketStorageException
Description copied from class: Bucket
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.

Specified by:
deleteObject in class Bucket
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

deleteAllObjects

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

Specified by:
deleteAllObjects in class Bucket
Returns:
the number of deleted objects
Throws:
BucketStorageException - if there was an object that cannot be deleted from the bucket

getObject

public LocalAbstractObject getObject(UniqueID objectID)
                              throws java.util.NoSuchElementException
Description copied from class: Bucket
Retrieves an object with the specified ID from this bucket.

Specified by:
getObject in class 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 LocalAbstractObject getObject(java.lang.String locator)
                              throws java.util.NoSuchElementException
Description copied from class: Bucket
Retrieve an object with the specified locator from this bucket.

Specified by:
getObject in class 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 LocalAbstractObject getObject(AbstractObjectKey key)
                              throws java.util.NoSuchElementException
Description copied from class: Bucket
Retrieve an object with the specified key from this bucket.

Specified by:
getObject in class 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 AbstractObjectIterator<LocalAbstractObject> getAllObjects()
Description copied from class: Bucket
Returns iterator over all objects from this bucket.

Specified by:
getAllObjects in class Bucket
Returns:
iterator over all objects from this bucket

toString

public java.lang.String toString()
Returns a string representation of this bucket.

Overrides:
toString in class java.lang.Object
Returns:
a string representation of this bucket