brooklyn-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Aled Sage <aled.s...@gmail.com>
Subject Re: [PROPOSAL] catalog YAML format consistency
Date Mon, 20 Jun 2016 17:08:06 GMT
Thanks all,

Alex's suggestion makes a lot of sense. So we should:

 1. agree short-term preferred syntax
 2. update our docs and examples to *always* use that
 3. discuss improvements for a more powerful syntax, and the longer term
    bigger long-term overhaul.

It should be trivial to warn someone if they have not included the 
"itemType", so I think we should do that short-term.

---
Any more opinions for the preferred syntax?

Aled


On 20/06/2016 14:44, Geoff Macartney wrote:
> +1 for the proposal, and for staging it.
>
> I actually quite like the suggestion of making items/item entirely consistent (by requiring
both).   If I have
>
> 1 brooklyn.catalog:
> 2   version: "2.0.0-SNAPSHOT"
> 3
> 4   item:
> 5     type: server
> 6     id: testy
> 7     name: Testy McServer
>
> and decide for some reason that I need a second item (maybe move one here from another
file), I can’t just add it below line 7.  Instead I have to go editing lines 3-7 to add
“items:” and change the indentation. Sticking to items+item consistently will make this
sort of refactoring less tedious.  Just a thought.
>
> Geoff
>
>
>
>
> ————————————————————
> Gnu PGP key - http://is.gd/TTTTuI
>
>
>> On 20 Jun 2016, at 14:17, Svetoslav Neykov <svetoslav.neykov@cloudsoftcorp.com>
wrote:
>>
>> +1 for the proposal.
>>
>> I find the current item-items functionality logical. "item" is used in leaf items,
"items" is used in non-leaf items. Forcing a non-leaf root just so we always have "items"
is overhead.
>>
>> Svet.
>>
>>
>>> On 20.06.2016 г., at 15:47, Aled Sage <aled.sage@gmail.com> wrote:
>>>
>>> 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.
>>>
>>>
>


Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message