cbr.service
Class PicsStore

java.lang.Object
  cbr.service.PicsStore

public class PicsStore

extends Object

This class manages an index of picture entries. The index is kept in a file in a Resource. Multiple instances can share a single resource. However, the index files must not be shared unless the instances use the same Lock instance for locking.

This class is thread safe and supports multiple concurrent readers and exclusive write access. Readers and writers are scheduled according to the first come first serve strategy. No starvation can occur, each reader and writer eventually gets its turn.

Management of thumbnails is delegated to a separate object. The rationale for this is to remove thumbnails before the picture entries are written to the index. This renders lookup and insertion operations more efficient because the thumbnails must not be written and read whenever the index is scanned.

Lookups depend on the FeatureVector.distance() method of the query vector. Incompatible vectors should return 1.0 which is the maximum normalized distance. The index simply consists of a stream of serialized PictureEntry instances terminated by a string ("EOF").

Version:

"$Id: PicsStore.java 1913 2007-08-08 02:41:53Z jpeters $"

Author:

Volker Roth

Field Summary

private StoreDelegate	delegate_ The delegate that handles treatment of thumbnails.
private String	idx_ The name of the index file in the resource.
private Lock	lock_ The lock used to manage access to the index file.
static int	MODE_DELETE The mode for deleting entries from the index.
static int	MODE_INSERT The mode for inserting entries into the index.
private Resource	store_ The resource where the index is kept.
private String	tmp_ The name of the temporary index file in the resource.

Constructor Summary

PicsStore(Resource store, String idx, String tmp)
Creates a new instance.

Method Summary

PictureEntry[]	find(FeatureVector v, float threshold, int max) Matches the given feature vector against the ones of the known pictures and returns the picture entries of at most max pictures that have a normalised distance less than the given threshold to the query vector.
StoreDelegate	getDelegate() Returns the StoreDelegate of this instance.
void	init() Initialises the store.
PicsIterator	iterator() Returns an iterator for the pictures in the index file.
void	setDelegate(StoreDelegate delegate) Sets the StoreDelegate of this PicsStore.
private void	truncate(ArrayList list, int max) Truncates the given list to the given number of entries.
void	update(Iterator entries, int mode) Updates the index file according to the picture entries returned by the given iterator.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MODE_INSERT

public static final int MODE_INSERT

The mode for inserting entries into the index.

See Also:

Constant Field Values

MODE_DELETE

public static final int MODE_DELETE

The mode for deleting entries from the index.

See Also:

Constant Field Values

store_

private Resource store_

The resource where the index is kept.

lock_

private Lock lock_

The lock used to manage access to the index file.

idx_

private String idx_

The name of the index file in the resource.

tmp_

private String tmp_

The name of the temporary index file in the resource. This file is used when the index is updated either by importing entries into it or by deleting entries from it.

delegate_

private StoreDelegate delegate_

The delegate that handles treatment of thumbnails.

Constructor Detail

PicsStore

public PicsStore(Resource store,
                 String idx,
                 String tmp)

Creates a new instance.

Parameters:

store - The Resource in which the index file is stored. A resource can be shared among multiple instances of this class.

idx - The name of index file in the resource. The index file cannot be shared among multiple instances of this class unless these instances share the same lock instance.

tmp - The name of the temporary file that is used when the index is updated. The temporary file cannot be shared.

Throws:

NullPointerException - if some argument is null.

Method Detail

setDelegate

public void setDelegate(StoreDelegate delegate)

Sets the StoreDelegate of this PicsStore. The delegate handles thumbnails on behalf of this object.

Parameters:

delegate - The StoreDelegate instance or null if the delegate shall be cleared.

getDelegate

public StoreDelegate getDelegate()

Returns the StoreDelegate of this instance.

Returns:

The StoreDelegate or null if none is set.

init

public void init()
          throws IOException

Initialises the store. If the index file already exists and contains data then all this data will be lost. The method attempts to get a write lock on the index file.

Throws:

IOException

update

public void update(Iterator entries,
                   int mode)
            throws IOException

Updates the index file according to the picture entries returned by the given iterator. The iterator must return the picture entries in the natural order of the picture entries as determined by the compareTo method.

If the mode is MODE_DELETE then all entries in the index matching the ones returned by the given iterator are deleted. Otherwise the entries returned by the given iterator are inserted into the index.

The following comment is relevant only if the mode is not MODE_DELETE.

If no StoreDelegate has been set then thumbnails are embedded into the stream of serialised object instances. This is inefficient since the thumbnails are not required for feature matching. Still they must be read when the search method sifts through the index. Thus setting an appropriate delegate is strongly recommended.

Parameters:

entries - An iterator that iterates over the picture entries that shall be inserted into the index.

Throws:

IOException

find

public PictureEntry[] find(FeatureVector v,
                           float threshold,
                           int max)
                    throws IOException

Matches the given feature vector against the ones of the known pictures and returns the picture entries of at most max pictures that have a normalised distance less than the given threshold to the query vector.

Parameters:

v - The feature vector to match known picture entries against.

threshold - The maximum distance a picture in the result set is allowed to have from the query vector.

max - The maximum number of results that shall be returned.

Throws:

IOException

truncate

private void truncate(ArrayList list,
                      int max)

Truncates the given list to the given number of entries. Before truncation the list is sorted according to the distance values in the entries.

In other words this methods makes sure that the max best results are kept in the given list.

Parameters:

list - The list of picture entries.

max - The maximum number of entries that shall be kept in the list after truncation.

iterator

public PicsIterator iterator()

Returns an iterator for the pictures in the index file. Important note: accessing the index entries by means of this method bypasses the locking mechanisms. The caller is responsible for assuring that no concurrent accesses to the store occur while the iterator is in use. Moreover all elements of the iterator should be requested via its next() method such that the iterator can free its resources after completition.

This iterator returns picture entries with thumbnails filled in. For this, the StoreDelegate of this instance is used.

Callers should close the returned iterator as soon as it is not longer used.

Returns:

The PicsIterator for all entries in the index. The elements are returned in sorted order; the order is the natural ordering as determined by PictureEntry.compareTo()