Github user ahgittin commented on the pull request:
https://github.com/apache/incubator-brooklyn/pull/92#issuecomment-61643946
After a lot of thought here is my thinking:
**Everything in catalog gets a version number**
* If version is not supplied on a catalog addition, normally:
* If no versions are present, we set `0.0.0`
* If the only versions that are present are `0.0.0` or `0.0.0_N` we set
`0.0.0_M` where `M` is one more than the largest such `N` (i.e. so we
monotonically increase a qualifier)
* If other versions are present, we fail
* If a version *is* supplied but it is already present, normally we apply
the monotonic increasing strategy above
* If a version is supplied and is not present, we add it
* The exceptions to the *normally* items above are that if a `force`
parameter is supplied with a version number, we will set it always, replacing
items which may exist; if `force` is supplied without a version number, we fail.
This allows us to have unique explicit versions for everything, unless a
user has forced something (which would only be done for cleanup.)
**There is a preferred/default version**
So references *may* specify a version but do not have to. References to
specific versions should follow the `catalogItemId` nomenclature of
`my-catalog-item-symbolic-name:0.0.0`. (In some contexts a separate `version`
key might be supported, but it might be better not to.)
A user could set this by including `isDefaultVersion: true` when adding.
This tag would be interpreted specially: it would be persisted, but it would
also have the effect of clearing any such tag in any other version.
`isDefaultVersion: false` would also be permitted, and it would prevent a
version from being available as default.
To determine the default/preferred version at runtime, the system chooses:
* The unique entry with `isDefaultVersion: true`, if there is one (if there
is multiple it should probably clear lower numbers and log a warning ...
probably means someone has been mucking with catalog files); otherwise
* The highest non-SNAPSHOT version which does not have `isDefaultValue:
false` set, if present; otherwise
* The highest version which does not have `isDefaultValue: false` set;
otherwise
* It reports that no such entity is available
**As for data structures...**
The field `catalogItemId` in many places (e.g. in `Entity`) should always
be in the format `symbolic-name:version`.
`CatalogItem` instances themsleves should be updated to have the following
fields to identify them:
* 'id' -- the random ID field exists (it is inherited) but never used; it
might be persisted which could be useful for some types of tracking; `getId()`
is overwritten to return `getCatalogItemId()`
* `catalogItemId` -- this should always be set to
`symbolicName+":"+version` whenever either of those two fields changes; never
`null`
* 'symbolicName` -- cf OSGi property, this is the version-less name of
the item; it replaces `registeredTypeName`; never `null`
* `version` -- this is an OSGi-style version (maven style also accepted);
treated as semver; never `null`
* `displayName` -- this is a human-readable name; it is displayed in the
catalog, along with `catalogItemId`; if `null`, the getter returns
`catalogItemId`; it should replace `name` in most places (though in some places
`catalogItemId` or `symbolicName` should perhaps be used)
(Other fields e.g. `javaType` and `description` continue exist but may be
null, although at least one of a `javaType` or a `yamlPlan` is required.)
I think we will have to keep the old fields due to persistence but let's
deprecate them; if they can be migrated on rebind to the new fields that would
be great as it makes it easier to mark the old ones as transient and remove
them in time.
**On the API and YAML**
Versions may be specified either using `name:
my-catalog-item-symbolic-name:0.0.0` or `{ name: my-catalog-item-symbolic-name,
version: 0.0.0 }`.
Additionally, `symbolicName` or `id` are also accepted as ways to set the
symbolic name. `name` has lower priority and is used also to set
`displayName`. Some rules:
* If `symbolicName` *and* `id` are specified, it is an error if they are
not identical.
* If `name`, `displayName`, and either `symbolicName` or `id` is specified,
we warn that `name` is being ignored
* If `symbolicName` (or `id`, or `name` in the absence of the other two)
contains a `:`, everything after the `:` is interpreted as a version, and must
be valid as per semver/osgi/maven regexing. The internal `symbolicName` does
*not* store the version, whereas the `catalogItemId` *does*. If an additional
`version` key is supplied, its value must match identically.
There should be an API call to set a default version.
On deletion, a version is required. If a `catalogItemId`is in use, an
error is thrown, unless `force` is specified, in which case the item is deleted
(and corresponding entities will not rebind unless it is added back).
---
Does this hang together? Does it seem right? @aledsage @neykov
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at [email protected] or file a JIRA ticket
with INFRA.
---
