org.electrocodeogram.cpc.core.api.hub.event
Class CloneModificationEvent

java.lang.Object
  org.electrocodeogram.cpc.core.api.hub.event.CPCEvent
      org.electrocodeogram.cpc.core.api.hub.event.CloneEvent
          org.electrocodeogram.cpc.core.api.hub.event.CloneModificationEvent

All Implemented Interfaces:

java.lang.Cloneable, java.lang.Comparable<CPCEvent>

public class CloneModificationEvent
extends CloneEvent

Modification event object for clone data modifications. Send whenever the clone data for a file is changed for some reason.

NOTE:

• All values MAY BE NULL
• The same clone may be contained in more than one of the lists.
• This event represents a collection of all events which happened during one IStoreProvider "transaction". As such a clone may appear multiple times in different stages. I.e. it was added, moved and modified within a single transaction. If a clone was updated multiple times, it will be listed only once in the modified and moved clones lists (the latest version).
• A clone that is part of the deleted list, will not appear in any other list.
• If all clone data for a large number of files (or all clone data) is removed/updated a special format may be used.
  CloneEvent.getCloneFile() is NULL, isFullModification() is true and all clone lists are NULL.
• All objects contained in this event are cloned. Thus instances of the same clone will not match between different lists. Use equals() to compare clone objects, not ==.
• The clone objects must not be modified by a receiver. They are shared between all receivers of this event.

IMPORTANT: Make sure you understand the effects of the IStoreProvider.LockMode value during the acquisition of an exclusive IStoreProvider lock before you create any events of this type yourself.

Author:

vw

See Also:

IStoreProvider, IStoreProvider.LockMode, IStoreProvider.UpdateMode, IStoreProvider.acquireWriteLock(org.electrocodeogram.cpc.core.api.provider.store.IStoreProvider.LockMode), IStoreProvider.releaseWriteLock()

Field Summary

protected java.util.List<IClone>	addedClones
protected boolean	fullModification
protected java.util.List<IClone>	modifiedClones
protected java.util.List<IClone>	movedClones
protected java.util.List<IClone>	removedClones

Constructor Summary

CloneModificationEvent(ICloneFile cloneFile)
Creates a new CloneModificationEvent instance for dispatching via the event hub registry.

Method Summary

java.util.List<IClone>	getAddedClones() A list of clones which were added during this event.
java.util.List<IClone>	getModifiedClones() A list of clones which had their contents changed during this event.
java.util.List<IClone>	getMovedClones() A list of clones which were moved during this event.
java.util.List<IClone>	getRemovedClones() A list of clones which were removed during this event.
boolean	isFullModification() Indicates whether the entire clone data for the file was modified.
boolean	isValid() Checks if this event has been fully initialised.
void	setAddedClones(java.util.List<IClone> addedClones) Must only be called ONCE.
void	setFullModification(boolean fullModification) This may only be set to true if all clone lists of this event are null.
void	setModifiedClones(java.util.List<IClone> modifiedClones) Must only be called ONCE.
void	setMovedClones(java.util.List<IClone> movedClones) Must only be called ONCE.
void	setRemovedClones(java.util.List<IClone> removedClones) Must only be called ONCE.
java.lang.String	toString() Every event should implement a sensible toString method for use in debugging log messages.

Methods inherited from class org.electrocodeogram.cpc.core.api.hub.event.CloneEvent

getCloneFile, subToString

Methods inherited from class org.electrocodeogram.cpc.core.api.hub.event.CPCEvent

checkSeal, clone, compareTo, getCreationTime, seal

Methods inherited from class java.lang.Object

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

Field Detail

fullModification

protected boolean fullModification

addedClones

protected java.util.List<IClone> addedClones

modifiedClones

protected java.util.List<IClone> modifiedClones

movedClones

protected java.util.List<IClone> movedClones

removedClones

protected java.util.List<IClone> removedClones

Constructor Detail

CloneModificationEvent

public CloneModificationEvent(ICloneFile cloneFile)

Creates a new CloneModificationEvent instance for dispatching via the event hub registry.
i.e. CPCCorePlugin.getEventHubRegistry().dispatch(newEvent);

The cloneFile parameter may be NULL, in the special case that this event is meant to indicate to all interested parties that all clone data has been potentially removed/updated.
In this case fullModification has to be true and all lists must be null.

Parameters:

cloneFile - the file for this event, if the event is specific to one file, may be NULL.

See Also:

IEventHubRegistry.dispatch(CPCEvent), CPCCorePlugin.getEventHubRegistry()

Method Detail

isFullModification

public boolean isFullModification()

Indicates whether the entire clone data for the file was modified.
In this case all clone lists are NULL and a receiver should retrieve the latest clone data from the store provider.

This typically happens when:

• a file is reverted to an earlier state
• ...

Returns:

true if this event represents a full modification of the clone data

setFullModification

public void setFullModification(boolean fullModification)

This may only be set to true if all clone lists of this event are null.

Parameters:

fullModification - true if this event represents a full modification of the clone data

See Also:

isFullModification()

getAddedClones

public java.util.List<IClone> getAddedClones()

A list of clones which were added during this event.
They may also be moved and/or modified by the same event!

Returns:

may be NULL

setAddedClones

public void setAddedClones(java.util.List<IClone> addedClones)

Must only be called ONCE.

Parameters:

addedClones - corresponding clone list, never null

See Also:

getAddedClones()

getModifiedClones

public java.util.List<IClone> getModifiedClones()

A list of clones which had their contents changed during this event.
They may also be added and/or moved by the same event!
A clone will not appear more than once within this list. It will only contain the latest version.

Modified clones usually carry an ICloneModificationHistoryExtension object which contains CloneDiff data for all modifications since the last time the clone was part of an CloneModificationEvent.
However, there are some special circumstances under which no modification history data is available for a clone which might have been modified. I.e. if a file is reverted or if a file was externally modified and it is not possible to generate an exact CloneDiff description of the change.

Returns:

may be NULL

See Also:

ICloneModificationHistoryExtension, CloneDiff

setModifiedClones

public void setModifiedClones(java.util.List<IClone> modifiedClones)

Must only be called ONCE.

Parameters:

modifiedClones - corresponding clone list, never null

See Also:

getModifiedClones()

getMovedClones

public java.util.List<IClone> getMovedClones()

A list of clones which were moved during this event.
They may also be added and/or modified by the same event!
A clone will not appear more than once within this list. It will only contain the latest version.

Returns:

may be NULL

setMovedClones

public void setMovedClones(java.util.List<IClone> movedClones)

Must only be called ONCE.

Parameters:

movedClones - corresponding clone list, never null

See Also:

getMovedClones()

getRemovedClones

public java.util.List<IClone> getRemovedClones()

A list of clones which were removed during this event.
Any clone which is part of this list will not appear in any other list.
A clone which was added and removed during a single transaction will not be part of any list.

Returns:

may be NULL

setRemovedClones

public void setRemovedClones(java.util.List<IClone> removedClones)

Must only be called ONCE.

Parameters:

removedClones - corresponding clone list, never null

See Also:

getRemovedClones()

isValid

public boolean isValid()

Description copied from class: CPCEvent

Checks if this event has been fully initialised.
Will return false if one of the mandatory fields of the event has not yet been filled out.

Subclasses should override this method but should never return true. Instead they should delegate to the super class implementation once all validity checks on their level have passed.

The CPCEvent.isValid() implementation always returns true.

Overrides:

isValid in class CPCEvent

Returns:

true if this event is valid, false otherwise.

See Also:

IEventHubRegistry.dispatch(CPCEvent)

toString

public java.lang.String toString()

Description copied from class: CPCEvent

Every event should implement a sensible toString method for use in debugging log messages.

Specified by:

toString in class CPCEvent

Returns:

debug string representation, never null.