# javapathfinder/jpf-core architecture

> Architecture diagram of the GitHub repository javapathfinder/jpf-core, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/javapathfinder/jpf-core
- Repository: https://github.com/javapathfinder/jpf-core

## Overview

##### Project type and purpose
- Java PathFinder (JPF) is an extensible model-checking framework for Java bytecode. It is not a web app or database-backed service, but a standalone CLI tool and library that loads Java class files, interprets or simulates their execution in a custom VM, and systematically explores thread interleavings and state spaces.

##### File structure
- Top-level scripts (bin/) and build configs (build.gradle, settings.gradle, jpf.properties) form the CLI and bootstrap.
- src/main/gov/nasa/jpf: core engine (Config, JPF, JPFClassLoader, Shell, Property, State, VM).
- src/main/gov/nasa/jpf/jvm: classfile reader, bytecode interpreter, InstructionFactory.
- src/main/gov/nasa/jpf/search: state‐space search strategies (DFSearch, RandomSearch, heuristics).
- src/main/gov/nasa/jpf/listener & report: observer plugins and output publishers (ConsolePublisher, XMLPublisher).
- src/peers: native‐method “peers” that replace real JVM native methods.
- src/annotations: Java annotations to mark JPF options, filters, perturbations.
- src/main/fault: fault/injection examples and utilities.
- src/classes: generated annotation proxy classes.
- src/tests & src/examples: test suite and usage examples.

##### README
- Confirms that JPF is a CLI tool that runs on OpenJDK 11, highly plugin-oriented, with extensive wiki and community documentation.

##### Final advice
- Major modules and how they interact without overwhelming with every single class.
- Extension points explicitly.
- Document configuration loading, execution loop, and plugin invocation.
- Remain detailed: break the VM into ClassLoader, Interpreter, InstructionFactory, but group low-level instructions under “Bytecode Interpreter.”

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI & Launcher
    subgraph "CLI & Launcher"
        direction TB
        binScripts["bin/ scripts"]:::cli
        RunJPF["RunJPF"]:::cli
        RunTool["Run"]:::cli
        JPFShellNode["JPFShell"]:::cli
        JPFNode["JPF"]:::cli
    end

    %% Configuration Manager
    subgraph "Configuration Manager"
        direction TB
        ConfigNode["Config"]:::config
        ConfigListener["ConfigChangeListener"]:::config
        JPFProps["jpf.properties"]:::config
    end

    %% Class Loader & Parser
    subgraph "Class Loader & Parser"
        direction TB
        JPFClassLoaderNode["JPFClassLoader"]:::core
        ClassFileReaderNode["ClassFileReader"]:::core
        JVMClassInfoNode["JVMClassInfo"]:::core
        ClassFileNode["ClassFile"]:::core
        JVMPackage["jpf/jvm package"]:::core
    end

    %% Bytecode Interpreter / VM
    subgraph "Bytecode Interpreter / VM"
        direction TB
        InstructionFactory["JVMInstructionFactory"]:::core
        VMNode["VM"]:::core
        SingleVM["SingleProcessVM"]:::core
        MultiVM["MultiProcessVM"]:::core
        VMCore["vm core package"]:::core
    end

    %% Search Engine
    subgraph "Search Engine"
        direction TB
        SearchNode["Search"]:::search
        DFSearchNode["DFSearch"]:::search
        RandomSearchNode["RandomSearch"]:::search
        HeuristicSearchNode["HeuristicSearch"]:::search
        SearchPkg["search package"]:::search
    end

    %% Choice Generation
    subgraph "Choice Generation"
        direction TB
        ChoiceGen["ChoiceGenerator"]:::search
        ThreadChoice["ThreadChoiceFromSet"]:::search
        ChoicePkg["choice package"]:::search
    end

    %% Listener & Plugin Framework
    subgraph "Listener & Plugin Framework"
        direction TB
        JPFListenerNode["JPFListener"]:::plugin
        ListenerAdapterNode["ListenerAdapter"]:::plugin
        ListenerPkg["listener package"]:::plugin
    end

    %% Reporting & Publishing
    subgraph "Reporting & Publishing"
        direction TB
        PublisherNode["Publisher"]:::report
        ConsolePub["ConsolePublisher"]:::report
        XMLPub["XMLPublisher"]:::report
        ReportPkg["report package"]:::report
    end

    %% Native-Peers Layer
    subgraph "Native-Peers Layer"
        direction TB
        PeersDir["src/peers"]:::native
        PeersVM["peers/vm package"]:::native
    end

    %% Utilities & Support
    subgraph "Utilities & Support"
        direction TB
        UtilPkg["util package"]:::util
    end

    %% Fault Injection Modules
    subgraph "Fault Injection Modules"
        direction TB
        FaultInj["fault/injection"]:::fault
    end

    %% Connections
    binScripts -->|"invokes"| ConfigNode
    RunJPF -->|"invokes"| ConfigNode
    RunTool -->|"invokes"| ConfigNode
    JPFShellNode -->|"invokes"| ConfigNode
    JPFNode -->|"invokes"| ConfigNode

    ConfigNode -->|"loads"| JPFClassLoaderNode
    ConfigNode -->|"reads"| JPFProps
    ConfigListener -->|"listens to"| ConfigNode

    JPFClassLoaderNode -->|"uses"| ClassFileReaderNode
    ClassFileReaderNode -->|"parses"| ClassFileNode
    ClassFileReaderNode -->|"builds"| JVMClassInfoNode
    ClassFileReaderNode -->|"belongs to"| JVMPackage

    InstructionFactory -->|"creates instructions for"| VMNode
    VMNode -->|"executes on"| SingleVM
    VMNode -->|"executes on"| MultiVM
    VMNode -->|"core in"| VMCore

    SearchNode -->|"controls"| VMNode
    DFSearchNode -->|"implements"| SearchNode
    RandomSearchNode -->|"implements"| SearchNode
    HeuristicSearchNode -->|"implements"| SearchNode
    SearchPkg -->|"contains"| SearchNode

    VMNode -->|"requests choices from"| ChoiceGen
    ThreadChoice -->|"type of"| ChoiceGen
    ChoicePkg -->|"contains"| ChoiceGen

    VMNode -->|"emits events to"| JPFListenerNode
    ListenerAdapterNode -->|"extends"| JPFListenerNode
    ListenerPkg -->|"contains"| JPFListenerNode

    JPFListenerNode -->|"sends metrics to"| PublisherNode
    ConsolePub -->|"publishes to console"| PublisherNode
    XMLPub -->|"publishes to XML"| PublisherNode
    ReportPkg -->|"contains"| PublisherNode

    VMNode -->|"delegates natives to"| PeersDir
    PeersVM -->|"implements native peers in"| PeersDir

    VMNode -->|"uses utilities from"| UtilPkg

    FaultInj -->|"injects faults into"| InstructionFactory
    FaultInj -->|"injects events into"| ListenerAdapterNode

    %% Click Events
    click binScripts "https://github.com/javapathfinder/jpf-core/tree/master/bin/"
    click RunJPF "https://github.com/javapathfinder/jpf-core/blob/master/src/main/gov/nasa/jpf/tool/RunJPF.java"
    click RunTool "https://github.com/javapathfinder/jpf-core/blob/master/src/main/gov/nasa/jpf/tool/Run.java"
    click JPFShellNode "https://github.com/javapathfinder/jpf-core/blob/master/src/main/gov/nasa/jpf/JPFShell.java"
    click JPFNode "https://github.com/javapathfinder/jpf-core/blob/master/src/main/gov/nasa/jpf/JPF.java"
    click ConfigNode "https://github.com/javapathfinder/jpf-core/blob/master/src/main/gov/nasa/jpf/Config.java"
    click ConfigListener "https://github.com/javapathfinder/jpf-core/blob/master/src/main/gov/nasa/jpf/ConfigChangeListener.java"
    click JPFProps "https://github.com/javapathfinder/jpf-core/blob/master/jpf.properties"
    click JPFClassLoaderNode "https://github.com/javapathfinder/jpf-core/blob/master/src/main/gov/nasa/jpf/JPFClassLoader.java"
    click ClassFileReaderNode "https://github.com/javapathfinder/jpf-core/blob/master/src/main/gov/nasa/jpf/jvm/ClassFileReader.java"
    click JVMClassInfoNode "https://github.com/javapathfinder/jpf-core/blob/master/src/main/gov/nasa/jpf/jvm/JVMClassInfo.java"
    click ClassFileNode "https://github.com/javapathfinder/jpf-core/blob/master/src/main/gov/nasa/jpf/jvm/ClassFile.java"
    click JVMPackage "https://github.com/javapathfinder/jpf-core/tree/master/src/main/gov/nasa/jpf/jvm"
    click InstructionFactory "https://github.com/javapathfinder/jpf-core/blob/master/src/main/gov/nasa/jpf/jvm/JVMInstructionFactory.java"
    click VMNode "https://github.com/javapathfinder/jpf-core/blob/master/src/main/gov/nasa/jpf/vm/VM.java"
    click SingleVM "https://github.com/javapathfinder/jpf-core/blob/master/src/main/gov/nasa/jpf/vm/SingleProcessVM.java"
    click MultiVM "https://github.com/javapathfinder/jpf-core/blob/master/src/main/gov/nasa/jpf/vm/MultiProcessVM.java"
    click VMCore "https://github.com/javapathfinder/jpf-core/tree/master/src/main/gov/nasa/jpf/vm"
    click SearchNode "https://github.com/javapathfinder/jpf-core/blob/master/src/main/gov/nasa/jpf/search/Search.java"
    click DFSearchNode "https://github.com/javapathfinder/jpf-core/blob/master/src/main/gov/nasa/jpf/search/DFSearch.java"
    click RandomSearchNode "https://github.com/javapathfinder/jpf-core/blob/master/src/main/gov/nasa/jpf/search/RandomSearch.java"
    click HeuristicSearchNode "https://github.com/javapathfinder/jpf-core/blob/master/src/main/gov/nasa/jpf/search/heuristic/HeuristicSearch.java"
    click SearchPkg "https://github.com/javapathfinder/jpf-core/tree/master/src/main/gov/nasa/jpf/search"
    click ChoiceGen "https://github.com/javapathfinder/jpf-core/blob/master/src/main/gov/nasa/jpf/vm/choice/ChoiceGenerator.java"
    click ThreadChoice "https://github.com/javapathfinder/jpf-core/blob/master/src/main/gov/nasa/jpf/vm/choice/ThreadChoiceFromSet.java"
    click ChoicePkg "https://github.com/javapathfinder/jpf-core/tree/master/src/main/gov/nasa/jpf/vm/choice"
    click JPFListenerNode "https://github.com/javapathfinder/jpf-core/blob/master/src/main/gov/nasa/jpf/JPFListener.java"
    click ListenerAdapterNode "https://github.com/javapathfinder/jpf-core/blob/master/src/main/gov/nasa/jpf/ListenerAdapter.java"
    click ListenerPkg "https://github.com/javapathfinder/jpf-core/tree/master/src/main/gov/nasa/jpf/listener"
    click PublisherNode "https://github.com/javapathfinder/jpf-core/blob/master/src/main/gov/nasa/jpf/report/Publisher.java"
    click ConsolePub "https://github.com/javapathfinder/jpf-core/blob/master/src/main/gov/nasa/jpf/report/ConsolePublisher.java"
    click XMLPub "https://github.com/javapathfinder/jpf-core/blob/master/src/main/gov/nasa/jpf/report/XMLPublisher.java"
    click ReportPkg "https://github.com/javapathfinder/jpf-core/tree/master/src/main/gov/nasa/jpf/report"
    click PeersDir "https://github.com/javapathfinder/jpf-core/tree/master/src/peers/"
    click PeersVM "https://github.com/javapathfinder/jpf-core/tree/master/src/peers/gov/nasa/jpf/vm"
    click UtilPkg "https://github.com/javapathfinder/jpf-core/tree/master/src/main/gov/nasa/jpf/util"
    click FaultInj "https://github.com/javapathfinder/jpf-core/tree/master/src/main/fault/injection"

    %% Styles
    classDef cli fill:#D6E9FE,stroke:#4A90E2,color:#000
    classDef config fill:#FEEFD6,stroke:#E2A84A,color:#000
    classDef core fill:#E8F1FE,stroke:#2E6DA4,color:#000
    classDef search fill:#FDEBD0,stroke:#E67E22,color:#000
    classDef plugin fill:#F4ECF7,stroke:#9B59B6,color:#000
    classDef report fill:#E8F6F3,stroke:#27AE60,color:#000
    classDef native fill:#EEEEEE,stroke:#A0A0A0,color:#000
    classDef util fill:#F0F0F0,stroke:#7F8C8D,color:#000
    classDef fault fill:#FDEDEC,stroke:#E74C3C,color:#000
```
