.. xws4j
welcome
license (LGPL)


.. SourceForge
project page
download
mailing lists

SourceForge.net Logo Bioclipse.net Logo


.. docu
javadoc
dependencies


.. tutorial
server - 3 minutes
client - 1 minute
binding tutorial

one minute client tutorial



This is a very quick introduction to xws4j. Skim read it to get an idea of how simple it is to invoke a function of a XMPP IO Data service. I'm sure you'll have questions afterwards.


IExecutionPipe
The client side of xws4j is an XMPP client. A Jabber ID (XMPP client account) is required to create the client. Beside this an "execution pipe" is passed to optionally "inject" listener code from the socket thread into the correct GUI thread. If the meaning of an execution pipe is not patent yet you may directly progress to the next chapter.

Example 1: there is no GUI thread, use the socket thread.
IExecutionPipe epipe = new IExecutionPipe() {
   public void exec(Runnable r) {
      r.run(); // listener code will run in socket thread
   }
};

Example 2: xws4j is used in an Eclipse Plug-In, listener code is injected in Eclipse's GUI thread.
IExecutionPipe epipe = new IExecutionPipe() {
   public void exec(Runnable r) {
      Display.getDefault().asyncExec(r); // for Eclipse Plug-Ins; listener code will run in Eclipse's GUI thread 
   }
};

Client
Creating the client requires a JID, resource, password, server name, port, and the execution pipe. Optionally it is possible to define a connection listener that is informed on connect/disconnect events.

Example: a client is created and connected for the JID user@myserver.example.net and the resource bio
Client client = new Client("user@myserver.example.net/bio", // JID + resource
                           "secret",                        // password
                           "myserver.example.net",          // server name
                           "5222",                          // server port
                           epipe);                          // execution pipe

client.addConnectionListener(listener); // optional
client.connect();

IFunction
To create and invoke a function the created client must be used. Input and output of the function is org.w3c.dom.Element.

Example 1: create and invoke a function and wait for the result (block)
IFunction function = client.getFunction("database.server.example.com", // IO Data service component that hosts the function
                                        "getProteinSequence");         // function name

Element output = function.invokeSync(input,  // the input Element
                                     90000); // timeout in milliseconds

Invoking functions without blocking but with listeners is supported, too.

Example 2: handle the results of function invocation in a user defined listener
ISimpleProcessListener listener = new ISimpleProcessListener() {
   public void onIqError(Process p, XmppException error) {
      // handle IQ error ...
   }
   public void onError(Process p, XwsException error) {
      // handle process error ...
   }
   public void onResult(Process p, Element output) {
      // handle result ...
   }
};

function.invokeAsync(input,     // the input Element
                     listener); // the listener that gets informed about errors and result