org.semanticdesktop.aperture.accessor
Interface AccessData

All Known Implementing Classes:

AccessDataImpl, FileAccessData, FilterAccessData, ModelAccessData, SynchronizedAccessData

public interface AccessData

An AccessData instance stores information about accessed resources such as last modification dates, locations, etc. This primarily facilitates incremental crawling of DataSources. AccessData proposes a number of keys to use when storing values, combined with a proposed value encoding. This is to ensure that several DataAccessors and possibly other components can share the same AccessData instance without resulting in conflicts.

Field Summary

static String	BYTE_SIZE_KEY Recommended key to store a resource's byte size.
static String	DATE_KEY Recommended key to store a resource's date.
static String	REDIRECTS_TO_KEY Recommended key to store the redirected URL of an original URL.

Method Summary

void	clear() Clears this AccessData.
String	get(String id, String key) Gets specific information about the specified id.
Set	getAggregatedIDs(String id) Returns a set of id's that are aggregated immediately below the given one.
ClosableIterator	getAggregatedIDsClosure(String id) Returns an iterator over all ids aggregated within the given one, both directly and indirectly.
Set	getReferredIDs(String id) Returns all referred resources of the specified resource.
int	getSize() Gets the number of resources for which information has been stored in this AccessData.
Set	getStoredIDs() Gets the IDs of all resources for which information has been stored in this AccessData.
ClosableIterator	getUntouchedIDsIterator() Returns an iterator over all ID's in this access data instance that have not been touched since the last call to initialize()
void	initialize() Prepares the AccessData for operation.
boolean	isKnownId(String id) Returns whether this AccessData holds any information about the specified ID.
boolean	isTouched(String id) Returns true if this id is known and has been touched since the last call to initialize(), false if the id is not known, or hasn't been touched since the last call to initialize().
void	put(String id, String key, String value) Stores information (a key-value pair) for the specified id.
void	putAggregatedID(String id, String aggregatedID) Puts a link between the given id and the aggregated ID.
void	putReferredID(String id, String referredID) Stores a reference relation between two resources, modeling e.g. a link.
void	remove(String id) Removes all information about the resource with the specified ID.
void	remove(String id, String key) Removes the value for the specified id and key.
void	removeAggregatedID(String id, String aggregatedID) Removes the link between the given id and the aggregated ID.
void	removeReferredID(String id, String referredID) Removes a reference relationship between two resources.
void	removeReferredIDs(String id) Removes all referred IDs of a resource.
void	removeUntouchedIDs() Removes all untouched IDS
void	store() Informs the AccessData that processing has completed and, in case of a persistent storage, now is a good time to write or flush results.
void	touch(String id) Touches an id.
void	touchRecursively(String id) Recursively touches all ids within the aggregation subtree beginning with the given id

Field Detail

DATE_KEY

static final String DATE_KEY

Recommended key to store a resource's date. Recommended value encoding: time in milliseconds as a string.

See Also:

Constant Field Values

BYTE_SIZE_KEY

static final String BYTE_SIZE_KEY

Recommended key to store a resource's byte size. Recommended value encoding: String-encoded long.

See Also:

Constant Field Values

REDIRECTS_TO_KEY

static final String REDIRECTS_TO_KEY

Recommended key to store the redirected URL of an original URL. Recommended value encoding: a legal URI.

See Also:

Constant Field Values

Method Detail

initialize

void initialize()
                throws IOException

Prepares the AccessData for operation. This may for example mean reading files or opening repositories that hold the stored data.

Throws:

IOException

store

void store()
           throws IOException

Informs the AccessData that processing has completed and, in case of a persistent storage, now is a good time to write or flush results. Afterwards the AccessData may be in an unusable state until 'initialize' is invoked again.

Throws:

IOException

clear

void clear()
           throws IOException

Clears this AccessData. This may be invoked on initialized and unititialized AccessData's. Both in-memory information as any persistent storage will be cleared. Afterwards the AccessData may be in an unusable state until 'initialize' is invoked again.

Throws:

IOException

getSize

int getSize()

Gets the number of resources for which information has been stored in this AccessData.

Returns:

The number of registered resources.

getStoredIDs

Set getStoredIDs()

Gets the IDs of all resources for which information has been stored in this AccessData.

Returns:

A Set of Strings.

isKnownId

boolean isKnownId(String id)

Returns whether this AccessData holds any information about the specified ID.

Returns:

"true" when this AccessData has information about the specified ID, "false" otherwise.

put

void put(String id,
         String key,
         String value)

Stores information (a key-value pair) for the specified id.

Parameters:

id - The resource's ID.

key - The info key.

value - The info value.

putReferredID

void putReferredID(String id,
                   String referredID)

Stores a reference relation between two resources, modeling e.g. a link.

Parameters:

id - The referring resource's ID.

referredID - The referred resource's ID.

get

String get(String id,
           String key)

Gets specific information about the specified id.

Parameters:

id - The resource's ID.

key - The info key.

Returns:

The stored info value, or null if no info has been stored for the specified id and key.

getReferredIDs

Set getReferredIDs(String id)

Returns all referred resources of the specified resource.

Returns:

A Set of Strings, or null when there are no referred resources registered for this resource.

remove

void remove(String id,
            String key)

Removes the value for the specified id and key.

Parameters:

id - A resource ID.

key - A key under which info is stored.

removeReferredID

void removeReferredID(String id,
                      String referredID)

Removes a reference relationship between two resources.

Parameters:

id - The referring resource's ID.

referredID - The referred resource's ID.

removeReferredIDs

void removeReferredIDs(String id)

Removes all referred IDs of a resource.

Parameters:

id - The referring resource's ID.

remove

void remove(String id)

Removes all information about the resource with the specified ID.

Specifically:

• Remove all keys and values pertaining to that ID
• Remove all links between this id and all id's it refers to
• Remove the aggregation link "upwards" to the parent id
• Remove recursively all aggregated id's

Note that this method does NOT remove ids this id is referred BY. I.e. it does remove "outgoing" referredID links but it does NOT remove "incomming" referred ID's. To be on the safe side - the crawler should take care about this by itself.

Parameters:

id - A resource ID.

putAggregatedID

void putAggregatedID(String id,
                     String aggregatedID)

Puts a link between the given id and the aggregated ID. The aggregated ID will appear in the aggregation closure (returned by getAggregatedIDsClosure(String)), will be touched by the touchRecursively(String) method, it will be removed if the id is removed (@link remove(String)). Note that the aggregation graph must not contain cycles, each id can have at most one parent, the implementations are expected to enforce this. If the aggregatedID had a parent before, the previous link will be removed.

Parameters:

id - the parent id

aggregatedID - the aggregated id

removeAggregatedID

void removeAggregatedID(String id,
                        String aggregatedID)

Removes the link between the given id and the aggregated ID. After a call to this method, the aggregated ID will not appear in the aggregation closure (getAggregatedIDsClosure(String) and will not be touched by the touchRecursively(String) method. A call to remove the id will not remove the aggregated id.

Parameters:

id -

aggregatedID -

getAggregatedIDs

Set getAggregatedIDs(String id)

Returns a set of id's that are aggregated immediately below the given one.

Parameters:

id -

Returns:

a set of id's that are aggregated immediately below the given one.

getAggregatedIDsClosure

ClosableIterator getAggregatedIDsClosure(String id)

Returns an iterator over all ids aggregated within the given one, both directly and indirectly. The iterator will traverse the entire aggregation subtree beginning with the given id.

Parameters:

id - the id whose aggregation subtree is to be traversed

Returns:

an iterator over the aggregation subtree

touch

void touch(String id)

Touches an id. This id will not appear on the list returned by getUntouchedIDsIterator() and will not be removed by removeUntouchedIDs()

Parameters:

id -

isTouched

boolean isTouched(String id)

Returns true if this id is known and has been touched since the last call to initialize(), false if the id is not known, or hasn't been touched since the last call to initialize().

Parameters:

id - the id to check

Returns:

true if the id has been touched, false if not

touchRecursively

void touchRecursively(String id)

Recursively touches all ids within the aggregation subtree beginning with the given id

Parameters:

id -

getUntouchedIDsIterator

ClosableIterator getUntouchedIDsIterator()

Returns an iterator over all ID's in this access data instance that have not been touched since the last call to initialize()

Returns:

an iterator over all untouched IDs

removeUntouchedIDs

void removeUntouchedIDs()

Removes all untouched IDS