Let's add to our project three input fields and a result with one output field.

When you are adding input and output parameters to your function, you should at the same time declare the type of your parameter. There are two kinds of types, the ones already defined in XINS and the ones you create. The types already defined in XINS are explained in the next chapter.

To create a new type for your project execute xins create-type.

The command will ask you for the name of the API, the name of the type and the description of the type. It will then create a new <type name>.typ file with the content :

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE type PUBLIC "-//XINS//DTD Type 2.2//EN"
"http://www.xins.org/dtd/type_2_2.dtd">

<type name="TypeName"
rcsversion="$Revision$" rcsdate="$Date$">

  <description>Description of the type.</description>

</type>

The different possibilities of types that could be defined are listed in the section called “Defined types”.

Let's create two types for our project, one with the type lastName and one with the type gender.

Edit the LastName.typ file with

  <description>Last name of a person.</description>
  <pattern>[A-Za-z ]{1,50}</pattern>

Edit the Gender.typ with

  <description>A gender.</description>
  <enum>
    <item name="male"   value="m" />
    <item name="female" value="f" />
  </enum>

If the name attribute is not specified it will be the same as the value attribute.

Now that the types are created, we need to add the declaration in api.xml and to set them as input parameters in our function. For the output we will use a predefined type so there is no need to define the type in api.xml.

Add <type name="Gender"/> and <type name="LastName"/> to api.xml.

Add to the file MyFunction.fnc :

<input>
  <param name="gender" required="true" type="Gender">
    <description>The gender of the person.</description>
  </param>
  <param name="personLastName" required="true" type="LastName">
    <description>The last name of the person.</description>
  </param>
</input>
<output>
  <param name="message" required="true" type="_text">
    <description>The message returned to this person.</description>
  </param>
</output>

You can also assign a default value for an optional parameter using the default attribute.

  <param name="gender" required="false" type="Gender" default="m">
    <description>The gender of the person.</description>
  </param>

You can specify in XINS the environments where you want to test the API.

As seen in the section called “api.xml”, it's possible create the file containing the test environments by using the xins create-api or by creating the file with a text editor and editing the xins-project.xml.

When you generate the specification documentation, for each function defined in the API a link below "Test forms" that points you to a HTML form which is used to fill the input parameters of the function. When you then click on Submit the function will be executed on the specified environment. This requires of course that the application is installed on the defined environment.

The environments are also listed on the main page of the specification documentation along with some links that provide direct access to some meta functions.

If you want to add a new environment, just add for example <environment id="production" url="http://www.mycompany.com:8080/my-project/" /> to environments.xml.

You can also define some examples for your API in the specification. The definition of the examples are done in the function specification file.

Let's add some examples to MyFunction.fnc by adding the following text after the output section:

<example resultcode="_InvalidRequest">
  <description>Missing parameter : lastName</description>
  <input-example name="gender">m</input-example>
</example>
<example resultcode="_InvalidRequest">
  <description>Invalid parameter</description>
  <input-example name="gender">m</input-example>
  <input-example name="personLastName">Bond 007</input-example>
</example>
<example>
  <description>Message returned.</description>
  <input-example name="gender">f</input-example>
  <input-example name="personLastName">Lee</input-example>
  <output-example name="message">Hello Miss Lee</output-example>
</example>

This example shows how to add some examples to a function with input and output parameters but it's also possible to define examples for a function that contains a data section or returns a result code that contains some parameters. For more information, look at the function specification defined in the allinone project.

The examples are shown on the generated specification documentation and if you have also defined some environments, you can execute the example by just clicking the provided links.

In XINS 1.4.0, you can create an example using xins create-example. The API should be running on http://localhost:8080/<api name>/. The create-example target will ask you for the name of the API and the request URL. The example is automatically added to the function.

You can edit the new MyFunctionImpl.java generated file located in the apis\myproject\impl\com\mycompany\myproject\api directory with

   public final Result call(Request request) throws Throwable {

      String nomination = null;
      if (request.getGender().equals(com.mycompany.myproject.types.Gender.MALE)) {
         nomination = "Mister";
      } else {
         nomination = "Miss";
      }
      SuccessfulResult result = new SuccessfulResult();
      result.setMessage("Hello " + nomination + " " +request.getPersonLastName());
      return result;
   }

We first need to rebuild the WAR file, the spec docs, the client jar and the javadoc by executing xins all-myproject.

Now you must restart the servlet container server and reopen the file build\specdocs\index.html. You can test your function by either clicking on the link provided with the examples or by using the test forms.