Skip to main content

Dictionary and code generation

Most applications need only a few of the steps on this page. 10.0 removes code generation options and generated classes that 8.15 had already deprecated, turns some 8.15 dictionary warnings into errors, and reuses upstream products' generated code by default.

The steps show up at different points of the upgrade:

When it shows upSteps
The Gradle build script doesn't compile1 (removed codeGen { } properties)
Your application code doesn't compile2 (generated table repositories), 3 (entity builders) and 4 (removed members)
The dictionary fails to build5 (framework fields), 6 (index blocks) and 7 (format names)
The build behaves differently8 (upstream reuse)
The build warns9 (fields dictionaries and the generated Fields object)

Every replacement in steps 2 to 5 already exists in 8.15. You can make those changes on 8.15 first, check that the application still works, and then upgrade.

These need no action:

  • Generated view repositories (<View>AsyncRepository and <View>Rx3Repository) are still generated, and keep the deprecation they had in 8.15, so you still see deprecation warnings where you use them. When convenient, move to AsyncEntityDb or SyncEntityDb.
  • Sequence codes shared by more than one table are now a warning, not a dictionary error.

1. Remove generateRepositories and generateCache from codeGen { }​

Applies to: applications whose Gradle build scripts set either property in a codeGen { } block, usually in a *-generated-dao or *-generated-view module.

Why: both properties have been removed from the code generation plugin.

What goes wrong if you skip this: a Kotlin build script that still sets either property fails to compile, with an unresolved reference.

What to do: delete both lines, and delete the codeGen block if it is now empty.

// 8.15
codeGen {
generateCache = true
generateRepositories = true
}

// 10.0
codeGen {
}

The other properties, productName, configModuleFilter, generateCompactToString and useCleanerTask, are unchanged.

If your system definition sets GenerateDatabaseRepositories, remove it too. 10.0 ignores it, without a warning.

2. Replace generated table repositories with the entity database​

Applies to: applications that set generateRepositories = true in 8.15 and use the generated table repositories. They were not generated by default.

Why: 10.0 no longer generates <Table>AsyncRepository, <Table>Rx3Repository or their implementation classes in the package global.genesis.gen.dao.repository.

What goes wrong if you skip this: any code that uses one of these classes no longer compiles.

What to do: inject one of the entity database interfaces instead of the repository:

InterfaceWhen to use it
AsyncEntityDbKotlin code
SyncEntityDbBlocking calls
RxEntityDbJava code that updates records. The update methods of AsyncEntityDb (updateBy, updateByRange and updateAll) are suspend inline, so Java can't call them. RxEntityDb is deprecated in 10.0, with no removal version set, so expect a deprecation warning; see Database layer.

Then change the calls. In this table, Trade stands for one of your table entities:

Generated table repository (8.15)Entity database (10.0)
update<Index>(keys..., transform), for example updateById(id) { ... }updateBy(Trade.byId(id)) { ... }
updateAll(transform)updateAll<Trade> { ... } on AsyncEntityDb, or updateAll(Trade.class, transform) on RxEntityDb
updateRange<Index>(keys..., transform)updateByRange(Trade.byTypeId(type)) { ... }
updateRangeStartToEnd<Index>(start, end, transform)updateByRange(Trade.byId(start), Trade.byId(end)) { ... }
getQueryBuilder()queryBuilder<Trade>() on AsyncEntityDb
getFirstInRange<Index>(key) and getLastInRange<Index>(key), for example getFirstInRangeById(id)getRange and getRangeFromEnd, with MIN_VALUE and MAX_VALUE as bounds for the other parts of the key, and MIN_STRING and MAX_STRING for String parts
get, insert, modify, delete, upsert, getRange, subscribe and the other reads and writesThe method with the same name, passed the entity or an index such as Trade.byId(id)

Two differences to watch for:

  • SyncEntityDb has updateBy and updateByRange, but no updateAll or queryBuilder.
  • insert on the entity database returns an InsertResult. The stored record is its record property.
// 8.15, with codeGen { generateRepositories = true }
class TradeCanceller @Inject constructor(
private val trades: TradeAsyncRepository,
) {
suspend fun cancel(id: String) = trades.updateById(id) { tradeStatus = TradeStatus.CANCELLED }
}

// 10.0
class TradeCanceller @Inject constructor(
private val db: AsyncEntityDb,
) {
suspend fun cancel(id: String) = db.updateBy(Trade.byId(id)) { tradeStatus = TradeStatus.CANCELLED }
}

The index accessor (byId here) and the field names come from your own dictionary.

3. Stop using the nested entity Builder, setIs setters and builder subclasses​

Applies to: application code, in Kotlin or Java, that builds generated entities.

Why: 10.0 removes three things from generated code:

  • the nested Builder class in every generated entity, which was deprecated in 8.15;
  • the deprecated setIs<Name> setters on generated builders;
  • the ability to subclass a generated builder: generated builders are now final.

What goes wrong if you skip this: code that uses any of them no longer compiles.

What to do: search your code for .Builder() on generated entity classes, for setIs calls on generated builders, and for classes that extend a generated *Builder. Then change them:

8.1510.0
Trade.Builder()Trade.builder(), or Trade { ... } in Kotlin
builder.setIsTied(value), for a BOOLEAN field IS_TIEDbuilder.setTied(value)
builder.setsuer(value), for a field ISSUERbuilder.setIssuer(value)
class MyBuilder : TradeBuilder()Not possible. Wrap the builder, or use it from your own class.

The setter names follow one rule. For a BOOLEAN field named IS_<NAME>, the setter is set<Name>. For every other field, the setter is set<FieldName>.

For a field whose name starts with IS but that is not a BOOLEAN, 8.15 also generated a deprecated alias with the Is removed: setActive next to setIsActive for a STRING field IS_ACTIVE, and the malformed setsuer next to setIssuer for ISSUER. 10.0 generates only setIsActive and setIssuer, so change any calls to the aliases.

4. Replace removed dictionary, system definition and code generation members​

Applies to: system definitions, custom application code and build tooling that use members deprecated in 8.15.

Why: 10.0 removes these members. Each one has a replacement that already exists in 8.15.

What goes wrong if you skip this: the script or code that uses them no longer compiles.

What to do:

RemovedUse insteadWhere it's usually used
dtaHosts(environment)genesisHosts(environment)The systems { } block of a *-system-definition.kts file
dictionary.sequenceIdFields (getSequenceIdFields() in Java)dictionary.idSequences (getIdSequences())Custom code that reads GenesisDictionary
global.genesis.codegen.GenesisVersion.versionglobal.genesis.commons.utils.GenesisVersion.versionCustom Gradle or build tooling
LambdaExtractor and LambdaListener (global.genesis.dictionary.reader.kts)TableDerivedFieldAnalyzer, in the same packageCustom tooling that reads derivedField lambdas from a tables dictionary

5. Fix framework field declarations that 8.15 only warned about​

Applies to: dictionaries that declare the framework fields RECORD_ID or TIMESTAMP themselves.

Why: the framework adds and manages these fields. In 8.15, declaring them with the wrong type, or with autoIncrement(), logged a warning that said this would be an error after 8.15. In 10.0, it is an error. 10.0 also rejects an inline TIMESTAMP field (declared with field(...) inside table { }) of type LONG, which 8.15 accepted without a warning.

What goes wrong if you skip this: the dictionary fails to build, during code generation and when a process starts, with one of the errors in the table below.

What to do:

DeclarationError in 10.0Fix
RECORD_ID with a type other than LONGFramework field RECORD_ID can only be used as type LONGDelete the declaration, because the framework adds the field, or make it LONG.
TIMESTAMP with a type other than LONG or NANO_TIMESTAMP in a fields dictionary, or an inline TIMESTAMP with any type other than NANO_TIMESTAMP, including LONGFramework field TIMESTAMP can only be used as type NANO_TIMESTAMPDelete the declaration, or make it NANO_TIMESTAMP.
autoIncrement() on RECORD_ID or TIMESTAMPFramework managed field <name> does not support sequenceRemove the autoIncrement().

To find most of these before you upgrade, run code generation or a remap on 8.15 and look in its output for warnings that start Detected unsupported field type on RECORD_ID, Detected unsupported field type on TIMESTAMP or Illegal sequence detected on framework field. 8.15 doesn't warn about an inline TIMESTAMP of type LONG, so search your tables dictionaries for field("TIMESTAMP" as well.

6. List inline fields of an index by name​

Applies to: tables dictionaries that declare a field inline, with field(...) inside table { }, and then refer to it inside a primaryKey { } or indices { } block.

Why: an index block can't add an inline field to the index. In 8.15, such a field was left out of the key without any error, so the index had fewer fields than the dictionary showed, or none at all. 10.0 rejects the index instead, and it also rejects an index that has no fields.

What goes wrong if you skip this: the dictionary fails to build with an error such as this one, where <key> is the name of the index:

Primary key <key> on table TRADE references TRADE_ID, declared with field(...) inside table { }, which an index block cannot add to the index. List every field of the index by name instead, e.g. primaryKey("FIELD_A", "FIELD_B").

or, for an index that has no fields:

Primary key <key> on table TRADE has no fields; list them by name, e.g. primaryKey("FIELD_NAME"). ...

What to do: list every field of the index by name, as a string.

// 8.15: TRADE_ID was silently left out of the primary key
table(name = "TRADE", id = 11000) {
val tradeId = field("TRADE_ID", STRING(64))
primaryKey {
tradeId
}
}

// 10.0
table(name = "TRADE", id = 11000) {
field("TRADE_ID", STRING(64))
primaryKey("TRADE_ID")
}

For other indices, use indices { unique("FIELD_A", "FIELD_B") } or indices { nonUnique("FIELD_A") }. You can also call .primaryKey() on the inline field itself.

If an index changes because of this fix, the database schema changes too, so run a remap after the upgrade.

7. Import java.text and Joda-Time format classes explicitly in tables dictionaries​

Applies to: *-tables-dictionary.kts files that use the names DateFormat, DateTimeFormat or NumberFormat from a star import, such as import java.text.* or import org.joda.time.format.*.

Why: in 10.0, tables dictionaries import DateFormat, DateTimeFormat and NumberFormat from global.genesis.config.dsl.format by default, so that you can use them to set the format of an inline field. These default imports take precedence over a star import.

What goes wrong if you skip this: those names now refer to the Genesis classes, and the dictionary fails to compile.

What to do: import the class you want by its full name, for example import java.text.NumberFormat.

8. Check your build with upstream reuse​

Applies to: every application. Most need no change.

Why: in 10.0, the build reuses the generated code that each upstream product (Genesis itself and every PBC your application depends on) has already published, instead of generating it again from that product's dictionary files. This is switched on by default. For how it works, and for every setting mentioned here, see Code generation and upstream reuse.

What goes wrong if you skip this: in most cases, nothing. In the cases below, the build warns, fails, or is slower than it needs to be.

What to do: check the table below. In every case, the build's warning or error names the value to set.

If your application...Then
Depends on a PBC version that was published before 10.0That version has no slice jars to reuse, and the build reports it. Upgrade the PBC to a version built with Genesis 10.0, or list it in genesis.codegen.overrideSlices to generate its code locally.
Overrides an upstream product's dictionary fileThe build switches upstream reuse off for that module, with a warning, and generates every upstream product locally. To avoid the warning, set genesis.codegen.reuseUpstream=false yourself.
Sets a system definition value that an upstream product's dictionary reads, such as ADMIN_PERMISSION_ENTITY_TABLE and ADMIN_PERMISSION_ENTITY_FIELDThe build generates those products locally and logs a *** DEPRECATION WARNING ***. To move to the future behaviour now, set genesis.codegen.reuseUpstream.strict=true and list those products in genesis.codegen.overrideSlices.
Adds fields to an upstream product's table with tableUnionThe build fails until you list that product in genesis.codegen.overrideSlices.
Is a product that others depend on, and has a dictionary file whose name doesn't start with <productName>-The build fails. Rename the file, for example to position-tables-dictionary.kts.
Has a build problem that you trace to upstream reuseSwitch it off with genesis.codegen.reuseUpstream=false in gradle.properties, or codegenReuseUpstream = false in the genesis { } block of settings.gradle.kts.

9. Optional: move fields out of fields dictionaries​

Applies to: applications with *-fields-dictionary.kts files, or with code that uses the generated Fields constants, such as Fields.PRICE.

Why: 10.0 deprecates fields dictionaries (the fields { } block) and the generated Fields object, with no removal version set. Both keep working. Fields are now declared inline, inside each table { } block, and code refers to them through the table, for example TRADE.PRICE.

What goes wrong if you skip this: nothing fails. You see deprecation warnings in the IDE and when the scripts are compiled, and each process logs this warning once:

Fields dictionaries (*-fields-dictionary.kts): Deprecated in 10.0. Declare fields inside table { } in a *-tables-dictionary.kts instead. A field used by several tables must be redeclared in each. They remain supported and no removal version is set.

What to do: there's no deadline, so you can do this after the upgrade. Applications with many fields that several tables share may prefer to wait, because each table needs its own declaration of the field, or a sharedField.

When you do move, the build can do most of the work:

  1. Run inlineDictionaryFields from your dictionary-cache module, for example ./gradlew :<product>-dictionary-cache:inlineDictionaryFields. It is in the genesis-dev-tools task group. It moves each table's fields from the fields dictionary into the table, based on the dictionary that code generation built. It reports how many fields it moved, lists any it couldn't move, and writes a report for each file.
  2. As a separate Gradle run, run the verification command that the task prints, verifyInlineDictionaryFields. It checks that the dictionary built from the changed files is the same as the one you started from.
  3. In your code, replace each Fields.<NAME> with the table's own handle, such as TRADE.PRICE, imported from global.genesis.gen.config.tables. A field that exists only inline has no Fields constant.
  4. Delete the fields dictionary once it is empty.
  5. Run a remap without --commit against a copy of each environment. It should report no schema changes. If it reports any, a size, nullability or default differs from the old declaration.

If you move fields by hand instead, the two kinds of declaration have different defaults, so a field copied as written can change its size or nullability. See Moving fields into tables for how each default maps.