# 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:

```console jdx-generated
$ 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) -> #INSTANCE
  read com.google.gson.Gson#toJson(java.lang.Object, java.lang.Appendable) -> #INSTANCE
  read com.google.gson.Gson#toJsonTree(java.lang.Object) -> #INSTANCE
  read com.google.gson.JsonArray#add(com.google.gson.JsonElement) -> #INSTANCE
  read com.google.gson.JsonArray#add(java.lang.Boolean) -> #INSTANCE
  read com.google.gson.JsonArray#add(java.lang.Character) -> #INSTANCE
  read com.google.gson.JsonArray#add(java.lang.Number) -> #INSTANCE
  read com.google.gson.JsonArray#add(java.lang.String) -> #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)
```

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|

`--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.

## Type hierarchy: `hierarchy` and `implementors`

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

```console jdx-generated
$ 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)
```

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

```console jdx-generated
$ 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)
```

## Call hierarchy: `callers` and `calls`

```console jdx-generated
$ 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)
```

`--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:

```console jdx-generated
$ 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)
```

## 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.
- Call matching is exact name + descriptor, not override-aware: a call through an interface is
  attributed to the interface method.
- 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](https://github.com/MohammadMD1383/jdx/issues).