Demo of SOAP using Idoox

This document is comprised of several parts:

Installation

Creating a demo

 This example will create a very simple demo. The server has a counter. The server accepts two commands: one to return the current value of the counter: getCount() and one to increment the counter: incrementCount()

After the software is installed, there are several steps involved in making this demo. Idoox has several tools that will do a lot of the work for you. Idoox will marshall the data across the nextwork for each method call. In order to do that, you need to tell it what the data looks like. This works much like CORBA´s and DCOM´s IDL language. The language is called SCL.

SCL (SOAP Contract Language) used to be a proposal for a standard. but there were several competing proposals. The people proposing the competing standards have since combined their efforts and created a new proposal Web Services Description Language (WSDL).

Luckily, you don´t have to learn SCL nor WSDL. The Idoox tools will take a Java file, create an SCL file, and then create the Stubs and Skeletons. The following steps help you through this process:

Setting your class path

 In order to run the Java tools, you must add the three Idoox .jar files into your classpath. These are: I know the last is a little strange. You would think that it would find it in the current working directory. I never want to mess up my classpath permanently, so I end up starting up a shell just for running this.

Making a Java file

You need to make a .java file that corresponds to the methods and datat that will be used to communicate between the modules. The reason that you must make a Java file is that the tools only work on a Java file. Our simple example has only two methods and one data. The file looks like this:

    public class Counter
    {
       private int count;
       public int getCount()
       {
          return count;
       }
       public void incrementCount()
       {
          count++;
       }
    }

Making an SCL file from the Java .class file

After making your .java file (we´ll put it into the file Counter.java), you will want to use the Idoox tool to make the SCL file. To do this, first compile your .java file and then run the SCL compiler, like this:

    javac Counter.java
    java com.idoox.soap.Java2SCL dsl-cnt Counter > Counter.scl

The first parameter to Java2SCL is a namespace. You only need make this something unique. It isn't terribly important. It will only be used inside the XML documents.

For more information on the Idoox API, see http://www.zvon.org/idooxoap/doc/api/

Making the stubs and skeleton from the SCL file

Now, we are ready to create the Stubs and Skeletons. The SCL compiler creates these C++ files from the SCL file like this:

    java -Ddebug.config=none com.idoox.soap.SCLCompilerC -v -u Counter.scl Counter

Filling out the stub code

Now, you need to finish the stubs and skeletons that were created. First, the file CounterImpl.h needs to have the instance variable declarations added. The two lines indicated below are added:

class CounterImpl : public SOAP_ReferencedInterface {
  private:       // added
     int m_iCount;  // added
  public:
  CounterImpl();
  virtual ~CounterImpl();
  Kind getKind() const { return Implementation; };
  DOMString getID() const { return "dsl-cnt#Counter"; };
  int getCount ();
  void incrementCount ();
};

Now, the file CounterImpl.cpp needs to have its stub code completed. The SCL compiler will make stub methods with comments that they need their bodies coded. We finish the methods as follows:

  CounterImpl::CounterImpl() {;
       m_iCount = 0;
  }
  CounterImpl::~CounterImpl() {;
       // put the destruction code here - this can be left empty
  }
 
  int CounterImpl::getCount () {
       return m_iCount;
  }
 
  void CounterImpl::incrementCount () {
       m_iCount++;
  }

Writing the server and the client code

We write the client program in file CounterClient.cpp.

CounterClient.cpp

And then we write the server program in file Server.cpp.

Server.cpp

Compiling

The rest is normal programming; however, getting the libraries correct is a little complex. I´m not listing that yet until I can get it siplified.

You might (you definitely must for RedHat) need to set up your library path first, though. You should set this library to include the "lib" directory under your xerces install directory and to include the "build/lib" directory under your IdooXoap-C install directory.

In RedHat Linux with bash, set your library path with:

    export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:<xerces-c-install-dir>/lib:<IdooXoap-C-install-dir>/build/lib

For example,

    export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:/usr/local/pkgs/xerces-c/lib:/usr/local/src/IdooXoap-C/build/lib

Running the programs

Once the programs are made, start the server. The demo servers are all stand-alone servers (they do not require a Web Server to be running). Both the server and the client have a lot of debugging messages, so you might want to direct STDERR to /dev/null.

The server needs no parameters, so here's an example of starting the Structures demo server:

    cd build/bin
    ./CounterServer 2> /dev/null &

Now you can run the client passing the URL of the server as the only parameter.

    ./Structures http://localhost:8080 2> /dev/null