====================================
Run a user program as a RaSC service
====================================

This topic describes how to run a user program as a RaSC service for reducing startup overhead and parallelization.

The programs you can run on RaSC must meet the conditions described in :ref:`rasc_ready_program`. This topic takes the `syntactic parser Enju <http://kmcs.nii.ac.jp/enju/>`_ as an example which meets such conditions.

Configure a RaSC service
========================

First, download and unzip the RaSC *core* package. [#f1]_

.. code-block:: bash

   $ curl -O -J "%DL_FILE_URL|rasc-core-%RASC_VERSION%,zip%"
   $ unzip rasc-core-%RASC_VERSION%.zip

The package contains the following files. ::

   rasc-core-%RASC_VERSION%/
   + /lib
      + ... (Required libraries)
   + logging.properties (Log settings)
   + /WEB-INF
     + /serviceimpl
       + SampleService.xml (Service definition XML example)
   + SampleClient.java (Client program example)
   + server.sh (Start script)

The file name (the part without the file extension) of the service definition XML under ``WEB-INF/serviceimpl`` must be the service name. This example changes the service name on the assumption that we will use Enju with RaSC.

.. code-block:: bash

   $ mv WEB-INF/serviceimpl/SampleService.xml WEB-INF/serviceimpl/EnjuService.xml

Open ``WEB-INF/serviceimpl/EnjuService.xml`` , and set the command line of the user program you want to run to the part of ``___PATH_TO_PROGRAM___``.

.. code-block:: xml
   :emphasize-lines: 8

   <?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="\n" />
           <property name="delimiterOut" value="\n\n" />
         </bean>
       </property>
     </bean>
   </beans>

RaSC executes the user program using the command line specified in the  *cmdLine* property. The *delimiterIn* property indicates that a linefeed code is the delimiter for one unit of input. The *delimiterOut* property indicates that two linefeed codes are delimiters (for information on detailed specification, refer to :doc:`service_xml`)

RaSC appends the character string specified as *delimiterIn* to a request received from the client, and write it to standard input of the user program. Then RaSC discovers the character string specified as *delimiterOut* property among the output from standard output. Finally RaSC returns the part of the output before *delimiterOut* as the output for one request.

For example, if the character string ``He runs the company.`` (without any linefeed code) is sent from the client, RaSC appends a linefeed code to the character string before writing it to standard input of Enju. As Enju appends the characters ``\n\n`` at the end of one analysis result, RaSC can recognize a unit of output. For any other user programs, you must set *delimiterIn* and *delimiterOut* according to the specification of the program.

Start a RaSC service
=====================

To start a RaSC service, run the following command under the path with which you unzip the package. The first argument is the service name and the second is the port number.

.. code-block:: bash

   $ sh ./server.sh EnjuService 19999 start

Note that you can stop the service with the following command:

.. code-block:: bash

   $ sh ./server.sh EnjuService 19999 stop

Now you can call the user program through a fast and efficient network protocol, `MessagePack RPC <https://github.com/msgpack-rpc/msgpack-rpc>`_.


Call a RaSC service
===================

The package contains the following Java client to call an RaSC service (``SampleClient.java``).

.. code-block:: java
   :emphasize-lines: 13-15

   import java.io.BufferedReader;
   import java.io.FileInputStream;
   import java.io.InputStreamReader;
   import java.net.InetSocketAddress;
  
   import jp.go.nict.langrid.client.msgpackrpc.MsgPackClientFactory;
   import jp.go.nict.wisdom.wrapper.TextAnalysisService;
  
   public class SampleClient {
     public static void main(String[] args) throws Exception {
       MsgPackClientFactory factory = new MsgPackClientFactory();
    
       TextAnalysisService client = factory.create(TextAnalysisService.class,
                 new InetSocketAddress(args[0], Integer.parseInt(args[1])));
       String ret = client.analyze(args[2]);
 
       System.out.println(ret);
       factory.close();
     }
   }

You can compile and run the client program as follows. 

.. code-block:: bash

   $ javac -classpath ./lib/*: SampleClient.java
   $ java -cp ./lib/*: SampleClient localhost 19800 'He runs the company.'
   ROOT    ROOT    ROOT    ROOT    -1      ROOT    ROOT    runs    run     VBZ     VB      1
   runs    run     VBZ     VB      1       verb_arg12      ARG1    He      he      PRP     PRP     0
   runs    run     VBZ     VB      1       verb_arg12      ARG2    company company NN      NN      3
   the     the     DT      DT      2       det_arg1        ARG1    company company NN      NN      3

Specify the host on which the service is running for the first argument, and specify the port for the second argument. The string in the third argument is given to the standard input of the user program after *delimiterIn* is attached. Then, ``analyze()`` returns the output from the standard output of the user program as its result.


See also
========

- :doc:`rasc_parallel_local`
- :doc:`rasc_msgpack_various_lang`
- :doc:`service_xml`

FAQ
===

- :ref:`faq_whitespace_in_cmd`


.. [#f1] This package is generated from the project pkg_core registered in GitHub.