org.electrocodeogram.cpc.core.api.provider.classification
Interface IClassificationProvider

All Superinterfaces:

IProvider

public interface IClassificationProvider
extends IProvider

The CPC API for clone classification providers.
A classification provider takes a clone objects, analyses it and attaches a number of classifications to it.
Classifications are Strings which usually correspond to the CLASSIFICATION_* constants of this class.

3rd parties may add their own classification strings. Such strings need to have a globally unique prefix to prevent collisions with other classifications.
The prefix "cpc." is reserved for the default CPC classifiers.
Classification strings may only contain letters, numbers and dots. Classification strings are case sensitive.

Author:

vw

See Also:

IClone.hasClassification(String), IClone.getClassifications(), IClone.addClassification(String), IClone.removeClassification(String)

Nested Class Summary

static class	IClassificationProvider.Result Possible results of the classify(Type, ICloneFile, IClone, String, IClone) method.
static class	IClassificationProvider.Type Specifies the type of classification to be performed.

Field Summary

static java.lang.String	CLASSIFICATION_CLASS The clone contains at least one complete java class.
static java.lang.String	CLASSIFICATION_COMMENT The clone contains only comments and whitespaces or a part of a comment.
static java.lang.String	CLASSIFICATION_COMPLEX The clone contains potentially complex code.
static java.lang.String	CLASSIFICATION_CONDITION The clone contains at least one complete java condition block.
static java.lang.String	CLASSIFICATION_IDENTIFIER The clone contains a complete identifier and nothing else.
static java.lang.String	CLASSIFICATION_LOOP The clone contains at least one complete loop construct.
static java.lang.String	CLASSIFICATION_METHOD The clone contains at least one complete java method.
static java.lang.String	CLASSIFICATION_TEMPLATE The clone contains is probably a template code fragment.

Method Summary

IClassificationProvider.Result

classify(IClassificationProvider.Type type, ICloneFile cloneFile, IClone clone, java.lang.String fileContent, IClone originClone) Takes a clone object and passes it to all registered classification strategies to decide on the correct classifications.

Methods inherited from interface org.electrocodeogram.cpc.core.api.provider.IProvider

getProviderName, toString

Field Detail

CLASSIFICATION_CLASS

static final java.lang.String CLASSIFICATION_CLASS

The clone contains at least one complete java class.

See Also:

Constant Field Values

CLASSIFICATION_METHOD

static final java.lang.String CLASSIFICATION_METHOD

The clone contains at least one complete java method.

See Also:

Constant Field Values

CLASSIFICATION_LOOP

static final java.lang.String CLASSIFICATION_LOOP

The clone contains at least one complete loop construct.

See Also:

Constant Field Values

CLASSIFICATION_CONDITION

static final java.lang.String CLASSIFICATION_CONDITION

The clone contains at least one complete java condition block.
I.e. a complete "if () { ... } else { ... }" construct.

See Also:

Constant Field Values

CLASSIFICATION_IDENTIFIER

static final java.lang.String CLASSIFICATION_IDENTIFIER

The clone contains a complete identifier and nothing else. Whitespaces and comments are ignored.

See Also:

Constant Field Values

CLASSIFICATION_COMMENT

static final java.lang.String CLASSIFICATION_COMMENT

The clone contains only comments and whitespaces or a part of a comment.

See Also:

Constant Field Values

CLASSIFICATION_COMPLEX

static final java.lang.String CLASSIFICATION_COMPLEX

The clone contains potentially complex code.
A clone should be tagged with this classification if it seems likely that the clone is non-trivial and that any update anomalies inside such a clone are potentially interesting candidates for CPC Warnings.

See Also:

Constant Field Values

CLASSIFICATION_TEMPLATE

static final java.lang.String CLASSIFICATION_TEMPLATE

The clone contains is probably a template code fragment.
Clones of this kind can be similar to each other, but the underlying semantics are usually not related.
This classification should only be set, if there is a high probability that the decision is correct. Other modules may base their decisions on this fact. I.e. CPC Notify may decide to ignore a clone modification if this classification is set.
However, if it is absolutely clear that there is no point in tracking this clone at all. The classification provider should return a IClassificationProvider.Result.REJECTED result.

See Also:

Constant Field Values

Method Detail

classify

IClassificationProvider.Result classify(IClassificationProvider.Type type,
                                        ICloneFile cloneFile,
                                        IClone clone,
                                        java.lang.String fileContent,
                                        IClone originClone)

Takes a clone object and passes it to all registered classification strategies to decide on the correct classifications.

The new classifications are directly added to the clones classifications data structure (the clone object is updated in place).
It is up to the specified type and the implementation how existing classification are handled.

Providing the file content is optional, however, if it is already present for some reason, it should be provided to reduce load.

A classification provider may try to obtain additional information for the corresponding file from the Eclipse environment, if it is running. I.e. a classification provider may try to obtain the AST for a Java class.
It is up to the classification provider implementation whether to make use of any such additional information or not.

Parameters:

type - the type of classification to be performed, never null.

cloneFile - the clone file which contains the given clone, never null.

clone - the clone to classify, never null.

fileContent - current content of the file this clone is located in, may be NULL in which case the content will be retrieved from an open editor or the filesystem, when needed.

originClone - optional reference to the IClone which the given clone was copied from. This will usually only be available for IClassificationProvider.Type.INITIAL calls and even then it is optional. May be NULL.

Returns:

the general classification result IClassificationProvider.Result, never null.