Skip to content

Symbol references

Every jdx command takes a symbol reference in Javadoc style. jdx is generous about what it accepts and canonical about what it prints, so any reference it prints can be pasted back into the next command.

The forms#

Reference	Means
`com.google.gson.Gson`	a type
`java.util.Map$Entry`, `java.util.Map.Entry`	a nested type (`$` or `.`)
`Gson`	a short name — resolved, or exit `2` with candidates
`com.google.gson.Gson#toJson`	every overload of a method
`com.google.gson.Gson#toJson(Object)`	one overload, simple parameter names
`com.google.gson.Gson#toJson(java.lang.Object)`	one overload, qualified parameter names
`…#toJson(Object):String`	disambiguated by return type (bridge methods)
`…#toJson(Ljava/lang/Object;)Ljava/lang/String;`	an exact JVM descriptor — never ambiguous
`com.google.gson.Gson#<init>(...)`	a constructor
`java.lang.Integer#MAX_VALUE`	a field
`com.google.code.gson:gson:2.14.0/com.google.gson.Gson`	scoped to one Maven artifact

:: and . are accepted in place of #. The last dot-separated segment before the member is always the class.

Quote references in a shell. # starts a comment, ( opens a subshell and $ expands a variable — single quotes avoid all three.

Nested types#

Both spellings resolve to the same type, and jdx prints the canonical $ form:

$ jdx show java.util.Map.Entry
interface java.util.Map$Entry
  public abstract interface Entry
  members: 0 constructors, 15 methods, 0 fields
source: java.base (jrt)
next: jdx members java.util.Map$Entry --inherited
$ jdx show 'java.util.Map$Entry'
interface java.util.Map$Entry
  public abstract interface Entry
  members: 0 constructors, 15 methods, 0 fields
source: java.base (jrt)
next: jdx members java.util.Map$Entry --inherited

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

Overloads and descriptors#

Simple names, qualified names and raw descriptors all select a single overload; fields work the same way:

$ jdx signature 'java.util.HashMap#put(Object, Object)'
signatures of java.util.HashMap#put
  public V put(K key, V value)
source: java.base (jrt)
next: jdx show java.util.HashMap
$ jdx signature 'java.util.HashMap#get(Ljava/lang/Object;)Ljava/lang/Object;'
signatures of java.util.HashMap#get
  public V get(java.lang.Object key)
source: java.base (jrt)
next: jdx show java.util.HashMap
$ jdx signature 'java.lang.Integer#MAX_VALUE'
signatures of java.lang.Integer#MAX_VALUE
  public static final int MAX_VALUE = 2147483647
source: java.base (jrt)
next: jdx show java.lang.Integer

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

Ambiguity: jdx never guesses#

When a reference matches more than one symbol, jdx exits 2 and prints every candidate in its canonical form. An agent retries with one of them — no reconstruction needed:

$ jdx signature 'com.google.gson.Gson#toJson(Object, Appendable)' --coord com.google.code.gson:gson:2.14.0
signatures of com.google.gson.Gson#toJson
  public void toJson(java.lang.Object src, java.lang.Appendable writer) throws com.google.gson.JsonIOException
warning MULTI_RELEASE_VARIANT: multi-release gson-2.14.0.jar serves version-specific variants for this JDK (21)
source: gson-2.14.0.jar (bytecode)
next: jdx show com.google.gson.Gson
$ jdx body 'com.google.gson.Gson#toJson' --coord com.google.code.gson:gson:2.14.0
ambiguous: 8 candidates for com.google.gson.Gson#toJson
  com.google.gson.Gson#toJson(com.google.gson.JsonElement)
  com.google.gson.Gson#toJson(com.google.gson.JsonElement, com.google.gson.stream.JsonWriter)
  com.google.gson.Gson#toJson(com.google.gson.JsonElement, java.lang.Appendable)
  com.google.gson.Gson#toJson(java.lang.Object)
  com.google.gson.Gson#toJson(java.lang.Object, java.lang.Appendable)
  com.google.gson.Gson#toJson(java.lang.Object, java.lang.reflect.Type)
  com.google.gson.Gson#toJson(java.lang.Object, java.lang.reflect.Type, com.google.gson.stream.JsonWriter)
  com.google.gson.Gson#toJson(java.lang.Object, java.lang.reflect.Type, java.lang.Appendable)
hint: re-run with one of the refs above
[exit 2]

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

Not found: did you mean#

A miss exits 1 with the closest candidates (camel humps, then edit distance, then the same simple name in other packages):

$ jdx show com.google.gson.JsonParse --coord com.google.code.gson:gson:2.14.0
not found: com.google.gson.JsonParse
did you mean:
  com.google.gson.JsonParser
[exit 1]

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

When you only know a simple name — from a stack trace or a snippet — jdx resolve lists every candidate with its kind and artifact, and several candidates are a success:

$ jdx resolve JsonParser --coord com.google.code.gson:gson:2.14.0
search results for 'JsonParser'
  class com.google.gson.JsonParser  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.

Round-tripping#

parse(print(ref)) == ref is a tested property: every reference jdx prints — in members, usages, callers, ambiguity lists, next: hints — is accepted verbatim as input.

The full grammar is in the design specification.

Edit this page on GitHub · View as Markdown · Updated 2026-10-05