XINS - Frequently Asked Questions

A technology for specification and implementation of internet applications, which enforces a definition-driven approach:

• first definitions need to written
• then documentation and code is automatically generated from these definitions
• then the testing and implementation can start.

To stimulate that thinking happens before the coding and to enable rapid application development.

From the definitions, numerous things can be automatically generated, including:

• HTML and ODF documentation
• test forms
• WSDL
• a basic web application
• test code, for automated unit- or integration-testing
• stubs, for automated unit testing
• client-side code
• etc.

Yes, some testing can indeed start after some initial definitions are written.

This requires that XINS is instructed to generate code, build a package and run the application from within an internal server. All of this can be done with a single command (xins run-apiname).

With this -basically empty- implementation of the API you can confirm that all functions are in place, and test the input error conditions. These conditions include missing parameters and type violations.

On the following:

• XML: For all definitions and for the default output from a XINS API.
• XSLT: Underlying the code generation technologies. Also, XSLT-support is available at runtime for converting the result XML to text, HTML or other forms.
• Java: All generated code is in the Java programming language.
• Apache Ant: XINS uses Ant internally for building XINS self. Additionally, XINS generates Ant build files at runtime so it can delegate most of the build process to Ant.

Of the following:

• An XML-based definition format for projects, APIs, functions, types and error codes (example).
• A POX-style RPC protocol (called the XINS Standard Calling Convention), compatible with web browsers (HTTP parameters in, XML out).
• A tool for generating human-readable documentation, from the definitions (example).
• A tool for generating WSDL, from the definitions (example).
• A Log4J-based technology for logging (called Logdoc), offering a definition format, internationalization of log messages, generation of HTML documentation and generation of code (example of generated HTML documentation).
• A Java client-side library for calliing XINS functions: the XINS/Java Client Framework; in xins-client.jar.
• A server-side container for Java-based XINS API implementations: XINS/Java Server Framework; in xins-server.jar. This is like a servlet container for XINS APIs. It supports not only POX-style calls, but also SOAP and XML-RPC. And it supports conversion using XSLT.
• A Java library with some common functionality, used by both the XINS/Java Client Framework and the XINS/Java Server Framework: the XINS/Java Common Library, in xins-common.jar.

Yes. XINS is actively used in a variety of production systems with no problems whatsoever. Most deployments are running XINS 1.3.0 on multi-processor Sun Solaris/SPARC systems, with the Sun JVM 1.4.2_10 HotSpot Server VM. Some of these have an uptime of several months, and handle more than 350,000 calls a day.

XINS 3.1 is considered the most stable release so far.

For manual testing, you can use the HTML test forms XINS generates from the definitions. These can be used with any browser.

If your program is written in Java, you can generated a client-side JAR file or you can use the underlying XINSServiceCaller class directly. Support for load-balancing, fail-over and time-out handling is included.

If you use a different programming language: just call the correct URL with appropriate parameters and parse the returned XML.

Yes, a test API is available at netarray.com. It's running on the Sun JVM 1.5.0_06 on Linux 2.4/x86. This API offers one defined function, called MyFunction, along with all the standard meta-functions.

To invoke the MyFunction function, use the on-line testform for testing this function with your browser.

To invoke the _GetSettings meta-function, for example, call http://xins.users.mcs2.netarray.com/myproject/xins/?_function=_GetSettings.

Rejection of requests due to the configured ACLs is logged at the INFO level. Make sure you either log all messages at the INFO level, or alteratively at least for messages 3551 and 3553.

If you also want to see why requests are accepted, also enable log messages 3550 and 3552, which are at the DEBUG level.

For details, see documentation on the log entry group 'Access rule matching'

By following these steps:

1. Install a Java SDK, preferably version 1.4.2 or later.
2. Install Apache Ant, preferably version 1.6.5.
3. Install XINS, preferably version 3.1.

See the Installation Guide for more detailed instructions.

In theory, no. Although there are numerous other technologies related to web services and RPC, none of them is a complete framework like XINS, providing an integrated approach to the various aspects of software development. And XINS is unique in it's definition-driven approach.

In practice, the following technologies are considered as alternatives to XINS:

• Apache Axis
• Sun JWSDP

Axis is a technology from the Apache Software Foundation for exposing Java code as SOAP services. XINS is a generic Java-based framework for RPC-oriented communication, which supports various protocols, including POX-RPC, XML-RPC and SOAP.

For more information on Axis, see the Apache Axis Wikipedia page or the Apache Axis homepage.

JWSDP is a technology from Sun MicroSystems which combines various technologies related to Web services development in a single toolkit. While XINS is focused on an integrated definition-driven development approach, providing a selected subset of what JWSDP includes.

For more information on JWSDP, see the JWSDP Wikipedia page or the JWSDP homepage.

As follows:

Copyright 2003-2008, Online Breedband B.V.
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its contributors
may be used to endorse or promote products derived from this software
without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

You need XINS 1.3 at least, but you are advised to use XINS 2.0:

• First of all, make a SOAP request. XINS can generate the WSDL for this request, using the command xins wsdl-api (where api is the name of your API).
• Secondly, with XINS 1.3, you need to add _convention=_xins-soap to the URL. This is not needed with XINS 1.4+, since XINS 1.4+ will automatically detect the SOAP request.

With the current stable version of XINS, 3.1, just send your XML-RPC request using HTTP POST.

For example:

POST /RPC2?_convention=_xins-xmlrpc HTTP/1.0
User-agent: Frontier/5.1.2 (WinNT)
Host: betty.userland.com
Content-type: text/xml
Content-length: 171


<?xml version="1.0"?>
<methodCall>
   <methodName>GetStateName</methodName>
   <params>
      <param>
         <value><i4>41</i4></value>
         </param>
      </params>
   </methodCall>

In theory, any operating system that supports Java Standard Edition, version 1.4 or higher should work with no problems.

In practise, XINS has been tested successfully on the following operating systems:

• Solaris
• Linux
• Windows

We advise using either Solaris 8 (or higher), Linux 2.6 or Windows 2000 (or higher).

In theory, any OS that runs Java 1.4, 1.5 or 1.6. In practice, some are 'more equal than others'; recommended is one of the following:

• Solaris 8, 9 or 10
• Linux 2.6/x86
• Mac OS X 10.4.x
• Windows 2000 or XP