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: One .java file whose declarations this store holds, and the stamp they were read at.
java_class_declaration: One class, interface, enum, record or annotation declaration written in a source file, at the position the parse read it.
java_method_declaration: One method declaration on a declared class.

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 code_ 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 reading 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

One class, interface, enum, record or annotation declaration written in a source file, at the position the parse read it. For example the FilmService declaration at line 12 of that file, carrying the doc comment written above it.

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 code_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

One field declaration on a declared class, meaning a variable whose immediate encloser is the class. For example the FILM_ID constant on a generated Film table class, which is how a column’s own declaration becomes reachable.

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

One .java file whose declarations this store holds, and the stamp they were read at. For example a consumer’s FilmService.java, under the root it was walked from and stamped with the content hash it was parsed at.

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 code_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 code_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, spelled <scheme>:<hex> like every stamp SourceStamp writes and always the sha256: scheme here, this family reading every file it stamps. 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
read_at (TIMESTAMP, nullable): when the content behind this row’s stamp began being read, on store_source.read_at’s terms and for its reasons: written for every file a refresh hashed, whether it rewrote the row or found the stamp still current, and taken before the walk that read the file rather than at the write. A refresh that can establish the file has not moved since this instant skips the hash entirely, which is the whole saving; a refresh that cannot hashes it exactly as it did before the column existed. NULL only where no pass has dated the row yet, which is a transient state rather than the cold-start one: a DDL change rebuilds every persisted store, so the first pass after this column arrived fills it. What makes a session start cold is the comparison rather than the null, a value a previous session wrote being below this session’s floor

java_method_declaration

One method declaration on a declared class. For example the first findFilm declaration on FilmService at ordinal 0, beside a second overload of the same name at ordinal 1.

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 the reading 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