The consumer’s Java sources

Prefix: java_.

Where things are written in the consumer’s own Java sources: the position and documentation comment of each class, method and field declaration, from a plain parse of the source files. It exists so tools can point at a line in a file the author owns. It reads the sources rather than the compiled output deliberately, because the two answer different questions and may legitimately disagree.

Where to start

java_file: A .java file whose declarations this store holds, and the stamp they were read at.
java_class_declaration: A class, interface, enum, record or annotation declaration written in a source file, at the position the parse read it.
java_method_declaration: A method declaration on a declared class: one row per declaration, not one per resolvable name.

How this family meets the others

No crossing is declared for this family and no foreign key crosses its boundary; its rows meet the other families' only where a reader joins them.

Why the name is right

What the consumer’s .java sources declare, read by an unattributed parse: where each class, method and field is written, and what its doc comment says. Its own family beside jvm_ rather than columns on it, because the two are separate populations on separate cadences that may legitimately disagree: a source parse yields arity where a classfile yields a descriptor, and the jvm_ census excludes the generated jOOQ package this family has to answer for. Named for the language whose declarations it transcribes, and distinct from javac_, which holds what the compiler concluded about generated sources rather than what a parse read from authored ones.

java_class_declaration

A class, interface, enum, record or annotation declaration written in a source file, at the position the parse read it. Keyed by file and name rather than by name alone: two files declaring one fully-qualified name is malformed Java that a parse still reads, and a relation keyed on the name would have to pick one of them. A nested class earns its own row under the dotted name its declaration chain spells; anonymous and local classes have no name to key on and are absent.

Primary key: (file, class_name). Foreign key: (file) references java_file (file).

Columns

file (CHARACTER VARYING, not null): the source file the declaration is written in; the family’s partition dimension and the key’s leading column
class_name (CHARACTER VARYING, not null): the dotted name the declaration spells: the file’s package, then the chain of enclosing class simple names. The join key to jvm_class.class_name, matched by name and by nothing else, the generated jOOQ package being absent there and present here
source_line (INTEGER, not null): line of the declaration, 1-based per the Compiler Tree API’s LineMap; the store holds the parse’s own convention and an editor surface converts to its own. A parse positions every declaration it reads, so -1, that API’s own no-position sentinel, is defensive: it is carried through rather than dropped, because a declaration whose position is missing still has a doc comment worth holding
source_column (INTEGER, not null): column of the declaration, 1-based on the same terms as source_line
javadoc (CHARACTER VARYING, nullable): the declaration’s doc comment as the parse retained it, stripped; NULL where the declaration carries none, absence being a fact rather than an empty string. Display material, never a dimension

java_field_declaration

A field declaration on a declared class: the position and doc comment of a variable whose immediate encloser is a class, so parameters and locals are absent. Enum constants are fields at this grain, and so are the generated jOOQ table classes' column constants, which is what makes a column’s declaration reachable here at all. A field name is unique within a class, so no ordinal is needed beside it.

Primary key: (file, class_name, field_name). Foreign key: (file, class_name) references java_class_declaration (file, class_name).

Columns

file (CHARACTER VARYING, not null): the source file the declaration is written in; the family’s partition dimension and the key’s leading column
class_name (CHARACTER VARYING, not null): the declaring class, as java_class_declaration spells it
field_name (CHARACTER VARYING, not null): the declared field name as written; the Java name, which is what joins to a generated table class’s column constant, never the SQL column name
source_line (INTEGER, not null): line of the declaration, 1-based per the Compiler Tree API’s LineMap; the store holds the parse’s own convention and an editor surface converts to its own. A parse positions every declaration it reads, so -1, that API’s own no-position sentinel, is defensive: it is carried through rather than dropped, because a declaration whose position is missing still has a doc comment worth holding
source_column (INTEGER, not null): column of the declaration, 1-based on the same terms as source_line
javadoc (CHARACTER VARYING, nullable): the declaration’s doc comment as the parse retained it, stripped; NULL where the declaration carries none. Display material, never a dimension

java_file

A .java file whose declarations this store holds, and the stamp they were read at. The family’s refresh unit: one transaction per file, retained when the file still hashes to its stamp and rewritten whole when it does not, so an edit costs one parse rather than a workspace walk. A row exists exactly while the last walk covering the file’s root saw it, so a file deleted under a walked root loses its row and its declarations with it.

Primary key: (file).

Columns

file (CHARACTER VARYING, not null): absolute normalised path of the source file; the family’s partition dimension and the grain its refresh runs at. Path form, as store_source spells a schema file, but never a store_source row (see this family’s charter) and never joined to jvm_class.source_name, which names a classpath entry rather than a source file
source_root (CHARACTER VARYING, not null): the walked root the file was reached under, on jvm_class.source_name’s terms: where the row came from, and so the scope whoever put it there owns. A walk prunes the files that left its own roots and leaves a sibling module’s alone. A file reachable under two nested roots is attributed to whichever root reached it first in the walk’s own order, one row either way
stamp (CHARACTER VARYING, not null): content hash of the file as parsed, on ClasspathSources' terms and for its reasons: modification time is a heuristic that a checkout, a rebase or a container layer defeats. NOT NULL because a file that cannot be read cannot be parsed either, so there is no partially-written partition to record

java_method_declaration

A method declaration on a declared class: one row per declaration, not one per resolvable name. Overloads are separate rows, so a consumer asking for a name gets as many rows as the class declares and the count is the resolution outcome; that is what replaces an index which dropped colliding keys into a side set of ambiguous ones and kept a first-declaration-wins view beside it. A constructor is a declaration and earns a row under the parse’s own name for it, where jvm_method excludes constructors: the two populations are not required to agree, and this is one of the places they do not.

Primary key: (file, class_name, method_name, ordinal). Foreign key: (file, class_name) references java_class_declaration (file, class_name).

Columns

file (CHARACTER VARYING, not null): the source file the declaration is written in; the family’s partition dimension and the key’s leading column
class_name (CHARACTER VARYING, not null): the declaring class, as java_class_declaration spells it
method_name (CHARACTER VARYING, not null): the declared method name; not a key on its own, overloads sharing it
ordinal (INTEGER, not null): declaration order within one file, class and method name, 0-based: the overload discriminator that keeps this key natural where the classfile side uses a descriptor. It follows the parse’s source order, so it is stable across re-parses of unchanged text and says nothing about which overload a call would bind to
parameter_count (INTEGER, not null): the declared arity, which is what an unattributed parse can know: parameter types resolve to unqualified names as written rather than to the erased types jvm_method_parameter carries, so arity is the part that is a fact and the types are deliberately absent
source_line (INTEGER, not null): line of the declaration, 1-based per the Compiler Tree API’s LineMap; the store holds the parse’s own convention and an editor surface converts to its own. A parse positions every declaration it reads, so -1, that API’s own no-position sentinel, is defensive: it is carried through rather than dropped, because a declaration whose position is missing still has a doc comment worth holding
source_column (INTEGER, not null): column of the declaration, 1-based on the same terms as source_line
javadoc (CHARACTER VARYING, nullable): the declaration’s doc comment as the parse retained it, stripped; NULL where the declaration carries none. Display material, never a dimension

← Schema index