Xobas Software'> ]> release: &PRODUCT;-&version; - &release-date; Bas Driessen &xobas;

bas.driessen@xobas.com

Original author and current maintainer. 2002-©right-year; The ProLinga Team Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License". This document describes the ProLinga-Soap Project, how to build the software components and documents the API reference of the prolinga-soap libraries. The ProLinga-Soap Project is a project which focusses on the development of a set of SOAP (1.2) client and service libraries. These libraries, after implementing, enable any application to send and receive XML request and XML response documents using the libxml2 format. The libraries are built around gSOAP from Associate Professor Robert van Engelen and libxml2, the popular open source XML toolkit. The service library (libprolingasoap) will transform any application to a real Web Service, while the client library (libprolingasoapclient) can be linked in into any existing application to send out and receive XML requests and XML responses from the Web Service. Main purpose for the creation of this project, is to provide an easy way to send XML documents between several components in the ProLinga Network environment. Since the result libraries of this project are very open, simple and easy to implement, they can be used in other non-ProLinga related projects. ProLinga-Soap has been built and tested on various popular GNU/Linux platforms as RedHat Fedora, Mandriva Linux, Debian, openSUSE, Ubuntu, FreeBSD and MS-Windows (Cygwin). Since all code is written in C++, it can be ported to all modern UNIX systems, GNU/Linux variants as well as MS-Windows and Mac O/S platforms. There are two types of libraries available: Soap Library Soap Client Library A very basic example program using the Soap Library, so it can run as a Web Service looks like this: int main() { PlSoapService sservice; /* Start as a web service. */ sservice.soapServiceStart("localhost", 8020, 3, 6, "/tmp/mySoap.log", 5); /* Return */ return 0; } void PlSoapLink(PlSoapProcessPtr link) { /* Every received request will access this function. */ /* Get Request */ xmlDocPtr docReq; docReq = link->getRequest(); /* Print on standard out */ xmlNodePtr curReq; xmlBufferPtr bufReq; bufReq = xmlBufferCreate(); curReq = xmlDocGetRootElement(docReq); xmlNodeDump(bufReq, docReq, curReq, 0, 1); printf("%s\n", (char *)xmlBufferContent(bufReq)); xmlBufferFree(bufReq); /* Create a response */ xmlDocPtr docRes; xmlNodePtr curRes; docRes = xmlNewDoc((const xmlChar *)"1.0"); docRes->children = xmlNewDocNode(docRes, NULL, (const xmlChar *)"ProLinga", NULL); curRes = xmlDocGetRootElement(docRes); xmlNewTextChild (curRes, NULL, (const xmlChar *)"String", (const xmlChar *)"Your request has been served."); /* Send back Response */ link->putResponse(docRes); } ]]> When running this application, function soapServiceStart is called and starts an indefinite loop listening for requests to arrive at TCP port 8020. As soon as a request arrives, function PlSoapLink is called with as argument a pointer to the class PlSoapProcess which holds the request the request in libxml2 format. In this example the request is printed on the console where the services has been started and a simple XML document is sent back by assigning this to the class PlSoapProcess. To compile the program, use the following command: g++ soap_s_test.cpp -o soap_s_test `pkg-config --cflags --libs prolinga-soap` You may need to set the environment variable PKG_CONFIG_PATH to point to the directories where prolinga-soap.pc and libxml-2.0.pc are located. This can be directory /usr/lib or directory /usr/local/lib/pkgconfig on GNU/Linux for example. You can also use a more traditional command as: g++ soap_s_test.cpp -o soap_s_test -I/usr/local/include/ -L/usr/local/lib -lprolingasoap -lxml2 -lpthread -lz A very basic example program using the Soap Client Library, so it can send a request to and receive a response from a Web Services looks like this: int main() { /* Create a request */ xmlDocPtr docReq; xmlNodePtr curReq; docReq = xmlNewDoc((const xmlChar *)"1.0"); docReq->children = xmlNewDocNode(docReq, NULL, (const xmlChar *)"ProLinga", NULL); curReq = xmlDocGetRootElement(docReq); xmlNewTextChild (curReq, NULL, (const xmlChar *)"String", (const xmlChar *)"This is a simple request."); /* Send of request and get response */ PlSoapClient sclient; xmlDocPtr docRes; docRes = sclient.soapCall(docReq, "http://localhost:8020",0); /* Print response */ xmlNodePtr curRes; xmlBufferPtr bufRes; bufRes = xmlBufferCreate(); curRes = xmlDocGetRootElement(docRes); xmlNodeDump(bufRes, docRes, curRes, 0, 1); printf("%s\n", (char *)xmlBufferContent(bufRes)); xmlBufferFree(bufRes); /* Free */ xmlFreeDoc(docReq); xmlFreeDoc(docRes); /* Return */ return 0; } ]]> This function creates a small XML document and sends that to TCP port 8020 of localhost. The request gets processed and a response comes back in XML format. This is then printed to the standard output. To test these 2 examples, start the service logic first in one terminal screen and then execute the client logic from another terminal screen. To compile the program, use the following command: g++ soap_c_test.cpp -o soap_c_test `pkg-config --cflags --libs prolinga-soapclient` You may need to set the environment variable PKG_CONFIG_PATH to point to the directory where prolinga-soapclient.pc is located. By default this is directory /usr/local/lib/pkgconfig on GNU/Linux for example. You can also use a more traditional command as: g++ soap_c_test.cpp -o soap_c_test -I/usr/local/include/ -L/usr/local/lib -lprolingasoapclient -lxml2 -lz The Soap library prolingasoap contains both the Service as the Client class, so client calls can be made as well. There are two types of product versions available for download: Production Version Development Version The production version is an official product release. This is a stable completed version which should be used in production environments. At this stage the product is only available as a source archive. Binary packages for a wide range of platforms will be available for download as the project progresses. Please visit the download page for the latest details. The development version is a snapshot of the latest source files. Since it can contain bugs as part of "work in progress", this version should not be used in production environments. Only developers who want to help with further development of the ProLinga Projects should download this version. Please read the details at the Subversion section of how to obtain the latest development version. ProLinga-Soap &version; has currently been built and tested on Fedora Core, Mandriva Linux, Debian, openSUSE, Ubuntu, FreeBSD and MS-Windows (Cygwin). The product should compile and run successfully on other GNU/Linux distributions as well as UNIX. GNU gcc/g++ >= 3.3 compilers/tools are required for a successful build. Required 3rd party package(s) for a successful build: libxml2. This product provides XML libraries. Optional 3rd party package(s): gSOAP. This product provides a SOAP/XML to C/C++ language binding. Not required for normal ProLinga-Soap builds, since gSOAP sources are integrated with ProLinga Soap sources. Only required when upgrading gSOAP or changing the SOAP schema. The current version used is gSOAP 2.8.8 stable. xsltproc. Command line processor. This package is only required to re-generate the HTML pages after making changes to the documentation. Assuming the directory /opt/builds will be used for 3rd party products, then in general the following steps need to be taken to download and extract a 3rd party product source archive. Download source tar/gz archive to /opt/builds/[product] Example: place libxml2-x.x.x.tar.gz in /opt/builds/libxml2 Use 'gunzip' to unzip the archive Use 'tar xvf [product.tar] to extract the archive. Example: tar xvf libxml2-x.x.x.tar. A new sub directory will be created with the new version of the product. Example: /opt/builds/libxml2/libxml2-x.x.x This way several versions of the same products can be installed next to each other. For product specific installation instructions see following sections. Product root dir: /opt/builds/libxml2 Current version: 2.7.8 Download: ftp://xmlsoft.org/libxml2/libxml2-2.7.8.tar.gz Build Instructions: cd /opt/builds/libxml2/libxml2-2.7.8 ./configure --prefix=/opt/builds/libxml2/libxml2-2.7.8 make make install This product only needs to be installed when upgrading gSOAP or when changing the SOAP schema. Product root dir: /opt/builds/gsoap Current version: 2.8.8 stable Download: http://sourceforge.net/projects/gsoap2/files gSOAP sources will be integrated into the ProLinga-Soap sources. When upgrading a gSOAP version perform the following steps: Go to the ProLinga-Soap src/gsoap directory and remove all files except prolingaSoap.hpp Generate a new SOAP schema by typing: "[gsoap-unpack-dir]/gsoap-2.8/gsoap/bin/linux386/soapcpp2 -2 prolingaSoap.hpp". This will generate (about) 14 files. Copy the files stdsoap2.cpp and stdsoap2.h from [gsoap-unpack-dir]/gsoap-2.8/gsoap to the ProLinga-Soap src/gsoap directory. Build ProLinga-Soap. (make and/or make install) Done. When changing the ProLinga-Soap schema you should know what you are doing, otherwise DO NOT TOUCH or all projects using the ProLinga-Soap library will fall over! The product archive can be extracted to any desired directory using unzip (.zip file extension) or gunzip (.gz file extension)/ bunzip2 (.bz2 file extension) and tar. After extracting, the following directories will be created: Directory Description &PRODUCT;-&version; Product version root directory. &PRODUCT;-&version;/config Config build information. &PRODUCT;-&version;/doc Documentation. &PRODUCT;-&version;/src All source and internal header files. &PRODUCT;-&version;/tests Self tests. &PRODUCT;-&version;/prolinga External (API) header files. To build the product go to the product root directory and run the configure script. For default installation in /usr/local type: ./configure To install into another directory type: ./configure --prefix=/any/dirname/ For all other configure options, type: ./configure --help After running the configure script, the product can be build with: make To run the optional self-test type: make check After compilation, the binaries, libraries and header files can be installed with: make install You may need root access for this last option. By default, HTML documentation pages are available in the doc/html directory. These pages are generated from DocBook XML file format files in /doc. To re-generate the HTML pages from these files type: make html The command line XSLT processor xsltproc must be available from $PATH to be able to generate the HTML documentation. Many of the ProLinga Projects are dependent on 3rd party libraries. These (non system) dependencies are outlined below. If these 3rd party products are not installed in either /usr/bin, /usr/lib, /usr/include or /usr/local/bin, /usr/local/lib, /usr/local/include, the additional configure option needs to be provided when building. Dependency Version Configure Option libxml2 >=2.6.5 --with-libxml-prefix=/path/to/libxml2 The default configuration options provide libraries which can be used both to develop/debug as to run the product. However better builds are possible for a dedicated development or production environment. In production environments, builds are needed which contain minimal (debug) overhead, so they are fast and small. To build such binaries/libraries, the --enable-final options can be used. Example: ./configure --enable-final The enable-final flag is configured to be used with GCC environments only. If access to more compilers become available over time, the enable-flag will be ported to those compilers as well. In development environments, builds are needed producing warnings, enabling maximum debugging info etc. Several options are available here. --enable-warnings : Set all compiler warning flags --enable-debug : Enable all debug messages --enable-gprof : Enables profiling with gprof (GCC only) All ProLinga Projects are under constant active development. This includes issues related to fixing bugs, increasing performance etc, as well as expanding the various projects with new features. This chapter provides information of all these types of tasks as well as details of how to join the development team. This section contains a list of work that needs to be done on the product. A more detailed and up to date list is available on the ProLinga Bugzilla Server. Implement XML Schemas for validation. Libxml2 is finishing up XML schemas. If it is still too far away, start with DTD. ProLinga-Soap is written in C++. Libxml2 however is C only. There is a C++ wrapper for this XML parser library. Details at http://libxmlplusplus.sourceforge.net/. Some strings/paths are hardcoded in the product. This all should be reviewed and be removed or made all configurable using a config file. Utilities. Code review and cleanup. Logging. A simple logging mechanism has been implemented. However, it appears that gSOAP has a logging system of its own. This should be investigated and implemented (if useful). Self-tests need to be developed for quality control. Porting to more platforms. A Subversion tree containing the latest project sources is available at http://svn.prolinga.org. For access please contact the ProLinga Team. Bugzilla software development and bug tracking system to manage the ProLinga projects is available at http://bugzilla.prolinga.org. For access please contact the ProLinga Team. Are you ready to join the ProLinga Team? There are several ways you can help: Use the product. Tell us what you think, ideas, bugs etc. Fixing bugs. Visit the development section on the ProLinga Web Site, choose a bug, fix it and send us the code changes. Enhancements. Have a look at the enhancement section of the to-do list and let us know which new feature you want to help to develop. Porting. To be successful it is essential that the ProLinga Projects are available on a wide range of platforms. We need help in porting and testing as well as providing binary releases for many different platforms. Let us know if and how you can help out. Real world examples. Are you using ProLinga products or do you know people who are happily using it. Tell us the story and provide some screenshots. This section contains the API reference for ProLinga-Soap. All the public interfaces are documented here. &prolinga-soap-API; &fdl;