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 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 NumberMetric<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