ccs.beetree
Interface BeeTreeFilter

public interface BeeTreeFilter

A BeeTreeFilter can be supplied to a BeeTreeCompactor to allow the objects in the database to be vetted as they pass. This provides a simple solution to certain kinds of master-file update problem.

Method Summary

boolean	btfFilter(BeeTree src, BeeTree dest, BeeObject bo) The main filter function.
boolean	btfShouldUnmarshal() States whether the compactor should attempt to unmarshal the object.
boolean	btfSrcChanged() States whether you might have altered the state of the source database during the last call to btfFilter (e.g. by doing a find on it.)

Method Detail

btfFilter

boolean btfFilter(BeeTree src,
                  BeeTree dest,
                  BeeObject bo)
                  throws java.io.IOException

The main filter function. Dictates whether an object is copied into the new BeeTree, or dropped.

Parameters:

src - The source (old) BeeTree. Allows the filter to e.g. check cross- references to work out what to do with this one. Many applications will not need this capability.

dest - The destination (new) BeeTree Allows the filter to e.g. add cross-referenced objects to the new database. Many applications will not need this capability. If you do insert arbitrary objects, make sure that you don't cause a collision with subsequent objects from the old database - check for these and drop them.

bo - The BeeObject whose future is being considered. Note: the BeeObject has not been properly unmarshalled at this point. Either its marshalled data is sitting in a buffer, waiting for transfer, or it hasn't been unmrshalled at all, and its data is still in the source BeeTree. This depends on the return of your btfShouldUnmarshal; if this returns true, then the marshalled data is buffered, if false it's left in the source BeeTree.

This is necessary because some types of BeeObject (e.g. CDBObjects) require extra context to unmarshal properly and BeeTreeCompactor cannot provide this. If you need to manipulate the object:

1. Create an object of the proper type (how you determine this depends on the application) and do e.g. src.findExact() to unmarshal it properly.
2. manipulate it.
3. marshal it into the destination database (e.g. dest.insert() ).
4. return false. This will prevent the dumb handler in the compactor from attempting to insert the old marshalled data which it's holding.
5. Assuming that the find in step 1 had the same key as bo your btfSrcChanged() can safely return false - although you accessed the source beetree, you didn't move the object pointer.

Returns:

true to insert the (changed?) BeeObject into the new beetree, false to drop it. This only has an effect if btfShouldUnmarshal returned true - otherwise the filter is responsible for copying the object.

Throws:

java.io.IOException - if something fatal happens. Such a throw will abort the compaction, leaving the old copy intact but in a temporary file, and the new copy incomplete and possibly corrupt. Therefore catch 'em yourself if you can!

btfSrcChanged

boolean btfSrcChanged()

States whether you might have altered the state of the source database during the last call to btfFilter (e.g. by doing a find on it.) If you did, the compactor has to do a find to get back to where it was. Clearly it is more efficient not to do this if unnecessary, hence the question. If you can't tell, return true - a false positive is a minor efficiency issue, a false negative will corrupt the database.

Returns:

true if the source beetree might have been manipulated by the most recent btfFilter, false if it definitely was not.

btfShouldUnmarshal

boolean btfShouldUnmarshal()

States whether the compactor should attempt to unmarshal the object. It is called once at the start of the compaction. The compactor's idea of unmarshalling is to put all the marshalled object data into a buffer in order to squirt it straight into the destination BeeTree; if you need more sophisticated handling - and all CDBObjects do, for example - you should return false and have your btfFilter do it.