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 onR
- 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
orMetricsUtil.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 aLanguageMetricsProvider
, which means your metric will not be available from XPath.- Since:
- 6.0.0
- Author:
- Clément Fournier
-
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Default Methods 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 Rcompute(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 thedisplayName()
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 nodeoptions
- 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 metricT
- Type of node the metric can be computed on- Parameters:
compute
- Implementation forcomputeFor(Node, MetricOptions)
(a pure function).cast
- Implementation forcastIfSupported(Node)
(a pure function).fullName
- The full name of the metricaliases
- 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 whereN
is unknown. The result is not cached on the node.- Type Parameters:
N
- Type of nodes the metric supportsR
- Return type- Parameters:
metric
- Metricnode
- Nodeoptions
- 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
-
-