To generate the HTML specification documentation (also called specdocs) execute xins specdocs-myproject.

This will generate a set of static HTML pages that you can view by opening the file build\specdocs\index.html.

The HTML pages contain:

To generate the Javadoc on the server-side execute xins javadoc-api-myproject.

This will generate a set of static HTML pages that you can view by opening the file build\javadoc-api\myproject\index.html.

To generate the jar file for the client API execute xins jar-myproject.

This will generate a jar file located at build\capis\myproject-capi.jar.

The following code shows how to use the generated CAPI to call a function. In this example, the myproject API is running on the same computer.

import org.xins.common.service.TargetDescriptor;

import com.mycompany.myproject.capi.CAPI;
import com.mycompany.myproject.capi.MyFunctionResult;

public class TestMyFunction {
   public final static void main(String[] args) throws Exception {

      // Create the descriptor for the service
      TargetDescriptor descriptor =
         new TargetDescriptor("http://localhost:8080/myproject/", 20000);

      // Create the CAPI instance
      CAPI project = new CAPI(descriptor);

      // Invoke the function
      MyFunctionResult result = project.callMyFunction();

      // No exceptions thown
      System.out.println("Call successful: " + result.getOutputMessage());
   }
}

It's also possible to invoke your API without using the generated CAPI file but by using the XINSServiceCaller. Examples on how to do it are provided in the XINSServiceCaller Javadoc.

The generated callMyFunction method can throw several kind of exceptions. For more information, refer to the generated CAPI Javadoc. Note that a subclass of the exception could be thrown. For example, if you want to catch the exception only when the function returns an error code, catch the org.xins.client.UnsuccessfulXINSCallException which is a subclass of the org.xins.client.XINSCallException.

You can also catch all the exception at once by catching the class org.xins.common.service.CallException.

      try {
         // Invoke the function
         project.callMyFunction();
      } catch (UnsuccessfulXINSCallException ex) {
         System.out.println("A standard error occured: " + ex.getErrorCode());
      } catch (CallException ex) {
         System.err.println("Execution failed: " + ex.getMessage());
      }

Most of the time your function will have input parameters to pass to the function. This can be done by passing the parameters to the callMyFunction method:

import com.mycompany.myproject.capi.CAPI;
import com.mycompany.myproject.types.Gender;
...
   MyFunctionResult result = project.callMyFunction(Gender.MALE, "Doe");

or to use the generated MyFunctionRequest object:

import com.mycompany.myproject.capi.CAPI;
import com.mycompany.myproject.types.Gender;
...
   MyFunctionRequest request = new MyFunctionRequest();
   request.setGender(Gender.MALE);
   request.setPersonLastName("Doe");
   MyFunctionResult result = project.callMyFunction(request);

In the second case, you don't need to call the set method for the optional parameters that are not set whereas in the first case you need to pass null values.

A new package org.xins.client.async has been added in XINS 1.4.0. This package provides you with some objects which facilitates the call to remote API asynchronously. For more information, read the article published at http://xins.sourceforge.net/asynchronous.html.

As of XINS 1.5.0, it is also possible to call the API without using the HTTP connection but directly as a function call. You just need to pass the location of the war file containing the API. As no connection is involved, the time-out represents the total time-out:

TargetDescriptor descriptor =
         new TargetDescriptor("file:///home/myuser/myproject.war", 20000);

It is possible to specify the HTTP method to use (POST or GET, default is POST), or whether redirection returned HTTP code should be followed (default is false by using the XINSCallConfig class.

To generate the Javadoc on the client-side execute xins javadoc-capi-myproject.

This will generate a set of static HTML pages that you can view by opening the file build\javadoc-capi\myproject\index.html.

The Open Document Format is a standard for word processors documents (similar to .doc). XINS contains a target that can generate the specifications of an API in this format.

To create the document, execute xins opendoc-myproject.

This will generate a build\opendoc\myproject\myproject-specs.odt file than can be opened with for example Open Office. Note that Open Office is free and can save your document as a MS Word document or as PDF.