XINS User Guide

Anthony Goubard


Table of Contents

Introduction
What is XINS?
Notation
Requirements
Installation
Code conventions
Setting up a new project
xins-project.xml
api.xml
MyFunction.fnc
Compiling and running the project
The HTML specification documentation
The web application.
The server-side Javadoc
The client API
The client-side Javadoc
The Open Document Format
Implementing the method
Defining Input, Output.
Defining the test environments.
Defining the examples.
Implementing your function.
Executing your function
The error code
The runtime properties
The properties
Getting properties value
Defining properties
The bootstrap properties
Integration with CVS
Managing dependencies
Adding other files to the WAR file
Multiple implementations and stubs
Testing
Categories
Managing logs
Managing the logs on the server side.
Adding your own logs.
Configuring the properties files for specific logs
Managing load balancing and fail over
XINS types
Predefined types.
Defined types
Shared types
Grouping types
Param combos
Attribute combos
Combos based on values
The data section.
The specification
The implementation
The result
Data section for the input
Data section on the client side
Function accesses
ACLs
Enable/Disable a function
HTTPS
The meta functions
Management
JMX
Versioning
Shared instance
Calling Convention
How to define the calling convention
Standard calling convention
XSLT calling convention
SOAP calling convention
XML calling convention
XML-RPC calling convention
JSON-RPC calling convention
JSON calling convention
SOAP-MAP calling convention
Custom calling convention
Examples calling convention
Utility classes
Ant tasks
callxins task
xins task
XINS targets
XINS tools
Content of the XINS package
Documentation
Examples
Program
Integration with IDE
Integration with Eclipse.
Integration with NetBeans
Integration with other frameworks
Spring framework
Dojo toolkit
Google Web Toolkit (GWT)
AJAX
Mule
ESB and JavaEE
Ant
Maven
Script languages (Groovy, Ruby, PHP, Perl...)

Introduction

This document explains the XINS functionalities. It starts by explaining how to create and run a simple API and continue by explaining the more advanced features.

What is XINS?

XINS is an open-source Web Services framework.

XINS supports POX-RPC, SOAP, XML-RPC and more. It consists mainly of an XML-based specification format and a Java-based implementation framework. From its specifications, XINS can generate HTML, WSDL, client-side code, server-side code, test forms and more.

Notation

This document uses the Windows file system. If you are installing XINS in a Unix operating system like Mac OS X, linux or Solaris, change all back slash characters ('\') with a forward slash character ('/') in the file names of this document.

The documentation provides some Javadoc links that only work in the HTML generated user guide.

Requirements

XINS requires the following software:

  • Java Development Kit 1.4 or higher: http://java.sun.com/javase/downloads/.

    If not done by the installation, you should set the environment variable JAVA_HOME to the directory where you have installed Java. Also add the %JAVA_HOME%\bin directory to the PATH environment variable. You can check the Java version installed by executing java -version.

    XINS is also compatible with Java 1.3.1. If you want to compile your API using Java 1.3.1, proceed as follow:

    • Download Xalan.

    • Copy xalan.jar, xercesImpl.jar and xml-apis.jar to %XINS_HOME%\lib.

    • Add -lib %XINS_HOME%\lib as argument to the ant commands located in the bin\xins.bat file.

    • If you would like to use the HTTPS functionality, then you require also a JSSE implementation.

    XINS has also been tested with Java 5.0 and Java 6.0 .

  • Ant: http://ant.apache.org/, version 1.6.2 or higher.

    You should set the environment variable ANT_HOME to the directory where you have installed Ant. Also add the %ANT_HOME%\bin directory to the PATH environment variable. You can check the Ant version installed by executing ant -version.

    Caution

    If you're using the Ant distribution included with Eclipse, you may need to copy xercesImpl-2.6.2.jar in the eclipse\plugins\org.apache.ant_1.6.5\lib directory. Otherwise you may have an putDocumentInCache error message.

    If you're using the Ant distribution included with NetBeans and have putDocumentInCache error messages, you should change the Ant home location to Ant 1.7.0 or higher (in Tools -> Options -> Miscalleneous -> Ant.

  • Optional: A servlet container. For example: Tomcat or Jetty. Any J2EE server can also deploy web applications. For example: Glassfish, Orion, JBoss, WebSphere, WebLogic, Resin or JRun.

    For the installation of the servlet container, please refer to the documentation of the downloaded product.

    XINS contains it's own servlet container implementation for basic testing purposes only.

  • Optional: A version control system. For example CVS or Subversion.

This document will assume that you have installed Java, Ant.

Installation

XINS can be installed using the Windows installer or by downloading the .tgz file and unzipping the file. Both options are explained below.

Windows Installer

  • Download xins-2.2.exe and execute it. A new directory c:\Program Files\xins is created.

  • If you choose to compile and run the demo, you can go to the link provided in the README file, then click on MyFunction and on the MyComputer links in the examples section or use the test form link provided on this page.

Using the .tgz file

  • Download XINS 2.2.

  • Unpack the downloaded file ( xins-2.2.tgz) to a directory.

  • Set the environment variable XINS_HOME to the xins directory.

  • Add the path %XINS_HOME%\bin to your PATH environment variable

Note

On Windows, the new environment variable will not be set until you have rebooted or logged on again. If you don't want to reboot your computer, you can set the variables with set XINS_HOME=c:\Program Files\xins and set PATH=%PATH%;%XINS_HOME%\bin in a DOS prompt.

You are now ready to create your first XINS project.

Code conventions

API names should be in lowercase. E.g. billing (and not Billing).

Functions, types and result codes should use the hungarian naming convention and start with an uppercase. E.g CheckStatus, Customer and NotFound.

Parameters, functions, types and result codes starting with an underscore ('_') are reserved for XINS.

Parameter names should start with a lowercase. E.g: message and houseNumber.

The Java code used for the generated templates and in the examples has private variables starting with underscore ('_') and contains some comment for the CVS tags. For the rest the Sun Java code conventions and the Javadoc documentation style rules apply.