An error code (previously named result code) contains the description of an error that occurred when executing the implementation code.

When you generate the specification documentation, you can already notice that some error codes already exist by default. These error codes are returned by the system when the problem occurs.

You should create custom error codes whenever the implementation of your function would encounter an error condition that should be distinguishable for the caller. For example, if you connect to another service, if you perform I/O operations or if the input fields should match fields in a database.

We will now extend our example with a NoVowel error code. Note that this error could be also detected by improving the lastName pattern.

Create a error code by executing xins create-rcd.

The command will ask you for the name of your api and the name and the description of your error code. The script will then create a new NoVowel.rcd file in the directory <specsdir>/<api name> with the content :

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE resultcode PUBLIC "-//XINS//DTD Result Code 3.0//EN"
          "http://www.xins.org/dtd/resultcode_3_0.dtd">

<resultcode name="NoVowel"
            rcsversion="$Revision: 1.102 $" rcsdate="$Date: 2013/01/02 17:28:58 $">

  <description>The name does not contain any vowels.</description>

</resultcode>

Once this file is created, add the line <resultcode name="NoVowel" /> in the api.xml file. A reference to this error code also needs to be defined in the function that may return this error code. In our case MyFunction.fnc. Also add the line <resultcode-ref name="NoVowel" /> at the beginning of the output section of MyFunction.fnc.

Now we need to adapt our Java code to detect if the given last name does not include any vowels and return the error code when it is the case. Add the following code at the beginning of your call() method.

String lastNameLower = request.getPersonLastName().toLowerCase();
if (lastNameLower.indexOf('a') == -1 && lastNameLower.indexOf('e') == -1 &&
    lastNameLower.indexOf('i') == -1 && lastNameLower.indexOf('o') == -1 &&
    lastNameLower.indexOf('u') == -1 && lastNameLower.indexOf('y') == -1) {
      return new NoVowelResult();
}

Now we need to adapt the specification of your function to include this result code in the examples. We moved the example 3 to example 4 as we wanted to keep the order "unsuccessful results" "successful results" in our examples and we added the example 3 with

<example resultcode="NoVowel">
  <description>The name does not contain any vowels.</description>
  <input-example name="gender">f</input-example>
  <input-example name="personLastName">qslkfj</input-example>
</example>

You can now regenerate everything with xins all-myproject and after restarting the servlet container server, test the new example using the generated specification documentation.

It is possible to have parameters and a data section in the error code. To do it, add an output element to the error code. For the examples in the specification and setting the values in the implementation, just do it as you would do for a function with output parameters or data section. The allinone example contains a AlreadySet error code with one parameter.

Since XINS 1.4.0, it is possible to specify if an error code is functional or technical. Functional error code are error that may occur such as InvalidPassword where as technical errors indicate a problem such as DatabaseCorrupted. By default an error code is technical. To specify the error code as functional add the attribute type="functional" to the resultcode element.

If you want to reuse an error code already defined in another API, you don't need to copy the file. You can also point to the error code of the API. Its uses the same system as in the section called “Shared types”.