brooklyn-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ahgittin <>
Subject [GitHub] incubator-brooklyn pull request: Versioning catalog items
Date Tue, 04 Nov 2014 14:09:30 GMT
Github user ahgittin commented on the pull request:
    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
    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
    `CatalogItem` instances themsleves should be updated to have the following fields to identify
      * '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
    (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 or file a JIRA ticket
with INFRA.

View raw message