org.electrocodeogram.cpc.core.api.data
Interface IClone

All Superinterfaces:

java.lang.Cloneable, java.lang.Comparable<IClone>, org.eclipse.core.runtime.IAdaptable, ICloneDataElement, ICloneObject, java.io.Serializable

All Known Subinterfaces:

ICloneInterfaces, ICreatorClone

public interface IClone
extends java.lang.Comparable<IClone>, ICloneObject

Public interface for all clone data objects.

This interface lists all methods which are available to all CPC plug-ins and 3rd party contributions.

Additional methods are defined by more specific sub-interfaces which belong to individual CPC plugins and are to be considered private.
Any CPC plugin other than the one designated in the sub-interface API must not access such methods.

Any implementation needs to implement ICloneInterfaces. Implementing only IClone is not enough!

Author:

vw

See Also:

ICloneInterfaces, ICloneFactoryProvider

Nested Class Summary

static class

IClone.State Specifies the state of a clone.

Field Summary

static java.lang.String

PERSISTENCE_CLASS_IDENTIFIER IStatefulObject persistence class identifier, value: "clone"

Fields inherited from interface org.electrocodeogram.cpc.core.api.data.ICloneObject

PERSISTENCE_OBJECT_IDENTIFIER

Method Summary

void	addClassification(java.lang.String classification) Adds the given classification string to this clone.
int	compareTo(IClone o) This is a somewhat tricky implementation of compareTo().
java.util.Collection<java.lang.String>	getClassifications() Returns a collection with all classifications of this clone.
IClone.State	getCloneState() Retrieves the IClone.State of this clone instance.
java.util.Date	getCloneStateChangeDate() Retrieves the date of the last modification to this clone's IClone.State.
java.util.Date	getCloneStateDismissalDate() Retrieves the date of the last dismissal of a cpc notification for this clone by the user.
java.lang.String	getCloneStateMessage() Retrieves an optional message which contains the rationale for the current clone state of this clone.
double	getCloneStateWeight() Retrieves the weight of the current clone state of this clone.
java.lang.String	getContent() Retrieves the current content of this clone.
java.util.Date	getCreationDate() Retrieves the creation date of this clone.
java.lang.String	getCreator() Retrieves the creator (username) of this clone.
int	getEndOffset() Returns the offset of the last character which is still part of this clone.
java.lang.String	getFileUuid() Retrieves the UUID for the clone file in which this clone is located.
java.lang.String	getGroupUuid() Retrieves the UUID of the clone group which this clone belongs to.
int	getLength() Retrieves the length of this clone.
java.util.Date	getModificationDate() Retrieves the date of the last modification to this clone's content.
int	getOffset() Retrieves the offset of the first character which is part of this clone.
java.lang.String	getOriginalContent() Retrieves the original content of this clone at the time of its creation.
java.lang.String	getOriginUuid() Retrieves the origin clone from which this clone was copied.
boolean	hasClassification(java.lang.String classification) Checks whether this clone possesses the given classification.
boolean	intersects(IClone clone) Checks whether two clone positions intersect.
boolean	intersects(int offset, int length) Checks whether this clone intersect with the given range.
boolean	isTransient() Whether this clone instance should be persisted or not.
void	removeClassification(java.lang.String classification) Removes the given classification from this clone.
void	setCloneState(IClone.State cloneState, double weight, java.lang.String message) Sets the IClone.State of this clone instance.
void	setGroupUuid(java.lang.String groupUuid) Sets the UUID of the clone group which this clone belongs to.
void	setLength(int length) Sets the length of this clone.
void	setOffset(int offset) Sets the offset of the first character which is part of this clone.
void	setOriginUuid(java.lang.String originUuid) Sets the origin clone for this clone.
void	setTransient(boolean _transient) Specifies whether this clone instance should be persisted or not.

Methods inherited from interface org.electrocodeogram.cpc.core.api.data.ICloneObject

addExtension, clone, equals, equalsAll, getExtension, getExtensions, getUuid, hasExtensions, hashCode, isMarked, removeExtension, removeExtension, setMarked, toString

Methods inherited from interface org.electrocodeogram.cpc.core.api.data.ICloneDataElement

isSealed, seal

Methods inherited from interface org.eclipse.core.runtime.IAdaptable

getAdapter

Field Detail

PERSISTENCE_CLASS_IDENTIFIER

static final java.lang.String PERSISTENCE_CLASS_IDENTIFIER

IStatefulObject persistence class identifier, value: "clone"

See Also:

Constant Field Values

Method Detail

getCreationDate

java.util.Date getCreationDate()

Retrieves the creation date of this clone.

Returns:

creation date, never null.

getCreator

java.lang.String getCreator()

Retrieves the creator (username) of this clone.
This value may be null if the creator could not be determined.

Returns:

creator of this clone, may be NULL.

getFileUuid

java.lang.String getFileUuid()

Retrieves the UUID for the clone file in which this clone is located.

Returns:

clone file uuid, never null.

getOffset

int getOffset()

Retrieves the offset of the first character which is part of this clone.

Returns:

the character offset to the beginning of the file at which the clone begins, inclusive, first char is 0.

setOffset

void setOffset(int offset)

Sets the offset of the first character which is part of this clone.

Parameters:

offset - the character offset to the beginning of the file at which the clone begins, inclusive, first char is 0.

See Also:

getOffset()

getLength

int getLength()

Retrieves the length of this clone.
A clone can't have length 0.

Returns:

length in characters, never <=0.

setLength

void setLength(int length)

Sets the length of this clone.

Parameters:

length - the length in characters, never <=0.

See Also:

getLength()

getGroupUuid

java.lang.String getGroupUuid()

Retrieves the UUID of the clone group which this clone belongs to.
Initially a clone belongs to no group, in which case this value is NULL.
As long as a clone is a member of a clone group, this value is non-NULL.

Returns:

clone group for this clone, if any, may be NULL

setGroupUuid

void setGroupUuid(java.lang.String groupUuid)

Sets the UUID of the clone group which this clone belongs to.

Parameters:

groupUuid - the clone group for this clone, if any, may be NULL

See Also:

getGroupUuid()

getOriginUuid

java.lang.String getOriginUuid()

Retrieves the origin clone from which this clone was copied.
May be null if this clone has no origin (i.e. it is only the source for other clones).
A clone's origin may also be deleted, in which case this value is reset to NULL.

Returns:

uuid of the origin clone of this clone or NULL if no origin exists.

setOriginUuid

void setOriginUuid(java.lang.String originUuid)

Sets the origin clone for this clone.
This method is usually only used during the creation of the clone but may be used again at a later point to reset the origin uuid to NULL in case the origin clone was deleted.

Parameters:

originUuid - uuid of the origin clone, may be NULL.

getClassifications

java.util.Collection<java.lang.String> getClassifications()

Returns a collection with all classifications of this clone.
All elements of the collection are unique, there are no NULL elements.

NOTE: The returned collection may not be modified in any way. It may or may not be backed by the internal classification data structure. A client who wants to iterate over the set while the clone might be concurrently modified, should create its own shallow copy.

Refer to the CLASSIFICATION_* constants in IClassificationProvider for more information.

Returns:

classification of this clone, collection must not be modified, never null.

See Also:

IClassificationProvider

hasClassification

boolean hasClassification(java.lang.String classification)

Checks whether this clone possesses the given classification.

Refer to the CLASSIFICATION_* constants of the IClassificationProvider for more information.

Parameters:

classification - the classification to check for, never null.

Returns:

true if the clone has that classification, false otherwise.

See Also:

IClassificationProvider

addClassification

void addClassification(java.lang.String classification)

Adds the given classification string to this clone.
Multiple additions of the same string have no effect.

Refer to the CLASSIFICATION_* constants of the IClassificationProvider for more information.

Parameters:

classification - the classification string to add, never null.

See Also:

IClassificationProvider

removeClassification

void removeClassification(java.lang.String classification)

Removes the given classification from this clone.
Has no effect if the clone did not possess the classification.

Refer to the CLASSIFICATION_* constants of the IClassificationProvider for more information.

Parameters:

classification - the classification string to remove, never null.

See Also:

IClassificationProvider

getOriginalContent

java.lang.String getOriginalContent()

Retrieves the original content of this clone at the time of its creation.
Calling this method may be expensive as contents may be lazy loaded.

Returns:

original content of clone, never null.

getContent

java.lang.String getContent()

Retrieves the current content of this clone.
Calling this method may be expensive as contents may be lazy loaded.

Returns:

current content of clone, never null.

getModificationDate

java.util.Date getModificationDate()

Retrieves the date of the last modification to this clone's content.
Initially this value matches the getCreationDate().

Returns:

modification date, never null.

getCloneState

IClone.State getCloneState()

Retrieves the IClone.State of this clone instance.

Returns:

current state of this clone, never null.

getCloneStateChangeDate

java.util.Date getCloneStateChangeDate()

Retrieves the date of the last modification to this clone's IClone.State.
This value is automatically updated to the current time, whenever the clone state is modified.
Initially this value matches the getCreationDate().

Returns:

date of last state change, never null.

See Also:

setCloneState(State, double, String)

getCloneStateDismissalDate

java.util.Date getCloneStateDismissalDate()

Retrieves the date of the last dismissal of a cpc notification for this clone by the user.
The date can be used to retrieve the clone content from the history at the point in time where the notification was dismissed.
In most cases this value will be NULL.

Returns:

date of last dismissal of a cpc notification, may be NULL.

getCloneStateWeight

double getCloneStateWeight()

Retrieves the weight of the current clone state of this clone.
This value only has a meaning for the states IClone.State.NOTIFY and IClone.State.WARN. Otherwise the value is 0.

Returns:

the weight of the current clone state, 0 if the state is neither IClone.State.NOTIFY nor IClone.State.WARN.

See Also:

IEvaluationResult.getWeight()

getCloneStateMessage

java.lang.String getCloneStateMessage()

Retrieves an optional message which contains the rationale for the current clone state of this clone.
This value is only defined for the states IClone.State.NOTIFY and IClone.State.WARN. However, the value is optional and can be NULL at any time.
For all other states the value is always NULL.

This value is displayed to the user and should therefore be human readable and localised.

Returns:

human readable reason behind the current clone state, this value may be NULL if no reason was given or if the clone state is neither IClone.State.NOTIFY nor IClone.State.WARN.

setCloneState

void setCloneState(IClone.State cloneState,
                   double weight,
                   java.lang.String message)

Sets the IClone.State of this clone instance.
A call to this method will also update getCloneStateChangeDate().

Parameters:

cloneState - new state for this clone, never null.

weight - weight of the new state. This value only has a meaning for states IClone.State.NOTIFY and IClone.State.WARN and should be 0 for all others.

message - optional human readable reason behind the new clone state. This value should only be defined for states IClone.State.NOTIFY and IClone.State.WARN (even then it may be NULL) and should be NULL for all other states.

See Also:

getCloneState(), getCloneStateChangeDate(), getCloneStateWeight(), getCloneStateMessage()

isTransient

boolean isTransient()

Whether this clone instance should be persisted or not.
IClone instances may be created for temporary use, i.e. to keep track of the source for CutCopyPaste actions. Such transient IClone instances must be tracked like normal instances (their position can change due to modifications to the file), however they are not yet part of any clone group and are therefore not real clones. Such transient instances must not be persisted.

Returns:

true if this clone should not yet be persisted, false otherwise.

setTransient

void setTransient(boolean _transient)

Specifies whether this clone instance should be persisted or not.

Parameters:

_transient - true if this clone should not yet be persisted, false otherwise.

See Also:

isTransient()

getEndOffset

int getEndOffset()

Returns the offset of the last character which is still part of this clone.
Use setOffset(int) and setLength(int) to modify this value.
Convenience method.

Returns:

offset + length - 1

intersects

boolean intersects(IClone clone)

Checks whether two clone positions intersect.
Convenience method.

Parameters:

clone - the other clone to compare against, never null.

Returns:

true if the two position ranges have at least one character in common, false otherwise.

intersects

boolean intersects(int offset,
                   int length)

Checks whether this clone intersect with the given range.
Convenience method.

Parameters:

offset - start offset, 0-based character count, always >= 0.

length - length in characters, always >= 0. A length of 0 is handled like a length of 1 (endOffset=offset). Which means a 0-length range may intersect with another range.

Returns:

true if the two position ranges have at least one character in common, false otherwise.

compareTo

int compareTo(IClone o)

This is a somewhat tricky implementation of compareTo().
By contract this.compareTo(o) == 0 must always yield the same result as this.equals(o).

However, we're ordering by start line, start offset, end offset here.
Two clones which are not equal may well start at the same line/offset.
If this happens some extra code tries to resolve the issue by putting one of the clones first and the other one second.

Specified by:

compareTo in interface java.lang.Comparable<IClone>