xws4j binding tutorial

This is a very quick introduction to xws4j client stub generation. Skim read it to get an idea of how simple it is to create a binding for an XMPP IO Data service. I'm sure you'll have questions afterwards.

Create a client stub (XMPP IO Data service binding) for a certain XMPP service function with the batch binder tool:

java -classpath "..." net.bioclipse.xws.binding.BatchBinder <clientJID> <pwd> <host> <port> <serviceJID> <functionName> <targetDirectory> <compileSrc> <classpathStr>

Example:

<clientJID> user@myserver.example.net/bio
<pwd> secret
<host> myserver.example.net
<port> 5222
<serviceJID> database.server.example.com
<functionName> getProteinSequence
<targetDirectory> c:/my-binding-files/
<compileSrc> false
<classpathStr> jsr173_1.0_api.jar;resolver.jar;xbean.jar;xbean_xpath.jar;xmlbeans-qname.jar;xmlpublic.jar;xws4j-binding-test.jar;xws4j-current.jar;rt.jar

... will yield the following very long command on windows:

java -classpath "xws4j-current.jar;xws4j-binding-current.jar;jso-full.jar;ecj-3.4.1.jar;jsr173_1.0_api.jar;resolver.jar;xbean.jar;xbean_xpath.jar;xmlbeans-qname.jar;xmlpublic.jar;rt.jar" net.bioclipse.xws.binding.BatchBinder user@myserver.example.net/bio secret myserver.example.net 5222 database.server.example.com getProteinSequence c:/my-binding-files/ false "jsr173_1.0_api.jar;resolver.jar;xbean.jar;xbean_xpath.jar;xmlbeans-qname.jar;xmlpublic.jar;xws4j-binding-test.jar;xws4j-current.jar;rt.jar"

The BatchBinder will create a new folder in the specified target directory (c:/my-binding-files/). The created folder name depends on the service and function name it was created for; it also contains a "time stamp" in milliseconds because (to be pragmatic) the XML Schemata of a function sometimes change:

<targetDirectory>/<serviceJID>#<functionName>%<time-stamp>/

Example:

c:\my-binding-files\database.server.example.com#getProteinSequence%1225741713234\

The created folder contains a /src and a /bin folder. The /src folder contains all auto-generated Java source files. The /bin folder contains the .class files if <compileSrc> was true and a folder with the name /schemaorg_apache_xmlbeans that contains .xsb files.

In the Java project...

xws4j client stub generation depends on XMLBeans. Therefore beside the Java source code files (and packages) within the /src folder the /bin folder must be in the classpath because XMLBeans needs the .xsb files in "packaged" schemaorg_apache_xmlbeans.

Now the following code illustrates how the auto-generated XMPP service binding would be used:

// import the IoFactory from the auto-generated XMPP service binding
import com.example.server.database.getproteinsequence.IoFactory;


Client client = new Client(clientJID, pwd, host, port, epipe);

client.connect();

// to get the function ...
IFunction function = IoFactory.getFunction(client);

// to create an input object (depends on the binding that was auto-generated) ...
IoFactory iofact = new IoFactory();
ProtSeqDatabaseInput input = iofact.createProtSeqDatabaseInput();
input.setProteinsequenceid("AAV97816");

// invoke the function ...
Element result = function.invokeSync(input.toString(), // input as String
                                     90000); // timeout in milliseconds

// convert the result in a proper output object ...
XmlObject output = iofact.getOutputObject(result);
if (output instanceof ProtSeqDatabaseOutput) {
   // cast output to ProtSeqDatabaseOutput and extract the requested info ...
   String proteinseq = ((ProtSeqDatabaseOutput)output).getProteinsequence();
}