Package net.sourceforge.pmd.lang.metrics

Interface Metric<N extends Node,R extends Number>

Type Parameters:

N - Type of nodes the metric can be computed on

R - Result type of the metric

All Superinterfaces:

DataMap.DataKey<Metric<N,R>,R>

public interface Metric<N extends Node,R extends Number>
extends DataMap.DataKey<Metric<N,R>,R>

A named computation that can be carried out on some nodes. Example include complexity metrics, like cyclomatic complexity.

Use with MetricsUtil, for example, in the Java module:

   if (JavaMetrics.CYCLO.supports(node)) {
     int cyclo = MetricsUtil.computeMetric(JavaMetrics.CYCLO, node);
     ...
   }
 

Note that the supports check is necessary (metrics cannot necessarily be computed on any node of the type they support).

Metrics support a concept of options, which can be passed to compute or MetricsUtil.computeMetric(Metric, Node, MetricOptions).

Metric instances are stateless by contract.

To implement your own metrics, use the factory method of. Be aware though, that you cannot register a custom metric into a LanguageMetricsProvider, which means your metric will not be available from XPath.

Since:

6.0.0

Author:

Clément Fournier

Method Summary

Modifier and Type	Method	Description
@Nullable N	castIfSupported(@NonNull Node node)	Casts the node to the more specific type <N> if this metric can be computed on it.
static <N extends Node,R extends Number> @Nullable R	compute(Metric<N,R> metric, Node node, MetricOptions options)	Compute a metric on an arbitrary node, if possible.
R	computeFor(N node, MetricOptions options)	Computes the value of the metric for the given node.
String	displayName()	The full name of the metric.
List<String>	nameAliases()	List of name aliases by which the metric is recognisable.
static <T extends Node,R extends Number> Metric<T,R>	of(BiFunction<? super T,MetricOptions,? extends R> compute, Function<Node,? extends @Nullable T> cast, @NonNull String fullName, String... aliases)	Factory method for a metric.
default boolean	supports(Node node)	Checks if the metric can be computed on the node.

Method Detail

displayName

String displayName()

The full name of the metric. This is the preferred name for displaying. Avoid using abbreviations.

nameAliases

List<String> nameAliases()

List of name aliases by which the metric is recognisable. This list includes the displayName() of the metric. These are typically an acronym for the display name, or some such mnemonic.

supports

default boolean supports(Node node)

Checks if the metric can be computed on the node.

Parameters:

node - The node to check

Returns:

True if the metric can be computed

Throws:

NullPointerException - If the parameter is null

castIfSupported

@Nullable N castIfSupported(@NonNull Node node)

Casts the node to the more specific type <N> if this metric can be computed on it. Returns null if the node is not supported.

Parameters:

node - An arbitrary node

Returns:

The same node, if it is supported

Throws:

NullPointerException - If the parameter is null

computeFor

R computeFor(N node,
             MetricOptions options)

Computes the value of the metric for the given node. Behavior if the node is unsupported (castIfSupported(Node)) is undefined: the method may throw, return null, or return a garbage value. For that reason the node should be tested beforehand.

Parameters:

node - The node

options - The options of the metric

Returns:

The value of the metric, or null if it could not be computed.

Throws:

NullPointerException - if either parameter is null

of

static <T extends Node,R extends Number> Metric<T,R> of(BiFunction<? super T,MetricOptions,? extends R> compute,
                                                                    Function<Node,? extends @Nullable T> cast,
                                                                    @NonNull String fullName,
                                                                    String... aliases)

Factory method for a metric. The returned instance does not override equals/hashcode.

Type Parameters:

R - Return type of the metric

T - Type of node the metric can be computed on

Parameters:

compute - Implementation for computeFor(Node, MetricOptions) (a pure function).

cast - Implementation for castIfSupported(Node) (a pure function).

fullName - The full name of the metric

aliases - Aliases for the name

Returns:

The metric key

Throws:

NullPointerException - If either parameter is null

compute

static <N extends Node,R extends Number> @Nullable R compute(Metric<N,R> metric,
                                                                   Node node,
                                                                   MetricOptions options)

Compute a metric on an arbitrary node, if possible. This is useful in situations where N is unknown. The result is not cached on the node.

Type Parameters:

N - Type of nodes the metric supports

R - Return type

Parameters:

metric - Metric

node - Node

options - Options for the metric

Returns:

Null if the node is unsupported, otherwise the result of the metric.

Throws:

NullPointerException - if any of the parameters is null