[hue] Implement Hue CLIP 2

[andrewfg]

Introduction

This issue is a place holder for the planned implementation of API v2 in the Hue binding.

Specifically it requires the following..

• Implement new CLIP 2 endpoints
• Implement new CLIP 2 DTOs
• Implement SSE

Dependency

Any PR arising from this issue will depend on #11842 being merged first.

Approach

I am tending to follow the same approach as I took with the HDPowerView API generation change as follows..

• Refactor the OH facing parts of the binding to use abstract base DTO classes (such as Scene, Light, etc.) and access the Bridge via an abstract base communication class HueBridge
• Relocate the current API V1 implementation code from Scene, Light, etc., and HueBridge into new SceneV1, LightV1, etc., and HueBridgeV1 implementation classes which implement/extend the abovementioned base abstract classes
• Write new SceneV2, LightV2, etc., and HueBridgeV2 implementation classes that implement/extend the base abstract classes too.
• Use a Config Parameter in the the thing handler to select whether the OH facing code instantiates/consumes the xxxV1 or xxxV2 implementation classes.

This allows the the OH facing parts of the binding to remain almost unchanged. And the V1 code would remain functionally unchanged too; although the actual code has to be split between the xxx base/abstract class, and the xxxV1 implementation class.

In the case of the HDPowerView migration, we have the good luck that the manufacturer chose to keep the V1 and V2 DTOs fairly similar, with many fields being common, and only a subset of fields having changed names and meanings. However in the case of the Hue migration, I can already see that the DTOs have changed MASSIVELY between V1 and V2, so I can already say that unlike the HDPowerView migration which I was able to write in a week or so, this Hue migration will certainly take a lot longer.

In any case, before I start writing code, I will first write a Class Structure diagram similar to the one I wrote for #12678 (comment) -- this should help to clarify if my above mentioned approach would work (or not)..

Constraints

Two requests from @lolodomo ..

• Use the OH standards for the SSE implementation (JAX-RS +Jetty}.
• Keep the compatibility with the old bridge in case it does not support SSE.

---

Signed-off-by: Andrew Fiddian-Green [email protected]

[andrewfg]

Dead Code in API V1

Just to point out that the API V1 HueBridge class implements 16 public methods which are never actually called by any other parts of the binding (i.e. dead code). Therefore when I start to implement the API V2 I shall certainly NOT try to replicate those methods. However we should probably keep this dead code in the V1 implementation 'just-in-case' => WDYT?

[andrewfg]

Status Update

This is to give a brief status update of what I have done so far..

• created most of the DTO classes for API V2 json de-/serialization
• created code to prove that it is possible to connect to the Bridge API V2 server endpoints, and GET and parse the respective DTO instances
• created JUnit tests for the DTO classes, and tested them based on actual data read as above from my bridge
• created 'tag' interfaces so that V1 and V2 DTOs can be transferred within the binding in a version agnostic manner e.g. both API v1 FullLight and Api V2 Light2 classes implement the ILight tag interface, and so both classes can be transferred as arguments and return values in method calls independent of the actual class version being used.
• the ILight implements a generic as() method to cast the ILight reference to the respective actual V1 or V2 implemented class so it can be accessed within the upper levels of the binding as in the example below..

public void doSomething(ILight light) {
    // API version 1
    try {
        FullLight fullLight = light.as(FullLight.class);
        fullLight.doSomethingV1Specific();
    } catch (ClassCastException e) {
    }
    // API version 2
    try {
        Light2 light2 = light.as(Light2.class);
        light2.doSomethingV2Specific();
    } catch (ClassCastException e) {
    }
}

Next Steps

Next steps would be as follows..

• overriding goal is that the OH facing parts of the code e.g. Things, Items, Channels, Properties, Config Parameters, etc. shall all remain the same.
• re-factor the HueBridge class to produce/consume (say) ILight references and actually write/read FullLight or Light2 instances of ILight depending on an API version configuration parameter.
• re-factor the Thing handler classes to produce/consume (say) ILight references and actually write/read FullLight or Light2 instances of ILight depending on an API version configuration parameter.
• implement the SSE call-back mechanism, also implementing ILight references to push DTO classes to the upper levels of the binding

[andrewfg]

^
Just an update on my progress..

I was originally planning to map the CLIP 2 DTO classes onto the old API v1 DTO classes (by having both classes implement the same 'tag' interface as described in the post above).

BUT after much experimenting, and with much regret, I am forced to conclude that the old API v1 DTO classes were (sorry to say it) not well structured, and have also accumulated too much 'spaghetti code', so that this mapping approach is simply not a feasible solution.

So instead I have written clean new DTO classes with clean new thing handlers for both the bridge and the things.