Collection & Complex attributes manipultation API

collection-api.md

Collection manipultation API

Proposal to add set of global operations for ease working with map & list attribute types. Operations mimic java colections. All indexes are 0 based!

Maps

put entry to map

:map-put(name=name-of-attribute, key=some-key, value="newvalue")

Remove entry from map:

:map-remove(name=name-of-attribute, key=some-key)

Get entry from map:

:map-get(name=name-of-attribute, key=some-key)

Empty map, note that is not the same as :undefine(name=name-of-attribute)

:map-clear(name=name-of-attribute)

Lists

Add element to list, with optional index where to put it

:list-add(name=list-attribute, value="some value", [index=5])

remove element from list, where you can provide value to remove or from which index to remove it.

:list-remove(name=list-attribute, [value="element-to-remove"], [index=3])

Get entry from list:

:list-get(name=name-of-attribute, index=5)

Empty list:

:list-clear(name=attribute-name)

Expand standard read/write operations

:write-attribute enhacements for complex attributes

Map write enhancements

:write-attribute(name=map-attribute.myKey value="newValue")

List write enhancements

:write-attribute(name=list-attribute[1] value="new-element-value")
:write-attribute(name=list-attribute.element-value value="new-element-value")

Map read enhancements

# return value of map-attribute with key "myKey"
:read-attribute(name=map-attribute.myKey)

List read enhancements

# return element under index 5 of list-attribute
:read-attribute(name=list-attribute[5])

Generic complex attributes enhancments

# return property.subproperty from complex attribute
:read-attribute(name=complex-attribute.property.subproperty)
# return subproperty of 5th property from complex attribute
:read-attribute(name=complex-attribute[5].subproperty)

# set subproperty of 5th property of complex attribute
:write-attribute(name=complex-attribute[5].subproperty, value="new-value")

# set property.subproperty.subsubproperty of attribute "complext-attribute to "new-value" 
:write-attribute(name=complex-attribute.property.subproperty.subsubproperty, value="new-value")

# return value of complex attribute with key "myKey"
:read-attribute(name=complex-attribute.myKey)
# return "property" of complex-attribute element on index 5
:read-attribute(name=complex-attribute[5].property)
# return object of complex-attribute element on index 5
:read-attribute(name=complex-attribute[5])

[index=-1], [index=-2] etc should work (I know the above was just an example, just saying this for the record)

Are indexes 0 or 1 based? I vote 0, as that is how ModelNode.get(int) works, and having two different schemes depending on how a user is approaching the API is bad

Added clarifications that all indexes are 0 based.
I found use for negative index is nice way for adding new entry to lists.

Would the :list-remove(name=list-attribute, value="foo") remove all entries with a value of foo?

:write-attribute(name=map-attribute[5].key value="new-key-name") seems a bit odd to me. Are there complex attributes that aren't maps/properties that allow the key to be updated? I know for sure there are complex attributes where the key should definitely not be allowed to be updated. How would you handle a use case like that?

This is just my opinion, but the allowing negative numbers for writing to lists seems weird. Why not just use the list-add? Well actually all the list/map write-attributes seem a bit weird to me if we already have custom operations for them :)

I agree with James, why have both custom ops to modify lists/maps and use write-/read-attribute. I prefer the custom ops, but there may well be some context I am missing.

+1 on the custom operation for list/map modifications.

But I am against the write-attribute changes and generic complex attributes . IMO we'd better be explicit about complex attributes and limit it to certain usecases:

• write-attribute is for simple attributes only and yields an error for complex types
• no support for generic complex attributes. these should become (child) resources themselves
• introduce an explicit ModelType.LIST and ModelType.MAP (i think the former already exists)

I agree with Heiko.

Why does :map-clear have an argument?

And like @heiko-braun I am against generic complex attributes. This ends up too quickly in conversion rat-holes.

@pilhuhn :map-clear needs name attribute to tell which attribute you are clearing :)

@jamezp & @kabir I have updated the proposed ideas for read/write-attributes to make them simpler and more strait forward.

LGTM