User's Guide (the First Step)

OpenSOAP Project
The Middleware as Platform for IT Application Services

First Step Guide

First Step: Getting the Hello sample to work(Linux Version)

OpenSOAP Installation

Preparing The Execution Environment

If the following software packages are not already installed, download from the appropriate distribution site and install. For testing connections between OpenSOAP, it is not necessary to have the Java environment.

1. Apache(http://httpd.apache.org/) or similar http server
2. libxml2 development kit(http://xmlsoft.org/)
3. OpenSSL development kit(http://www.openssl.org/)

OpenSOAP Download

Download the latest OpenSOAP package(opensoap-1.0-xxxxxx.tar.gz) from

http://opensoap.jp/download.html

Unpacking the package

Unpack the package in the your user directory

% tar zxvf opensoap-1.0-xxxxxx.tar.gz

or,

% gzip -dc opensoap-1.0-xxxxxx.tar.gz | tar xf -

Compiling/Installing The Package

In the top directory of the unpacked package, use

% ./configure
% make

to compile all the package components. By default, the CGI executables directory is the same as for VineLinux and RedHatLinux6.X, /home/httpd/cgi-bin. For distributions of RedHatLinux7.x, TurboLinux7, etc, use

% ./configure --with-cgi-bin=/var/www/cgi-bin/
% make

to compile. For other distributions, use the configure option to specify the location of cgi-bin. Having executed the commands above, and making sure there are no errors, use

% su
% make install

to install. This completes the installation.
At this point, the OpenSOAP API and OpenSOAP Server(Ref.1) have been installed, and the sample files have been compiled. With the OpenSOAP Server installed, a copy of soapInterface.cgi(Ref.2) can be found in the CGI executable directory.

Ref.1 Using the OpenSOAP Server allows you to send dispatches to services, perform asynchronous messaging and message routing.(See below for details)

Ref.2 soapInterface.cgi is the OpenSOAP Server entry (endpoint) interface.

Running the HelloService

To test the samples in the existing directory structure, change directory to samples/Hello, which contains the Hello sample. Using

% su
% make service-install

installs the service program in the CGI directory and /usr/local/opensoap/services/Hello, and prepares for connection to the OpenSOAP Server.
(The main body of the HelloService generated by the full compile can be found at samples/Hello/.libs/HelloService)

With this situation, using the following command,

% ./HelloClient myname

the client program HelloClient, sends(Ref.3) a SOAP message via HTTP, to the Hello service program endpoint,

http://localhost/cgi-bin/HelloService.cgi

and analyses the response.
(The default is not the OpenSOAP Server (soapInterface.cgi))

Ref.3 When changing the endpoint of a message being sent to the OpenSOAP Server, it can be specified on line 70 of the HelloClient.c sample program. After modification, re-make and install the sample program. See below for settings for use with the OpenSOAP Server.

Advice for using an original Makefile

In the above installation procedure, with automatic generation by automake, the package directory structure dependent Makefile is used . An independent Makefile, Hello.mak, is provided in the Hello directory. To create an original Makefile please refer to this.
To use this to install the HelloService, firstly in the directory samples/Hello/, use

% make clean

to remove the executable and initialize. Then, modify the value of the CGI executable directory (CGI_BIN_DIR) in the Hello.mak file to match the distribution being used.

Next, to install the sample, use

% make -f Hello.mak

after which, use

% su
% make -f Hello.mak install

to install in the CGI directory and /usr/local/opensoap/services/Hello as before, and to prepare for connection to the OpenSOAP Server.

Using the OpenSOAP Server

Through the OpenSOAP Server, several services can be used at a single endpoint.
To use the OpenSOAP Server, the endpoint setting of the client is set to

http://localhost/cgi-bin/soapInterface.cgi

(As seen above, HelloClient.c is modified.)
In the previous description, messages are sent to

http://localhost/cgi-bin/HelloService.cgi

By using the OpenSOAP Server, dispatches to a service, asynchronous messaging and message routing services are possible.

In order to use the OpenSOAP Server, the XML description of

/usr/local/opensoap/etc/ssml/Hello.ssml

generated in the previous Hello sample service installation is checked. (See : SSML_Readme.txt)

The ssml file specifies the relationship between the OpenSOAP Server and the service program (/usr/local/opensoap/services/Hello/HelloService).

In the default case, a StdIO type connection is specified when a Hello call to the server is made.
(For a socket type connection, the service must be registered with inetd. (See : RegistService.txt))

A StdIO connection type is where standard I/O is used to communicate directly with the OpenSOAP Server. With these settings, in the file

/usr/local/opensoap/etc/ssml/Hello.ssml

specifies the service program and

<operation type ='HelloStdio'>Hello</operation>

specifies the connection name to be used.

When the ssml file and server settings have been modified, it is necessary to reload the OpenSOAP Server. At this point, the server should be restarted.

% /usr/local/opensoap/sbin/opensoap-server-ctl reload

(the OpenSOAP Server settings will be reloaded)

or,

% /usr/local/opensoap/sbin/opensoap-server-ctl stop
% /usr/local/opensoap/sbin/opensoap-server-ctl start

(This restarts the OpenSOAP Server. *The stop operation must be executed first.)

after which the client execution can be tested.