Client API improvements
Quoting @grote:
Last night I thought about the Client API as well and I tried to forget most of what I know about how things are implemented at the moment, so I can have a fresh view on how a developer writing a client without being familiar with Briar's internals would see things.
It is nice to being able to access the raw message, being able to put your own data structures in there. It is nice that you can encode and parse metadata. However, for many applications that might not be necessary and all the developer wants is a simple key value store. We have this already with the BdfDictionary which resembles JSON and which I like.
So I was wondering, why we don't add a layer on top of what we have and allow the client developer to directly get a BdfDictionary (which I will call Payload) from the message. The same way, when composing the message, just let the developer provide the payload and the lower layers handle the rest.
Here's some pseudo code to illustrate those thoughts:
class MyClient extends BrambleClient {
@Override
public void receivedMessage(Message m) {
Payload payload = m.getPayload(); // this is currently called BdfDictionary
String myString = payload.getString("myString");
long myInt = payload.getIntegeger("myInt");
Object myObject = payload.getSerializable("mySerializableObject");
doSomething(myString, myInt);
}
public void sendMessage() {
Payload payload = new Payload();
payload.putString("myString", "foo");
payload.putInteger("myString", "foo");
payload.putSerializable("mySerializableObject", myObject);
Message m = messageFactory.createMessage(payload);
// if that's not possible, it can be db.addLocalMessage(group, ...)
Group group = getGroup(contact);
group.sendMessage(m);
}
public void doSomething(String s, int i) {
// payload queries for easy access to messages
List<Messages> msgs1 = db.getMessagesWithPayloadKey(group, "myString");
List<Messages> msgs2 = db.getMessagesWherePayload(group, "myString", String, s);
}
}
Adding data to the payload is very similar to how intent extras or bundles work in the Android API, so many people are already familar with it.
Also note that there's no mention of validatingMessage() because the client developer is only interesting in receiving a message, so there could be just another hook for that.
If at all possible, I would like the client developer to write as little validation code as possible. Not having to check lengths and such things, but maybe only to see if the payload objects she expects are there.
I think that payload queries (however they will look like) would also be a very nice addition and convenience methods for client developers, so they don't have to iterate through message lists themselves just to find the ones they are interested in.