Compiling and running the project

Now we have a simple project with a function that, for the moment, does nothing.

From the specification files XINS can generate :

The HTML specification documentation

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:

  • An overview with a description of the different functions, types and error codes used in your API.

  • A link for each environment to the meta functions _GetVersion, _GetStatistics and _GetSettings.

  • For each function, a description of the input parameters, output parameters, the validation rules and the possible result codes for this function.

  • For each function, a test form page to test the function.

  • For each example in the function, a description of the URL request, the expected result for this example and the links to execute the example on the given environments.

  • For each of the types, a description of the type. If the type is an enumeration, the possible values are written. If the type is a pattern then the regular expression for the pattern is written along with a link to test the provided pattern.

The web application.

Create the web application

The web application is packaged as a WAR file. When this WAR file is deployed on the servlet container, your functions are accessible through HTTP (for example using Internet Explorer).

To create the web application, execute xins war-myproject.

This command will create a myproject.war file in the directory build\webapps\myproject\.

This target also generates the skeleton file for the implementation, if the file did not exist. In our example the file will be apis\myproject\impl\com\mycompany\myproject\api\MyFunctionImpl.java.

You can set some compilation and running properties by creating a build.properties file in your project directory and set any of the following properties in the file:

Table 1. build.properties properties

Property nameDescriptionExample
build.compilerThe compiler to use to compile the classes. (Defaults to javac)build.compiler=jikes
build.deprecationWarn if deprecated methods are used. (Defaults to true)build.deprecation=false
build.java.versionThe version of Java where the code will be executed.build.java.version=1.3
org.xins.server.configThe location to the runtime properties file. Slash and backslash in the property value are translated with the system path separator in XINS. The location can also be a URL.org.xins.server.config=../xins.properties
servlet.portThe port number for the XINS servlet container (Defaults to 8080).servlet.port=8181
test.environmentThe environment upon which the tests should be executed (Defaults http://localhost:8080/).test.environment=http://integration.mycompany.com/myproject/
test.start.serverFlag to indicate that the API should be started when the tests are executed (Defaults to false).test.start.server=true
wsdl.endpointThe endpoint to use in the generated WSDL file (Defaults to the first entry of the environment.xml file)wsdl.endpoint=http://www.mycompany.com/myproject/
reload.stylesheetA work around property for Xerces library that produces sometimes putDocumentInCache errors.reload.stylesheet=true

These properties can also be passed to the system by using -D<property name>=<property value> on the command line.

Run the web application

To run the web application, execute xins run-myproject.

It is adviced to execute the web application with a specified runtime properties file. If no file is specified, only the local machine will have access to the API. For more information go to the runtime properties section.

You can also start the API using java [-Dorg.xins.server.config=<runtime property file>] -jar myproject.war [-port=<port number>] [-gui]. It is not needed to have XINS or Ant installed to run the API. The requester or the API or the testers for the API can receive the WAR file and execute it. The -gui option will start a user interface where the system output will be logged in a console.

To start the WAR file using the Jetty servlet container, create a file named myproject.xml int the projects directory with the following content :

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE Configure PUBLIC
 "-//Mort Bay Consulting//DTD Configure 1.2//EN"
 "http://jetty.mortbay.org/configure_1_2.dtd">

<Configure class="org.mortbay.jetty.Server">

  <Call name="addListener">
    <Arg>
      <New class="org.mortbay.http.SocketListener">
        <Set name="port">8080</Set>
      </New>
    </Arg>
  </Call>

  <Call name="addWebApplication">
    <Arg>/myproject/</Arg>
    <Arg>build/webapps/myproject/myproject.war</Arg>
  </Call>

</Configure>

Then start java -Dorg.xins.server.config=xins.properties -jar %JETTY_HOME%\start.jar myproject.xml in the projects directory.

Now execute your function by going to the address http://localhost:8080/myproject/?_function=MyFunction.

As nothing is implemented in your method, your function will just return a successful result.

If you want to get more information on your function or on XINS run the following meta functions :

Note

If you want to run the example in tomcat, you need to copy the demo\build\webapps\myproject\myproject.war to the tomcat\webapps directory and then start tomcat using the startup script. The URLs to access the functions will then start with http://localhost:8080/myproject/.

The server-side Javadoc

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.

The client API

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.

The client-side Javadoc

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

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.