Usages, hierarchy & calls

Find who uses a symbol, what implements a type, who calls a method and what it calls, and real call sites to learn from — across every jar on the classpath, not just one.

Find usages: `usages`#

One row per referencing method, named canonically so the next command is a copy-paste:

$ jdx usages com.google.gson.JsonNull --limit 8 --coord com.google.code.gson:gson:2.14.0
usages of 'com.google.gson.JsonNull'
gson-2.14.0.jar (8)
  read com.google.gson.Gson#toJson(java.lang.Object)  Gson.java:544 -> #INSTANCE
  read com.google.gson.Gson#toJson(java.lang.Object, java.lang.Appendable)  Gson.java:593 -> #INSTANCE
  read com.google.gson.Gson#toJsonTree(java.lang.Object)  Gson.java:498 -> #INSTANCE
  read com.google.gson.JsonArray#add(com.google.gson.JsonElement)  JsonArray.java:127 -> #INSTANCE
  read com.google.gson.JsonArray#add(java.lang.Boolean)  JsonArray.java:87 -> #INSTANCE
  read com.google.gson.JsonArray#add(java.lang.Character)  JsonArray.java:97 -> #INSTANCE
  read com.google.gson.JsonArray#add(java.lang.Number)  JsonArray.java:107 -> #INSTANCE
  read com.google.gson.JsonArray#add(java.lang.String)  JsonArray.java:117 -> #INSTANCE
8 of 30 usages shown (--limit 30 to see more)
warning MULTI_RELEASE_VARIANT: multi-release gson-2.14.0.jar serves version-specific variants for this JDK (21)

Real output — this example ran against the current jdx when the page was built.

Narrow by edge kind with --kind:

`--kind`	Finds
`call`	method calls
`read` / `write`	field reads and writes
`new`	constructor call sites
`ref`	any other reference (casts, `instanceof`, class literals, signatures)
`throw`	methods declaring the type in `throws` (declaration-level, not `ATHROW` throw sites)
`annotation`	classes and members carrying the annotation

With --kind annotation, filter by element values via --where key=value (repeatable, AND), or spell the predicate inline as an annotation use (omit the leading @ on the CLI — Clikt reserves @file for argfiles; MCP accepts @Type(k=v)):

$ jdx usages 'java.lang.Deprecated(forRemoval=true)' --kind annotation --jars lib.jar

Or use the dedicated command (same listing; recipe aliases for common cases):

$ jdx annotated forRemoval --jars lib.jar
$ jdx annotated test --coord org.junit.jupiter:junit-jupiter-api:5.10.2 --fetch --no-jdk
$ jdx annotated bean --coord org.springframework:spring-context:6.1.14 --fetch --no-jdk

Recipes: deprecated, forRemoval, test/junit5, junit4, bean. Annotation-use spelling works here too (jdx annotated 'Deprecated(forRemoval=true)' — omit leading @ on the CLI).

--in / --exclude filter by artifact (jar file name, JDK module or source directory), and --src <dir> adds your project's source directories — those hits are textual mentions with line numbers. --context N shows a short source window around each call site when paired sources (or --src) are available; 0 (default) is location-only (File.java:line).

Type hierarchy: `hierarchy` and `implementors`#

Supertypes upward (the full chain, interfaces included) and subtypes downward across the whole classpath:

$ jdx hierarchy com.google.gson.JsonElement --coord com.google.code.gson:gson:2.14.0
hierarchy of 'com.google.gson.JsonElement'
  supertypes
    extends java.lang.Object  java.base
  subtypes in workspace (4)
    class com.google.gson.JsonArray  gson-2.14.0.jar
    class com.google.gson.JsonNull  gson-2.14.0.jar
    class com.google.gson.JsonObject  gson-2.14.0.jar
    class com.google.gson.JsonPrimitive  gson-2.14.0.jar
warning MULTI_RELEASE_VARIANT: multi-release gson-2.14.0.jar serves version-specific variants for this JDK (21)

Real output — this example ran against the current jdx when the page was built.

--up / --down pick a direction, --direct stops at one level, --depth N caps it. jdx implementors <type> is hierarchy --down:

$ jdx implementors com.google.gson.TypeAdapterFactory --direct --coord com.google.code.gson:gson:2.14.0
hierarchy of 'com.google.gson.TypeAdapterFactory'
  subtypes in workspace (21)
    class com.google.gson.internal.Excluder  gson-2.14.0.jar
    class com.google.gson.internal.bind.ArrayTypeAdapter$1  gson-2.14.0.jar
    class com.google.gson.internal.bind.CollectionTypeAdapterFactory  gson-2.14.0.jar
    class com.google.gson.internal.bind.DefaultDateTypeAdapter$1  gson-2.14.0.jar
    class com.google.gson.internal.bind.EnumTypeAdapter$1  gson-2.14.0.jar
    class com.google.gson.internal.bind.JavaTimeTypeAdapters$14  gson-2.14.0.jar
    class com.google.gson.internal.bind.JsonAdapterAnnotationTypeAdapterFactory  gson-2.14.0.jar
    class com.google.gson.internal.bind.JsonAdapterAnnotationTypeAdapterFactory$DummyTypeAdapterFactory  gson-2.14.0.jar
… 14 more lines (run it yourself to see them all)

Real output — this example ran against the current jdx when the page was built.

Call hierarchy: `callers` and `calls`#

$ jdx callers 'com.google.gson.JsonParser#parseReader(com.google.gson.stream.JsonReader)' --coord com.google.code.gson:gson:2.14.0
callers of 'com.google.gson.JsonParser#parseReader(com.google.gson.stream.JsonReader)'
  call com.google.gson.JsonParser#parse(com.google.gson.stream.JsonReader)  gson-2.14.0.jar
  call com.google.gson.JsonParser#parseReader(java.io.Reader)  gson-2.14.0.jar
warning MULTI_RELEASE_VARIANT: multi-release gson-2.14.0.jar serves version-specific variants for this JDK (21)

Real output — this example ran against the current jdx when the page was built.

--depth N follows the graph transitively (cycle-safe, cycles are marked). jdx calls goes the other way; add --external-only to see only what a method needs from other artifacts — its dependency footprint.

Learn from real code: `samples`#

The fastest way to learn an API is to read code that already uses it. samples ranks real call sites by how exemplary they are — non-test before test, non-generated before generated, fuller overloads first — and shows the enclosing method when sources are available. Each snippet is capped at 15 lines by default (--max-lines N to raise it; the truncation marker names the total):

$ jdx samples 'com.google.gson.JsonParser#parseString(String)' --coord com.google.code.gson:gson:2.14.0
samples of 'com.google.gson.JsonParser#parseString(String)'
  example com.google.gson.JsonParser#parse(java.lang.String)  gson-2.14.0.jar
    com/google/gson/JsonParser.java:155-159
      @Deprecated
      @InlineMe(replacement = "JsonParser.parseString(json)", imports = "com.google.gson.JsonParser")
      public JsonElement parse(String json) throws JsonSyntaxException {
        return parseString(json);
      }
warning MULTI_RELEASE_VARIANT: multi-release gson-2.14.0.jar serves version-specific variants for this JDK (21)

Real output — this example ran against the current jdx when the page was built.

String constants#

To find which class holds this English string / resource key without unzip | tr | grep (issue #86):

$ jdx literals 'com.google.gson' --coord com.google.code.gson:gson:2.14.0 --limit 5 --no-jdk
literals matching 'com.google.gson'
gson-2.14.0.jar (2)
  ldc com.google.gson.internal.bind.TypeAdapters#javaTimeTypeAdapterFactory()  "com.google.gson.internal.bind.JavaTimeTypeAdapters"  TypeAdapters.java:951
  ldc com.google.gson.internal.reflect.ReflectionHelper#getInaccessibleTroubleshootingSuffix(java.lang.Exception)  "to module com.google.gson"  ReflectionHelper.java:51

Real output — this example ran against the current jdx when the page was built.

Matches bytecode LDC loads, String field ConstantValues, and .properties resource keys/values. A properties hit looks like prop messages/Bundle.properties#some.key "English value" — paste the path into jdx resources … --cat to read the whole bundle.

SPI / ServiceLoader registrations#

To answer who provides this service interface? without unzipping jars (issue #25):

$ jdx services java.sql.Driver --coord org.postgresql:postgresql:42.7.4 --fetch --no-jdk
services matching 'java.sql.Driver'
postgresql-42.7.4.jar (1)
  service java.sql.Driver
    provider org.postgresql.Driver

Real output — this example ran against the current jdx when the page was built.

Omit the pattern to list every META-INF/services registration in the workspace. A pattern matches the service interface FQN or a provider class FQN. module-info provides directives are read by jdx modules instead.

JPMS module-info#

To answer what does this module require / export / provide? without jmod describe (issue #25):

$ jdx modules java.sql --limit 5
modules matching 'java.sql'
jrt:/ (2)
  module java.sql @21.0.13
    requires java.base mandated
    requires java.logging transitive
    requires java.transaction.xa transitive
    requires java.xml transitive
    exports java.sql
    exports javax.sql
    uses java.sql.Driver
  module java.sql.rowset @21.0.13
    requires java.base mandated
    requires java.logging transitive
    requires java.naming transitive
    requires java.sql transitive
    exports javax.sql.rowset
    exports javax.sql.rowset.serial
    exports javax.sql.rowset.spi
    uses javax.sql.rowset.RowSetFactory

Real output — this example ran against the current jdx when the page was built.

Omit the pattern to list every module-info.class in the workspace (including the running JDK). A pattern matches the module name, an exported/opened package, a uses/provides service, or a provider class.

Manifest attributes#

To answer what is this jar's Main-Class / Implementation-Version / Multi-Release? without unzip -p …/MANIFEST.MF (issue #25):

$ jdx manifest Multi-Release --coord com.google.code.gson:gson:2.14.0 --no-jdk
manifests matching 'Multi-Release'
gson-2.14.0.jar (1)
  Multi-Release: true

Real output — this example ran against the current jdx when the page was built.

Omit the pattern to list every main attribute. A pattern matches the attribute name or value. Pass --entries to list per-entry (JarEntry) attributes instead (Name: sections — digests, Content-Type, …); the pattern then also matches the entry path.

Resource paths#

To answer which jar holds this .properties / META-INF/… path? without unzip -l loops (issue #25):

$ jdx resources META-INF --coord com.google.code.gson:gson:2.14.0 --limit 5 --no-jdk
resources matching 'META-INF'
gson-2.14.0.jar (4)
  META-INF/MANIFEST.MF
  META-INF/maven/com.google.code.gson/gson/pom.properties
  META-INF/maven/com.google.code.gson/gson/pom.xml
  META-INF/proguard/gson.pro

Real output — this example ran against the current jdx when the page was built.

Omit the pattern to list every non-class resource. A pattern matches the entry path. Versioned copies under META-INF/versions/ are listed as stored. Pass --cat to print the unique match's text (binary / non-UTF-8 payloads refuse to dump bytes; ambiguous matches exit 2 with path --in artifact candidates):

$ jdx resources META-INF/MANIFEST.MF --cat --coord com.google.code.gson:gson:2.14.0 --no-jdk
META-INF/MANIFEST.MF
  artifact: gson-2.14.0.jar
  size: 1243 bytes
Manifest-Version: 1.0
Created-By: Maven JAR Plugin 3.5.0
Java-Version: 8
Build-Jdk-Spec: 17
Bundle-ContactAddress: https://github.com/google/gson
Bundle-Description: Gson JSON library
Bundle-Developers: google;organization=Google;organizationUrl="https://w
 ww.google.com"
Bundle-DocURL: https://github.com/google/gson
Bundle-License: "Apache-2.0";link="https://www.apache.org/licenses/LICEN
 SE-2.0.txt"
Bundle-ManifestVersion: 2
Bundle-Name: Gson
Bundle-SCM: url="https://github.com/google/gson/",connection="scm:git:ht
 tps://github.com/google/gson.git",developer-connection="scm:git:git@git
 hub.com:google/gson.git",tag="gson-parent-2.14.0"
Bundle-SymbolicName: com.google.gson
Bundle-Vendor: Google Gson Project
Bundle-Version: 2.14.0
Export-Package: com.google.gson;uses:="com.google.gson.reflect,com.googl
 e.gson.stream";version="2.14.0",com.google.gson.annotations;version="2.
 14.0",com.google.gson.reflect;version="2.14.0",com.google.gson.stream;u
 ses:="com.google.gson";version="2.14.0"
Import-Package: sun.misc;resolution:=optional,com.google.errorprone.anno
 tations;resolution:=optional;version="[2.48,3)"
Require-Capability: osgi.ee;filter:="(&(osgi.ee=JavaSE)(version=1.8))"
Multi-Release: true

next: jdx resources 'META-INF/MANIFEST.MF' --in gson-2.14.0.jar

Real output — this example ran against the current jdx when the page was built.

Limitations#

Graph queries re-scan the bytecode roots on each query (there is no persistent graph index yet); the daemon and MCP server keep the scan warm.
callers is override-aware by default (issue #6): querying an interface/base method also finds call sites through overrides, and querying an override also finds polymorphic call sites through declaring supertypes. Pass --exact for invoke-owner matching only. calls stays bytecode-exact — an invoke instruction names one owner, so callees are not expanded to the override set.
Usages found in source directories are textual (ref kind only).
usages --kind throw reads throws declarations, not ATHROW sites (throw-site attribution needs data-flow analysis and is deferred to future work).

Open limitations are tracked in GitHub Issues.

Usages, hierarchy & calls

Find usages: usages#

Type hierarchy: hierarchy and implementors#

Call hierarchy: callers and calls#

Learn from real code: samples#

String constants#

SPI / ServiceLoader registrations#

JPMS module-info#

Manifest attributes#

Resource paths#

Limitations#

Find usages: `usages`#

Type hierarchy: `hierarchy` and `implementors`#

Call hierarchy: `callers` and `calls`#

Learn from real code: `samples`#