Package com.polarion.alm.builder

Interface IWatchableRepository

All Known Subinterfaces:

IBuildInformationRepository

public interface IWatchableRepository

Repository which can be watched by IWatchableRepositoryListeners.

Interface is created so as implementations can do as less work as possible:

• changes made directly in underlying storage may be omitted (clients should treat such repositories as other repositories and do not make change detection themselves
• multiple reporting of same change is permitted
• reporting of changes out-of-order is permitted
• changes to file resource which must be reported: creation, removal, content modification (change of any attribute which does not affect file content, like last modification time, can be omitted)
• changes to folder resource which must be reported: creation, removal
• changes to folder contents may or may not be reported as folder changes, but generally are not reported (= creation of file does not trigger change of its parent folder nor does it travel upwards)
• reporting of changes which are not visible by clients are permitted (e.g. file owner is changed, but repository does not allow to retrieve such information)

There are only two rules which must be obeyed:

• changes done through repository interface must be reported synchronously
• listener will be notified only with locations which match locations and location patterns register for watching

Location patterns can be used: if location contains asterisk (*; COMPONENT_MATCH_ALL) instead of some path component, then it will match any file or folder (on that hierarchy level).

WARNING: In cluster setup listeners are notified only on the node where the changes are done.

Author:

Stepan Roh, Polarion Software

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	IWatchableRepository.ILocationWithTime	ILocation with last modification time.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	COMPONENT_MATCH_ALL	location component which matches all files and folders - asterisk (*)

Method Summary

Modifier and Type	Method	Description
void	addWatchableRepositoryListener(IWatchableRepositoryListener l, Collection locations)	Add IWatchableRepositoryListener to watch specified locations.
void	removeWatchableRepositoryListener(IWatchableRepositoryListener l)	Remove IWatchableRepositoryListener from watching all locations.
void	removeWatchableRepositoryListener(IWatchableRepositoryListener l, Collection locations)	Remove IWatchableRepositoryListener from watching specified locations.
void	stuffWatchableRepositoryListener(IWatchableRepositoryListener l, Collection locations, long lastKnownModificationTime)	Collect all changes on given locations and stuff the IWatchableRepositoryListener with them.

Field Details

COMPONENT_MATCH_ALL

static final String COMPONENT_MATCH_ALL

location component which matches all files and folders - asterisk (*)

See Also:

• Constant Field Values

Method Details

addWatchableRepositoryListener

void addWatchableRepositoryListener(IWatchableRepositoryListener l,
 Collection locations)

Add IWatchableRepositoryListener to watch specified locations.

If given set of locations is empty, then does nothing.

If listener was already added, its registered set of locations is merged with given set.

Parameters:

l - listener

locations - Collection of ILocations

Throws:

IllegalArgumentException - if locations is null

IllegalArgumentException - if l is null

IllegalArgumentException - if some location is relative

removeWatchableRepositoryListener

void removeWatchableRepositoryListener(IWatchableRepositoryListener l,
 Collection locations)

Remove IWatchableRepositoryListener from watching specified locations.

If given set of locations is empty, then does nothing.

If given listener's registered set of locations contains only given locations, then listener is removed altogether.

It is permitted to pass locations which are not in listener's registered set of locations.

It is permitted to request removal of listener which was already removed.

Parameters:

l - listener

locations - Collection of ILocations

Throws:

IllegalArgumentException - if locations is null

IllegalArgumentException - if l is null

IllegalArgumentException - if some location is relative

removeWatchableRepositoryListener

void removeWatchableRepositoryListener(IWatchableRepositoryListener l)

Remove IWatchableRepositoryListener from watching all locations.

It is permitted to request removal of listener which was already removed.

Parameters:

l - listener

Throws:

IllegalArgumentException - if l is null

stuffWatchableRepositoryListener

void stuffWatchableRepositoryListener(IWatchableRepositoryListener l,
 Collection locations,
 long lastKnownModificationTime)

Collect all changes on given locations and stuff the IWatchableRepositoryListener with them. If last modification time is given then only newer changes are reported.

Listener is called synchronously and after it is stuffed with all changes method will return. Listener may be called any number of times (changes may come in one large chunk or in many smaller ones).

Note that file or folder removal might not be reported (depends on repository).

If IWatchableRepository.ILocationWithTime is used then it's IWatchableRepository.ILocationWithTime.getLastModificationTime() is used as a reference time (if not set to zero, in which case given last modification time is used instead) and location is treated as if it should exist.

Parameters:

l - listener

locations - Collection of ILocations and IWatchableRepository.ILocationWithTimes

lastKnownModificationTime - last modification time of known changes (exclusive; use 0 for indication that every change is wanted)

Throws:

IllegalArgumentException - if locations is null

IllegalArgumentException - if l is null

IllegalArgumentException - if some location is relative