Add some generalized documentation

[iheart2code]

As it is, I have a lot of questions, but here are a few that could be answered.

1. Does LFXClient need to be open for all commands or just discovery?
2. Can I have multiple instances of LFXClient open, or should I use a single instance?
3. Can LFXLight and LFXGroup instances be used without LFXClient being open?

[loefberg]

I'm not sure if this goes in readme, wiki or the javadoc so I'm writing it here for now.

Does LFXClient need to be open for all commands or just discovery?

LFXClient needs to be open for all commands. To send and receive messages you have to have routing information. So you need to have a live network loop. I don't see a way around that.

Can I have multiple instances of LFXClient open, or should I use a single instance?

Right now, you can only have one instance of LFXClient because if you have more than one and closes one of them, all of them will close. This will be fixed in #22 but then you'll have two parallel network loops which in most cases it a waste. Things are supposed to be thread safe, if not then that is a bug.

Can LFXLight and LFXGroup instances be used without LFXClient being open?

No, the LFXClient needs to be open. As I said above, you need a network loop to send and receive messages.

I wanted to separate the responsibilities. I wanted the "network stuff" to be separate from the state. So with this in mind I put everything that goes into sending and receiving messages in the impl.network package. To be able to send messages you need to know some basic routing information so that also goes in there. Driving all this is LFXNetworkLoop (which is currently a singleton). So you open a network loop and it starts discovery and updates its routing table.

The network loop alone is pointless. You need someone to keep track of lights and groups and all that. You do that by adding a LFXLightHandler (maybe not the best name) to the network loop. The light handler gets a message router (which it can use to send messages) and is handed incoming messages. It is now the light handler's responsibility to create and update lights and groups and keep them updated.

Today there is only one light handler, and that is LFXDefaultLightHandler in the impl.light package. It is here all the implementations of the lights and groups live.

But the thought when designing this, other than keeping a clean design, was that it should be possible to have different light handlers. You could for an example create a light handler that does not keep state by repeatedly polling but gets it asynchronously (e.g. Future<String> getLabel()) or a light handler that implements tags instead of groups.

LFXClient is just a thin wrapper around this. It creates a LFXDefaultLightHandler and adds it to the network loop. When opening the client it opens the network loop and when closing the client it closes the network loop. This is currently a bit silly. The plan was to implements a reference counter in the network loop so that you could create multiple instances of LFXClient and it was only when the last one was closed that the network loop closes.

But then you found that setReuseAddress() allows more than one listener on a socket. So now there is no reason for the network loop to be a singleton, leading to #22.

[iheart2code]

Awesome! Super helpful information. I think if there were some slightly more complex samples, or even a separate sample app, you could demonstrate this without having to do a lot of additions to the README.