readallproperties operation - closes #51

[benfrancis]

Closes #51.

This PR defines request and response message formats for a readallproperties operation.

There was some discussion in #27 about whether all the property readings should be contained in one message or whether they should all come in separate messages.

Having given this some thought my personal preference is for all of the property readings to be contained in a single message, for the following reasons:

• A Consumer doesn't have to correlate multiple responses with a single request and figure out when all of the property readings have been received and implement some kind of timeout if an incomplete set of properties values is sent.
• It satisfies the current rule that each request only receives a single response (vs. multiple notifications)
• If a Consumer wants to receive individual property readings as they become available they will also be able to use the observeallproperties operation, where each property reading will arrive in a separate message when it changes. We could potentially also have that operation report the current value of all properties in individual messages when the observation is first started which would satisfy that use case.

Let me know what you think.

---

Preview | Diff

[hspaay]

This all looks good with only a single exception.
I recommend the use of 'value' instead of 'values' as the response value, as it holds well ... the response value. That the content in this case is an object with property values doesn't neccesitate the change of the name from value to values. Instead using the same name for all response types simplifies implementation as the there is no need to look for different property names different operations.

[hspaay]

I recommend to use the name 'value' to contain the response value instead of 'values'.

1. This is consistent with readproperty.
2. The caller is requesting readallproperties. The result is a value that holds an object. Nothing is gained by using a different name. Instead the developer has to check the operation to know the result can be found under a different property name.
3. Implementation is easier using 'value' as the value of the response can always be found in the property 'value'.

[benfrancis]

Thank you for the review @hspaay.

This all looks good with only a single exception. I recommend the use of 'value' instead of 'values' as the response value, as it holds well ... the response value. That the content in this case is an object with property values doesn't neccesitate the change of the name from value to values.

The values member contains the values of multiple properties, not just a single value.

Any code implementing this operation would have to have different logic for the different operations and treat value and values differently regardless of whether they share the same name.

My personal opinion is therefore that it's important to give it a different name to signal that they are different and that in the case of values the top level keys in the object denote the names of properties, not their values. It's a map of name-value pairs.

Of course if I'm alone in this view I am open to the group consensus.

Instead using the same name for all response types simplifies implementation as the there is no need to look for different property names different operations.

I definitely don't agree that the payloads of all operations should have a generic member called "value" if that's what you mean.

As you know, in my proposal in #42 (which is a middle ground between the original strawman proposal and your suggestion for a single payload format for all messages) I still use the terms input, output and data in different payloads to clearly show which data schemas different members map onto.

Whilst I understand the OOP instinct to abstract similar looking classes, experience tells me too much abstraction can be harmful and actually I think clarity is more important than consistency in this case. I don't really believe it would necessarily simplify implementation either because the logic has to be different regardless.

That's really a separate topic but as always I'm open to other views if the consensus leads elsewhere.

[hspaay]

@benfrancis Yes I know we are on a different page with this one. Understandable as you view the message as the operation while I view it as a generic envelope. Either way it will be able to do its thing so its all good :) Whatever the end decision is I'll update hiveot accordingly.
I am curious to hear what others think.