Options
The main builder, spring_core_dart_generator:spring_core_dart, takes four options. They go into the build.yaml of the package being built, next to its pubspec.yaml. The other builders of the package take no options.
# build.yaml
targets:
$default:
builders:
spring_core_dart_generator:spring_core_dart:
options:
aop_proxies: all
aop_prune: true
aop_defer: false
dart_defines_exclude: []
Without a build.yaml, or without options:, every option has its default. That is the right choice for almost every application.
Why
The defaults give the smallest code that still behaves like Spring. The options exist for the cases the build cannot decide alone: advice added in code at run time, a library always reached through a starter, properties that must not be set by --dart-define.
The options
| Option | Values | Default | Invalid value |
|---|---|---|---|
aop_proxies |
all, interfaces, none |
all |
ArgumentError: Expected all, interfaces or none |
aop_prune |
true, false |
true |
ArgumentError: Expected true or false |
aop_defer |
true, false |
false |
ArgumentError: Expected true or false |
dart_defines_exclude |
a list of property name prefixes | [] |
ArgumentError (see below) |
An invalid value fails the build before any file is generated.
aop_proxies
Which beans may get a generated AOP proxy class.
| Value | Meaning |
|---|---|
all |
A proxy class for every bean whose class, or one of its interfaces, can be implemented; a subclass proxy for a class that can only be extended. |
interfaces |
Proxies only through a bean's abstract supertypes. A bean without one gets no proxy. |
none |
No proxy classes. AOP cannot advise the beans of the module. |
The value must be one of the three names, written as text in YAML.
aop_prune
With true, the outputs that know every piece of advice of the application leave out the proxy classes, and the proxy members, that no advice can match:
- the
@SpringBootApplicationoutput; - the
@ComponentScanmodules of an application (publish_to: noneinpubspec.yaml): nothing outside imports them.
The @ComponentScan modules of a library package are never pruned. The lib/ modules of a starter (a package with lib/spring_auto_configuration.dart) leave to the application the proxy classes only its aspects can match (AopProxyFactory.deferred), and the application writes those its pointcuts may match.
With false, every bean keeps its proxy class with every member, starters defer nothing, and the application writes every proxy left to it. Use false when advice is registered in code at run time (a registrar, a BeanFactoryPostProcessor, registerSingleton, Advised.addAdvisor): with pruning on, the startup fails in that case and says so.
Everything about it: AOP proxies: pruning and deferring.
aop_defer
With true, the lib/ modules of a library package without lib/spring_auto_configuration.dart leave to the application the proxy classes only its aspects can match, as a starter's modules do. This is for a library whose modules a starter's auto-configuration imports, so the application's build finds them through it (spring_boot_actuator sets it). Any other library keeps every proxy by default, because any module may import it.
Deferring needs aop_prune: true in the same build. In an application package (publish_to: none) the option changes nothing: its modules are pruned instead.
dart_defines_exclude
The @SpringBootApplication output lists in springApplication.dartDefines every property the application may read, so --dart-define can set it (see --dart-define keys). The properties under a prefix of dart_defines_exclude are left out of that list, in both of their forms (spring.flutter.theme.mode and SPRING_FLUTTER_THEME_MODE). They can still be set by config files, environment variables and arguments.
targets:
$default:
builders:
spring_core_dart_generator:spring_core_dart:
options:
dart_defines_exclude:
- spring.flutter.theme
- spring.datasource
How prefixes are read:
- A prefix covers every property under it, matched by whole
.-separated segments:spring.datasourcecoversspring.datasource.url, notspring.datasourceish. - Names are compared with relaxed binding, without case and ignoring
-and_inside a segment:spring.dataSource,spring.data-sourceandSPRING_DATASOURCEare the same prefix. - Each entry is trimmed; a trailing
.or[is dropped (spring.datasource.isspring.datasource).
Each of these fails the build with an ArgumentError:
| Value | Message |
|---|---|
not a list (dart_defines_exclude: spring.datasource) |
Expected a list of property name prefixes |
| an entry that is not a string | Expected a property name prefix (a string) |
an entry with * |
Wildcards are not supported: a prefix already covers every property under it (write spring.datasource, not spring.datasource.*) |
| a blank entry | Expected a property name prefix, not a blank entry |
other characters than letters, digits, _ . - [ ] |
Expected a property name prefix: letters, digits, _ . - [ and ] |
Full examples
An application that adds advice at run time
# build.yaml of the application
targets:
$default:
builders:
spring_core_dart_generator:spring_core_dart:
options:
# A registrar adds an advisor the build cannot see:
# keep every proxy class and every member.
aop_prune: false
A Flutter app that keeps theme properties away from --dart-define
# build.yaml of the application
targets:
$default:
builders:
spring_core_dart_generator:spring_core_dart:
options:
dart_defines_exclude: [spring.flutter.theme]
A module that never needs AOP
# build.yaml of a package
targets:
$default:
builders:
spring_core_dart_generator:spring_core_dart:
options:
aop_proxies: none
The spring_properties builder (hand-written starters)
Most of a starter can be written by hand, but the binding of its typed @ConfigurationProperties classes is best generated. That raises a problem: the starter's lib/ imports the generated file, and the starter's example (built by the main builder) imports lib/. A builder cannot read what another input of its own phase writes, so the example's build would not see the file.
The spring_properties builder solves it. It is the main builder, limited to lib/, in a phase of its own that runs before the main one. It is off unless a package turns it on (auto_apply: none), and it takes the same options as the main builder.
A typical starter's build.yaml:
# build.yaml of a starter (spring_boot_starter_cache)
targets:
$default:
builders:
# The main builder writes only the example's application.
spring_core_dart_generator:spring_core_dart:
generate_for: [example/**]
# The binding of the typed properties, before the main builder runs.
spring_core_dart_generator:spring_properties:
enabled: true
generate_for: [lib/src/config/**]
spring_core_dart_generator:spring_test:
enabled: false
A library a starter imports, with aop_defer (from spring_boot_actuator):
# build.yaml of spring_boot_actuator
targets:
$default:
builders:
spring_core_dart_generator:spring_core_dart:
enabled: false
spring_core_dart_generator:spring_properties:
enabled: true
generate_for: [lib/src/properties/**]
options:
# The actuator starter's auto-configuration imports these
# modules: the application writes the proxy classes its aspects
# need, as for a starter's own modules.
aop_defer: true
spring_core_dart_generator:spring_test:
enabled: false
Options are set per builder: options given to spring_core_dart do not apply to spring_properties, and the other way round.
enabled and generate_for are build_runner's own keys, available for every builder. The builders of the package and what they write are on The builders.