Hi all,
The YAML format for adding catalog items accepts several different ways
of defining them. This has led to our examples being inconsistent, our
code more complicated, and potential confusion for users when they see
different things that turn out to mean the same.
I think we should standardise on one approach, and deprecate the other ways.
---
_*Current Code*_
An example .bom file is shown below:
brooklyn.catalog:
items:
- id: entity1
version: "1.0.0"
itemType: entity
item:
type: org.apache.brooklyn.entity.machine.MachineEntity
Variants:
* If defining just a single item in the .bom file, you can optionally
miss out the "items".
* You can miss out the "itemType" - it will guess at it by trying to
treat it as an entity, a template, a location or a policy. The
default is "entity".
* You can include "services:" for entity or template types, or you can
miss it out if there is just one entity in the item.
* Similar to "services:", you can include "brooklyn.policies:" or
"brooklyn.locations:".
If itemType is missing, this helps to infer the type. If it does not
agree with itemType, then we add it as the item type and it will
fail later.
* You can define the item metadata at any level - it could be directly
under "brooklyn.catalog" (in which case it applies to all items), or
under a specific item (in which case it overrides any more general
metadata).
An example of a .bom for a single item is shown below:
brooklyn.catalog:
id: entity2
version: "1.0.0"
itemType: entity
item:
type: org.apache.brooklyn.entity.machine.MachineEntity
---
_*Proposal*_
I suggest we have the following stricter rules. Anything else is
deprecated, logging a warning.
* Always include "itemType".
* For entity, policy and location: do not include "services:",
"brooklyn.policies:" or "brooklyn.locations:" - i.e. it will expect
exactly one type in the item.
* For template, always expect "services:" (even if there is just one
thing). This is consistent with the YAML required when deploying an
application.
* Always include "items", even if there is just one item in it.
(reasoning: we do not support "service" versus "services", so why
support "item").
We should change the following (breaking backwards compatibility,
because it's really a bug):
* If the itemType differs from the actual type of the item, then fail.
Aled
p.s. I'm in two minds about "item" versus "items": it is simpler with
the single item, and having "item" underneath "items" means it's not
quite like the "services" analogy.
