Enum Class DetectorTrust.Evidence

java.lang.Object
java.lang.Enum<DetectorTrust.Evidence>
se.deversity.asynctest.diagnostics.DetectorTrust.Evidence
All Implemented Interfaces:
Serializable, Comparable<DetectorTrust.Evidence>, Constable
Enclosing class:
DetectorTrust

@API(status=EXPERIMENTAL, since="1.12.3") public static enum DetectorTrust.Evidence extends Enum<DetectorTrust.Evidence>
What a detector decides a finding from, which bounds the tier that finding can carry.

Why this exists. TrustTier.VERDICT used to need only a both-directions case: fire on the bug, stay silent on the correct twin. A detector whose finding is the test author's own record* call meets that rule by construction, since the buggy body makes the call and the correct one does not; so does a detector that counts threads or compares a number with a threshold, given a pair chosen on the right side of it. ExecutorDeadlockDetector reached VERDICT at CRITICAL severity that way while its finding was a lifetime counter of recorded sibling waits. A pair shows that a detector separates two bodies; this class says whether what separates them is the code or the recording, and cap() is the most a finding decided that way can claim.

DetectorTrustCoverageTest fails the build on a row whose tier exceeds its class's cap. For a report that grades its findings the cap is also applied at run time: the report path lowers any GradedFindings.Grade above its detector's cap to the cap before the gate, the banner or a listener sees it.

A detector that decides differently on different paths is classified by its weakest path, because the row's tier applies to every finding it makes. A report that implements GradedFindings is the exception: each of its findings carries its own tier and names the evidence of the path that produced it (GradedFindings.Grade.evidence()), so its class is the one behind its strongest grade, and the clamp keeps every grade at or below both that class's cap and the cap of the evidence it names.

Since:
1.12.3
  • Nested Class Summary

    Nested classes/interfaces inherited from class java.lang.Enum

    Enum.EnumDesc<E extends Enum<E>>
  • Enum Constant Summary

    Enum Constants
    Enum Constant
    Description
    The finding is essentially the recorded call itself: a call named after the defect, a flag argument, or arithmetic over declared events with nothing else consulted.
    Recorded accesses judged by "more than one thread touched it", with no lock or ordering context.
    Decided from recorded accesses, and only after consulting synchronization context the detector can see: the per-round lockset SelfGuard keeps, locks declared through HeldLocks, or a happens-before or ownership edge.
    A timing threshold, a ratio or a count.
    Decided from the real JVM object or thread: the detector asks the lock, barrier, queue or thread for its state, or reads events the agent wove into the bytecode.
  • Method Summary

    Modifier and Type
    Method
    Description
    cap()
    Returns the highest tier a finding decided from this kind of evidence may carry.
    Returns the enum constant of this class with the specified name.
    Returns an array containing the constants of this enum class, in the order they are declared.

    Methods inherited from class java.lang.Object

    getClass, notify, notifyAll, wait, wait, wait
  • Enum Constant Details

    • OBSERVED

      public static final DetectorTrust.Evidence OBSERVED
      Decided from the real JVM object or thread: the detector asks the lock, barrier, queue or thread for its state, or reads events the agent wove into the bytecode. The finding does not rest on the test describing its own code correctly.
    • CONTEXTUAL

      public static final DetectorTrust.Evidence CONTEXTUAL
      Decided from recorded accesses, and only after consulting synchronization context the detector can see: the per-round lockset SelfGuard keeps, locks declared through HeldLocks, or a happens-before or ownership edge. The same accesses recorded under a visible lock stay silent. Splitting the run into invocation rounds is not such context on its own: two threads that touched something in one round are still just two threads, which is CONTEXT_FREE.
    • ASSERTED

      public static final DetectorTrust.Evidence ASSERTED
      The finding is essentially the recorded call itself: a call named after the defect, a flag argument, or arithmetic over declared events with nothing else consulted. The report is true about what was recorded; that the recording matches the code is the test author's claim, so the most it can be is a TrustTier.FACT.
    • CONTEXT_FREE

      public static final DetectorTrust.Evidence CONTEXT_FREE
      Recorded accesses judged by "more than one thread touched it", with no lock or ordering context. Correct code sharing the object under a lock draws the same finding, so it is a TrustTier.PROMPT at most.
    • HEURISTIC

      public static final DetectorTrust.Evidence HEURISTIC
      A timing threshold, a ratio or a count. A number crossing a line says something may be wrong, never that it is, so it is a TrustTier.PROMPT at most.
  • Method Details

    • values

      public static DetectorTrust.Evidence[] values()
      Returns an array containing the constants of this enum class, in the order they are declared.
      Returns:
      an array containing the constants of this enum class, in the order they are declared
    • valueOf

      public static DetectorTrust.Evidence valueOf(String name)
      Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)
      Parameters:
      name - the name of the enum constant to be returned.
      Returns:
      the enum constant with the specified name
      Throws:
      IllegalArgumentException - if this enum class has no constant with the specified name
      NullPointerException - if the argument is null
    • cap

      public TrustTier cap()
      Returns the highest tier a finding decided from this kind of evidence may carry.
      Returns:
      the highest tier a finding decided from this kind of evidence may carry