XINS - Frequently Asked Questions

General Questions

What is XINS?

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.

Why this definition-driven approach?

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.

Can the testing really start even right after some definitions are written?

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.

Which technologies does XINS rely on?

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.

What is XINS composed of, technically?

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.

Are there any tutorials on XINS?

Yes, there is the XINS Primer. If you want to learn more after following this 15-minute introduction, have a look at the user guide.

Is XINS stable?

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.

Are there any memory leaks in XINS?

No. There were memory leaks in older versions of XINS, especially in XINS 1.0.0, but extensive memory profiling and testing on XINS 1.3.0 and later has shown there are no memory leaks left.

Does XINS support transport protocols other than HTTP?

No.

How do I interact with a XINS API?

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.

Are there any public XINS APIs I can test with?

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.

What is a XINS project?

Basically just a set of XINS APIs.

What is a XINS API?

Basically a group of related functions, which are deployed together. An API may also define types and error codes.

What is a XINS function?

A single function that can be invoked remotely. There are meta-functions and defined functions. Meta-functions, such as _GetStatistics and _GetSettings come with XINS, while defined functions are defined specifically within a certain API.

What do I need in order to implement a XINS API in a programming language other than Java?

Basically, you just need to be able to accept HTTP requests (HEAD, GET and POST) and return appropriate XML. All should be in accordance with the rules for the XINS Standard Calling Convention, of course.

How can I improve performance?

The performance of XINS self is typically very good, especially since XINS 1.3.0. If you have a performance problem, then use the NetBeans profiler with the profile target. You will find it in the demo/nbbuild.xml file.
You can also change the logging level of Log4j to WARN. If you really believe XINS is a bottleneck in your situation, please send an e-mail to the xins-users mailing list with some details and, if possible, a reproducible testcase.

How can I debug the ACLs?

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'

Installation

How do I install XINS?

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.

Competitors

Does XINS have any competitors?

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:

What are the main differences between XINS and Apache Axis?

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.

What are the main differences between XINS and JWSDP?

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.

Open source and Licensing

Who is the owner of the XINS source code?

Online Breedband B.V., previously known as Orange Nederland Breedband B.V.

Is XINS open-source?

Yes. XINS is distributed under the terms of a customized BSD license.

Then can I get the source code for XINS?

Yes. You may either download a XINS distribution or get the source code from CVS.

Am I allowed to use XINS in my commercial application?

Yes, the license permits that redistribution and use in source and binary forms, with or without modification, are permitted provided that the conditions defined in the license are met.

What is the license for XINS, exactly?

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 may download it from this site: license as plain text file. It is also part of the distributions.

SOAP-support

What do I need to do to make SOAP calls to a XINS application?

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.

Can I use a browser to make SOAP calls to a XINS application?

No, normally not, unless you manage to write some JavaScript code that will perform a SOAP call. However, you are advised to use the normal test forms instead.

Why does XINS not use WSDL as the definition format?

WSDL assumes the use of various complex technologies that XINS does not require, such as XML Namespaces, XML Schema and UDDI. XINS started from scratch and introduces a very simple format which avoids complexity such as that found in WSDL.

Does XINS support UDDI?

No. XINS does not require a broker. Instead, XINS supports client-side load-balancing and fail-over.

XML-RPC support

What is the relation between XINS and XML-RPC?

XML-RPC is a protocol for client-server communication. XINS is a set of technologies for client-server communication. XML-RPC is one of the communication protocols supported by XINS.

How can I make an XML-RPC call to my XINS implementation?

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>

Deployment

Which version of XINS should I use for deployment?

The same one as the one you tested with. We advise XINS 3.1.

Which Java version should I use with XINS?

We advise using Java SE 1.4.2 or higher. Java 1.3 should work mostly, but we do not advise using it. Always make sure you have the latest revision of the JVM of your choice.

Does XINS require a full-blown Java Enterprise Edition environment?

No. XINS requires a Java SE SDK during development and additionally a servlet container for deployment.

What operating system should I use with XINS on?

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).

On which configurations did you test XINS 1.5.0?

See the XINS 1.5.0 release notes for details on which combinations of JVMs and platforms we used.

Which OS should I run XINS on?

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

Which functionality in XINS does not work on Java 1.3?

Without an appropriate library, HTTPS will not work. It may work with one, but this has not been tested.

How do I know whether my API started correctly?

By calling the _GetSettings function. This function will return an overview of build-time, system and runtime configuration settings and some other information, including a timestamp that indicates when the API was started.

Troubleshooting

I have not found the answer to my problem in this list, what should I do?

First make sure that the solution is not in the documentation, then you can mail the XINS user mailing list. If you think that your problem is a bug you can submit it in the Bug database.

I have a putDocumentInCache or 'project_node' is mandatory error message, what should I do?

You encountered a known Eclipse issue. Don't use the Ant version of Eclipse or download the xercesImpl-2.6.2.jar file to the eclipse\plugins\org.apache.ant_1.6.5\lib directory.