Work with various network protocols

This topic describes how to call RaSC services through various network protocols: MessagePack RPC, JSON RPC, ProtocolBuffers, and SOAP. Users can choose the most appropriate protocol according to applications.

• MessagePack RPC and ProtocolBuffers: highly efficient binary protocols to be used when performance matters
• JSON RPC: uses a text representation understandable to humans. In addition to support by many programming languages, it is easy to use from command line tools, such as curl, etc.
• SOAP: XML-based protocol. Many frameworks provide a strict verification on interoperability for SOAP. It is easy to work with various service-oriented systems.

The programs you want to run on RaSC must meet the conditions described in Programs that can run with RaSC. This topic takes the syntactic parser Enju as an example which meets such conditions.

Configure a RaSC service

First, download and unzip the RaSC basic package. [1]

$ curl -O -J "http://alaginrc.nict.go.jp/rasc/cgi-bin/dl.cgi?name=rasc-basic-1.0.2&type=zip"
$ unzip rasc-basic-1.0.2.zip

The package contains the following files.

rasc-basic-1.0.2/
 + build.xml
 + jp.go.nict.wisdom.wrapper/
 + lib/
   + ... (Required libraries)
 + script/
 + webapps/
   + WEB-INF
     + services/
       + SampleService.xml (An example of service definition XML)

The RaSC service to be created in this tutorial will be packaged as a war file, that is an archive file of a Web application, and work on Java Servlet containers such as jetty.

The file name (the part without the file extension) of the service definition XML under WEB-INF/services/ must be the service name. This example will change the service name on the assumption that Enju will be provided as a RaSC service.

$ cd rasc-basic-1.0.2
$ mv webapps/WEB-INF/services/SampleService.xml webapps/WEB-INF/services/EnjuService.xml

The following three files must be edited to configure the RaSC service.

• webapps/WEB-INF/services/EnjuService.xml
• build.xml
• script/settings.json

First, open webapps/WEB-INF/serviceimpl/EnjuService.xml and set the command line of the user program you want to run to __PATH_TO_PROGRAM__ as follows.

<?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>

Next, edit build.xml to create a war file. Set __WAR_NAME__ to the war file name. In this example, we set jp.go.nict.rasc.enjuservice. This name can be different with the name of the service definition XML.

<target name="war" depends="wrapper">
  <property name="war_name" value="___WAR_NAME___"/>

  <war destfile="build/${war_name}.war" webxml="webapps/WEB-INF/web.xml">
    <webinf dir="webapps/WEB-INF" includes="**/*.*" excludes="**/web.xml" />
    <lib dir="lib" includes="**/*.jar" />
    <lib dir="build" includes="wrapper.jar" />
  </war>
</target>

Finally, edit script/settings.json. Use the name previously set for __WAR_NAME__ and service definition XML as ___SERVICE_NAME__.

{
     "serverName" : "RaSCServer",
     "jettyPort" : 8080,
     "controlPort" : 0,
     "httpServices" : [
                    { "contextPath":"/___WAR_NAME___",
                      "serviceName":"___SERVICE_NAME___",
                      "warPath":"../build/___WAR_NAME___.war" }
                ]
     "msgpackServices" : [
                    { "contextPath":"/___WAR_NAME___",
                      "serviceName":"___SERVICE_NAME___",
                      "warPath":"../build/___WAR_NAME___.war",
                      "msgpackPort":9090 }
                  ]
}

The default settings assigns port 9090 to MessagePack RPC, and port 8080 to protocols on HTTP such as JSON RPC, ProtocolBuffers, and SOAP.

Start a RaSC service

Run the following commands under the path with which the package was unzipped. The commands create a war file and start the RaSC service. This service can be called from any protocol of MessagePack RPC, JSON RPC, ProtocolBuffers, and SOAP.

$ ant
$ cd script
$ sh ./basic_server.sh start

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

$ sh ./basic_server.sh stop

Call a RaSC service

The following example introduces one of the methods for calling the service with JSON RPC. The benefits of using JSON RPC are simplicity and understandability. For example, you can run the service with JSON RPC, using the curl command as follows. It passes the method name and parameter as GET parameters.

$  curl "http://localhost:8080/jp.go.nict.rasc.enjuservice/jsonServices/EnjuService?method=analyze&params=\[\"He%20runs%20the%20company.\"\]"

For JSON RPC, a simple GUI is provided to test the service from a Web browser. Open the following URL with the browser to display the interface, with which you can call the service. Change ___WAR_NAME___ in the following URL as previously set on.

http://localhost:8080/___WAR_NAME___/jsonServices/

The following shows a screen shot of the interface. Click + for the method of String analyze(String) to open the input field. Enter a string you want to give to the user program, and click invoke to call the service with JSON RPC. The results are displayed as shown below.

Figure 1: GUI for JSON RPC

See also

• Run a user program as a RaSC service
• Call through ProtocolBuffers
• Call by SOAP

[1]	This package is generated from the project pkg_basic in GitHub.