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.

Author:
Clément Fournier
Since:
6.0.0

  • Method Details

    • 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<? super 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:
      T - Type of node the metric can be computed on
      R - Return type of the metric
      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