How to invoke asynchronously

So the procedure is: bind the facet, call the method, carry on. But how does Jtrix achieve this? What do we need to do? And how do we get to find out about the return?

It is all achieved with the magic of the mediator. Until now we have always talked about the mediator as being a boundary between netlets (and between the node and its netlets) and making sure they don't interfere with each other. And we've spoken about the IRemote proxy object that a mediator returns when we bind a facet, which we then cast into the type we want before using it.

But that mediated proxy can do much more than that. It acts as our interface into the other netlet and can help us invoke its facet methods asynchronously, among other things. When we perform an asynchronous invocation we supply a callback object which will get called whenever method returns.

Here's a code snippet. First it reminds us how to use a facet normally, then it shows us how to use it asynchronously. At this stage, it's very high level:

    // How to use a facet normally: (1) bind it, (2) cast it into the right type.
    // This should be very familiar to us.

    IRemote proxy = node.bindFacet(IHelloFacet.class.getName());
    IHelloFacet normal_version = (IHelloFacet)proxy;

    // But we can take that same facet and make it usable asynchronously...

    IAsynchronous.IClient async_version = (IAsynchronous.IClient)proxy;

    // Now we can use invoke its methods asynchronously.  Variable "method"
    // is the method we want to invoke. It's of class java.lang.reflect.Method.
    // Variable "params" is an Object array. It contains the parameters we want
    // to pass to the method. Variable "handler" is the callback object which
    // will get called when the method is invoked.

    async_version.invoke(method, params, handler);

    // And we carry on. Hopefully the handler object will get called eventually.

The first interesting thing is the cast into a IAsynchronous.IClient. It seems that the proxy object has a few hidden talents, and can be cast into more than just a normal facet interface. The IAsynchronous interface can be found in org.jtrix.base, and we're using its inner class/interface for clients.

The invoke() method of IAsynchronous.IClient simply lets us invoke the desired method in an asynchronous manner. If you've used java.lang.reflect before then you should be familiar with the broad principles of this. We say what method we're invoking along with its parameters.

The callback object will handle the method's return, when it happens. The node will start this in a new thread, or reuse one if appropriate.

Next, we present a complete netlet example which shows all the details in practice.