======================
Service definition XML
======================

This page explains the specifications of the service definition XML used to configure RaSC services.

The service definition XML is a setting file to specify configurations such as the command line of a user program, and the number of process instances for parallel execution. The following shows an example of a service definition XML that has a minimum of elements:

.. code-block:: xml

   <?xml version="1.0" encoding="UTF-8"?>
   <!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" "http://www.springframework.org/dtd/spring-beans.dtd">
   <beans>
     <bean id="target" class="jp.go.nict.langrid.servicecontainer.handler.TargetServiceFactory">
       <property name="service">
         <bean class="jp.go.nict.wisdom.wrapper.StdIOCommandService">
	   <property name="cmdLine" value="___PATH_TO_PROGRAM___" />
           <property name="delimiterIn" value="___INPUT_DELIMITER___" />
           <property name="delimiterOut" value="___OUTPUT_DELIMITER___" />
         </bean>
       </property>
     </bean>
   </beans>

In the service definition XML, the following two types of configurations are specified.

- User program execution mechanism
- Parameters involved in executing user programs

The following explains each of the above.


User program execution mechanism
================================

You can select a strategy of parallel or non-parallel execution by setting one of the following *Java class names* in ``/beans/bean/property[@name='service']/bean/@class`` (description with XPath):

- jp.go.nict.wisdom.wrapper.StdIOCommandService
- jp.go.nict.wisdom.wrapper.StdIOCommandArrayJoinService
- jp.go.nict.wisdom.wrapper.StdIOCommandParallelArrayService

The following explains each of the above items.


Standard non-parallel execution: StdIOCommandService
-----------------------------------------------------

For standard *non-parallel* execution, specify ``jp.go.nict.wisdom.wrapper.StdIOCommandService``.

This mechanism is intended for the most standard processing. It is recommended when you do not need parallelization. This mechanism:

- Gives the argument of ``String analyze(String)`` to a user program after adding the input delimiter
- When String[] analyzeArray(String[]) is called, adds the input delimiter to every element of the argument and gives all the elements to the user program 
- Does not parallelize execution


Standard parallel execution: StdIOCommandParallelArrayService
--------------------------------------------------------------

For standard *parallel* execution, specify ``jp.go.nict.wisdom.wrapper.StdIOCommandParallelArrayService``.

This mechanism is intended for standard parallel execution. When this mechanism is selected, the RaSC service:

- Divides the argument of ``String[] analyzeArray(String[])`` into smaller parts, and gives each part to each process instances of the user program.
- ``String[] analyzeArray(String[])`` is executed for the devided parts using each process instance.
- The number of processes for the user program is specified by ``poolSize``.


Processing on string joined from array elements: StdIOCommandArrayJoinService
------------------------------------------------------------------------------

For processing on string joined from array elements, specify ``jp.go.nict.wisdom.wrapper.StdIOCommandArrayJoinService``.

In the implementation of ``String[] analyzeArray(String[])``, instead of executing ``String analyze (String)`` for array elements, it combines the elements in the argument of ``analayzeArray`` into one character string and performs ``analyze`` once with the string.

You must configure parameters shown in :ref:`param_array_join`.


Parallel execution of analysis on each of array elements: StdIOCommandParallelService
--------------------------------------------------------------------------------------

For parallel processing on each of array elements, specify ``jp.go.nict.wisdom.wrapper.StdIOCommandParallelService``.

- This implementation distributes and gives each element of the argument of ``String[] analyze(String[])`` to each of multiple processes of the user program.
- ``String analyze(String)`` is executed using each process instance.
- The number of processes for the user program is specified by ``poolSize``.


Parameters
==========

Under ``/beans/bean/property[@name='service']/bean/``, you can specify parameters in the following format:

.. code-block:: xml

   <property name="___PARAM_NAME___" value="___PARAM_VALE___" />

Required parameters
-------------------

:cmdLine: Set a command to start a user program. If a directory name and/or filename includes a space character(s), use ``cmdArray`` instead. Note that specifying both will cause an error.
:cmdArray:  Set each element of the command line with the value tag under the ``list`` tag. Refer to :ref:`faq_whitespace_in_cmd` for details.
:delimiterIn: Delimiter characters for input. The linefeed code must be represented as ``\n`` (In default, ``\n`` will be replaced with the linefeed code in each environment. See also: ``useEnvLineSeparator``).
:delimiterOut: Delimiter characters for output. The linefeed code must be represented as ``\n`` (In default, ``\n`` will be replaced with the linefeed code in each environment. See also: ``useEnvLineSeparator``).

Optional parameters
-------------------

:includeDelim: Set whether delimiter characters are included in the result. When setting it to ``true``, output result includes the delimiter characters. 
:poolSize:  Set the number of process instances of a user program to be started. The parallel execution is to be performed with the number of processes specified here as the limit.
:initPoolSize: Specify the number of process instances of a user program that must be started immediately after a RaSC service is started. As default, new processes will be created according to ``poolSize`` as the limit when a request is received.
:pollTimeOut: The waiting time when the number of processes reaches *poolSize* and the processes are all busy. If no process becomes free after the time specified here (in units of ms) elapses, an error will be returned.
:timeOut: The timeout time for reading outputs from a user program. If any output is not available when the time specified here (in units of ms) elapses, an error will be returned and a user program will be restarted.
:startWait: The time from when a user program was started and to when a request for calling the program is accepted (in units of ms).
:restartWait: The time from when a user program was restarted due to any reason to when a request is accepted (in units of ms).
:bufSize: Buffer size for I/O (in bytes)
:directory: Set the working directory of the user program.
:environment: Set environment variables. See :ref:`faq_set_env_vars` for example. (Since ver. 1.0.2)
:useEnvLineSeparator: Set whether RaSC uses a new line code defined in the environment. The default value is ``true``． See also: ``useEnvLineSeparator`` (Since ver. 1.0.2)

.. :delLastNewline: Specify whether a linefeed code at the end of input is deleted. If a linefeed code is specified in delimiterIn, the linefeed will be automatically added before the request is given to the user program. For this reason, when the end of an input has the linefeed code in a user program that treats one line as one input, there will be two linefeed codes, which will cause an error. To prevent this event, set this parameter. The default is ``false``.

Execution mechanism dependent parameters
----------------------------------------

.. _param_array_join:

Parameters required for StdIOCommandArrayJoinService
+++++++++++++++++++++++++++++++++++++++++++++++++++++

:internalDelimiterIn: Delimiter to join each element of an input
:internalDelimiterOut: Delimiter to split an output
:includeInternalDelim: Setting whether a delimiter is included after split output using ``internalDelimiterOut``. The default value is ``false``.