Skip to content

Instantly share code, notes, and snippets.

@ctomc

ctomc/collection-api.md

Last active Aug 29, 2015
Embed
What would you like to do?
Collection & Complex attributes manipultation API

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])

@bstansberry

This comment has been minimized.

Copy link

@bstansberry bstansberry commented Aug 14, 2014

[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

@ctomc

This comment has been minimized.

Copy link
Owner Author

@ctomc ctomc commented Aug 14, 2014

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

@jamezp

This comment has been minimized.

Copy link

@jamezp jamezp commented Aug 14, 2014

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 :)

@kabir

This comment has been minimized.

Copy link

@kabir kabir commented Aug 14, 2014

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.

@heiko-braun

This comment has been minimized.

Copy link

@heiko-braun heiko-braun commented Aug 15, 2014

+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)
@aloubyansky

This comment has been minimized.

Copy link

@aloubyansky aloubyansky commented Aug 15, 2014

I agree with Heiko.

@pilhuhn

This comment has been minimized.

Copy link

@pilhuhn pilhuhn commented Aug 18, 2014

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.

@ctomc

This comment has been minimized.

Copy link
Owner Author

@ctomc ctomc commented Aug 18, 2014

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

@ctomc

This comment has been minimized.

Copy link
Owner Author

@ctomc ctomc commented Aug 18, 2014

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

@hpehl

This comment has been minimized.

Copy link

@hpehl hpehl commented Aug 31, 2014

LGTM

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.