Java

Last verified end to end: 2026-07-14 (query_code schema version 2).

For exact inbound and outbound symbol edges, proof tiers, and adapter-specific caveats, see Reference Traversal.

Java normalizes methods, constructors, annotations, object creation, member calls, imports, assignments, exceptions, and control flow. The fixture includes two post receivers so receiver filtering proves a real exclusion.

Fixture

package app;

import java.io.IOException;

@interface Route {}

class Response {}

class Client {
    Response post(String path) { return new Response(); }
}

class Api {
    @Route
    Api() {}

    @Route
    Response save(Client client, Client backup, String path) {
        backup.post(path);
        try {
            if (path.isEmpty()) {
                throw new IllegalArgumentException();
            }
            while (path.startsWith("/")) {
                return client.post(path);
            }
            return new Response();
        } catch (RuntimeException error) {
            throw error;
        }
    }
}

Narrow A Member Call

callee: "post" alone finds both calls. receiver: "client", the positional capture, and inside select only the return-path call in Api.save.

(inside
  (method :name "save")
  (language java
    (call :callee "post" :receiver "client" :args [(capture "path")])) )

{
  "languages": ["java"],
  "match": {
    "kind": "call",
    "callee": {"name": "post"},
    "receiver": {"name": "client"},
    "args": [{"capture": "path"}]
  },
  "inside": {"kind": "method", "name": "save"}
}

{
  "results": [
    {
      "result_type": "structural_match",
      "path": "java/App.java",
      "language": "java",
      "kind": "call",
      "start_line": 25,
      "end_line": 25,
      "text": "client.post(path)",
      "captures": [{"name": "path", "text": "path", "start_line": 25}],
      "enclosing_symbol": "app.Api.save"
    }
  ],
  "truncated": false
}

Find An Annotated Constructor

Java annotations use the normalized decorators role. A constructor remains distinct from an ordinary method.

(constructor :name "Api" :decorators [(decorator :name "Route" :capture "annotation")])

{
  "match": {
    "kind": "constructor",
    "name": "Api",
    "decorators": [
      {"kind": "decorator", "name": "Route", "capture": "annotation"}
    ]
  }
}

{
  "results": [
    {
      "result_type": "structural_match",
      "path": "java/App.java",
      "language": "java",
      "kind": "constructor",
      "start_line": 14,
      "end_line": 15,
      "text": "@Route…",
      "captures": [
        {"name": "annotation", "text": "@Route", "start_line": 14}
      ],
      "enclosing_symbol": "app.Api.Api"
    }
  ],
  "truncated": false
}

Query Exception And Control-Flow Shapes

has searches descendants, so these queries select only the catch, conditional, and loop that contain the requested statement shape.

(catch (has (throw :capture "rethrown")))

{"match":{"kind":"catch","has":{"kind":"throw","capture":"rethrown"}}}

{
  "results": [
    {
      "result_type": "structural_match",
      "path": "java/App.java",
      "language": "java",
      "kind": "catch",
      "start_line": 28,
      "end_line": 30,
      "text": "catch (RuntimeException error) {…",
      "captures": [
        {"name": "rethrown", "text": "throw error;", "start_line": 29}
      ],
      "enclosing_symbol": "app.Api.save"
    }
  ],
  "truncated": false
}

(if (has (throw :capture "failure")))

{"match":{"kind":"if","has":{"kind":"throw","capture":"failure"}}}

{
  "results": [
    {
      "result_type": "structural_match",
      "path": "java/App.java",
      "language": "java",
      "kind": "if",
      "start_line": 21,
      "end_line": 23,
      "text": "if (path.isEmpty()) {…",
      "captures": [
        {
          "name": "failure",
          "text": "throw new IllegalArgumentException();",
          "start_line": 22
        }
      ],
      "enclosing_symbol": "app.Api.save"
    }
  ],
  "truncated": false
}

(loop (has (return :capture "exit")))

{"match":{"kind":"loop","has":{"kind":"return","capture":"exit"}}}

{
  "results": [
    {
      "result_type": "structural_match",
      "path": "java/App.java",
      "language": "java",
      "kind": "loop",
      "start_line": 24,
      "end_line": 26,
      "text": "while (path.startsWith(\"/\")) {…",
      "captures": [
        {
          "name": "exit",
          "text": "return client.post(path);",
          "start_line": 25
        }
      ],
      "enclosing_symbol": "app.Api.save"
    }
  ],
  "truncated": false
}

Unsupported Keyword Arguments

Java has positional arguments but no keyword-argument syntax. Asking for kwargs produces a capability diagnostic and no pretend match.

(language java (call :callee "post" :kwargs [(path (name "path"))]))

{
  "languages": ["java"],
  "match": {
    "kind": "call",
    "callee": {"name": "post"},
    "kwargs": {"path": {"name": "path"}}
  }
}

{
  "results": [],
  "truncated": false,
  "diagnostics": [
    {
      "language": "java",
      "message": "structural adapter for java does not support role(s): kwargs"
    }
  ]
}

Precision Boundary

Receiver names are syntactic. receiver: "client" does not prove that the variable has type Client; use symbol and usage tools when identity matters.

Traverse Indexed Types And Members

class QueryRoot {
    void rootMember() {}
}

class QueryLeaf extends QueryRoot {
    void leafMember() {}
}

(supertypes (enclosing-decl (language java (class :name "QueryLeaf"))))

{"languages":["java"],"match":{"kind":"class","name":"QueryLeaf"},"steps":[{"op":"enclosing_decl"},{"op":"supertypes"}]}

{
  "results": [
    {
      "end_line": 3,
      "fq_name": "QueryRoot",
      "kind": "class",
      "language": "java",
      "path": "java/QueryHierarchy.java",
      "provenance": [
        {
          "seed": {
            "end_line": 7,
            "kind": "class",
            "path": "java/QueryHierarchy.java",
            "result_type": "structural_match",
            "start_line": 5
          },
          "steps": [
            {
              "op": "enclosing_decl",
              "result": {
                "end_line": 7,
                "fq_name": "QueryLeaf",
                "kind": "class",
                "path": "java/QueryHierarchy.java",
                "result_type": "declaration",
                "start_line": 5
              }
            },
            {
              "op": "supertypes",
              "result": {
                "end_line": 3,
                "fq_name": "QueryRoot",
                "kind": "class",
                "path": "java/QueryHierarchy.java",
                "result_type": "declaration",
                "start_line": 1
              }
            }
          ]
        }
      ],
      "result_type": "declaration",
      "signature": "class QueryRoot {",
      "start_line": 1
    }
  ],
  "truncated": false
}

(owner (members (subtypes :transitive true (enclosing-decl (language java (class :name "QueryRoot"))))))

{"languages":["java"],"match":{"kind":"class","name":"QueryRoot"},"steps":[{"op":"enclosing_decl"},{"op":"subtypes","transitive":true},{"op":"members"},{"op":"owner"}]}

{
  "results": [
    {
      "end_line": 7,
      "fq_name": "QueryLeaf",
      "kind": "class",
      "language": "java",
      "path": "java/QueryHierarchy.java",
      "provenance": [
        {
          "seed": {
            "end_line": 3,
            "kind": "class",
            "path": "java/QueryHierarchy.java",
            "result_type": "structural_match",
            "start_line": 1
          },
          "steps": [
            {
              "op": "enclosing_decl",
              "result": {
                "end_line": 3,
                "fq_name": "QueryRoot",
                "kind": "class",
                "path": "java/QueryHierarchy.java",
                "result_type": "declaration",
                "start_line": 1
              }
            },
            {
              "op": "subtypes",
              "result": {
                "end_line": 7,
                "fq_name": "QueryLeaf",
                "kind": "class",
                "path": "java/QueryHierarchy.java",
                "result_type": "declaration",
                "start_line": 5
              }
            },
            {
              "op": "members",
              "result": {
                "end_line": 6,
                "fq_name": "QueryLeaf.leafMember",
                "kind": "function",
                "path": "java/QueryHierarchy.java",
                "result_type": "declaration",
                "start_line": 6
              }
            },
            {
              "op": "owner",
              "result": {
                "end_line": 7,
                "fq_name": "QueryLeaf",
                "kind": "class",
                "path": "java/QueryHierarchy.java",
                "result_type": "declaration",
                "start_line": 5
              }
            }
          ]
        }
      ],
      "result_type": "declaration",
      "signature": "class QueryLeaf extends QueryRoot {",
      "start_line": 5
    }
  ],
  "truncated": false
}