Need to document correct async RPC usage

From Robert Varga:

The contract of the async RPC APIs returning Future objects does not allow for actual correct handling of asynchronous semantics. However, it turns out that internally it's actually using ListenableFuture with a thread pool that should allow for this to be done correctly, but this is not documented anywhere.

We need
(1) Document the correct usage of the API through javadoc and other documentation (Perhaps we can generate JavaDoc in the generated service API code that includes usage examples)
(2) Update all tutorials and examples to use the correct semantics.

https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob_plain;f=bgp/topology-provider/src/main/java/org/opendaylight/bgpcep/bgp/topology/provider/AbstractTopologyBuilder.java;hb=HEAD

note this listens to the datastore commits, just as we discussed:

DataModificationTransaction t = dataProvider.beginTransaction();
[...]
Futures.addCallback(JdkFutureAdapters.listenInPoolThread(t.commit()), new FutureCallback<RpcResult<TransactionStatus>>() {
@Override
public void onSuccess(final RpcResult<TransactionStatus> result)

{ LOG.trace("Change committed successfully"); }

@Override
public void onFailure(final Throwable t) {
LOG.error("Failed to initiate topology {} by listener {}", AbstractTopologyBuilder.this.topology, AbstractTopologyBuilder.this, t);
}
});

I think the current behavior is that the datastores an exception and RpcResult is unused (which kinda is where we want to go anyway). The topology provider is a singleton writer here, so a failure here is not recoverable.