declareSchemaVersion method

Registration declareSchemaVersion(String version, { String? namespace, })

Gives the schema version of the tools under this view's namespace — the plugin's, or namespace through the root — by the rule a server's schema version follows: a new tool or optional argument is a minor, a removed tool or a new required argument a major.

Honoured whenever it is called. Tools of the namespace added before it are given the version in their _meta too, and a running server offers them again with it, so a plugin that declares after adding is not left announcing nothing. Through a plugin's view namespace must be left out or be the plugin's own, and the version is the one of every tool under it, whichever plugin of the package added them.

Returns the Registration that withdraws the declaration. Through a plugin's view it is also withdrawn when the plugin is switched off, as its tools are, so flutter3d.schema stops naming a namespace whose tools are gone.

Implementation

Registration declareSchemaVersion(String version, {String? namespace}) {
  final scope = _scope;
  final space = scope?.manifest.namespace ?? namespace;
  if (space == null) {
    throw ArgumentError.value(
      version,
      'version',
      'the application names the namespace the version is for',
    );
  }
  if (scope != null && namespace != null && namespace != space) {
    throw PluginException(
      'plugin "${scope.manifest.id}" declared the schema version of the '
      'namespace "$namespace": a plugin declares its own namespace\'s, '
      '"$space", only',
    );
  }
  if (!RegExp(r'^\d+\.\d+\.\d+$').hasMatch(version)) {
    throw ArgumentError.value(version, 'version', 'is not MAJOR.MINOR.PATCH');
  }
  _store.schemaVersions[space] = version;
  _store.restamp(space);
  _store.changed();
  final registration = Registration(() {
    if (_store.schemaVersions[space] != version) return;
    _store.schemaVersions.remove(space);
    _store.restamp(space);
    _store.changed();
  });
  scope?.track(registration);
  return registration;
}