\chapter{The stub-generator}\label{chap:stubgen}

\index{stub-generator}

\section{Introduction}

We discussed the {\tt h\_in} in chapter \ref{chap:h-in}, and we saw that there

is quite some work involved in creating a simple {\em hello-world}

example. Much care is needed to be taken to manually marshal and unmarshal the

data and call the right handler functions. This is error-prone and

makes it hard to focus on the business logic of your system.

To alleviate that problem, there is the stub-generator or {\tt stubgen}. The

stub-generator generates the 'plumbing\index{plumbing} code' needed for

writing ANs\index{application node} and SNs\index{service node}, similar to

what an IDL\index{interface definition language}-compiler does in the world of

CORBA\index{Common Request Broker Architecture}. The language that the stub

generator uses for describing services, is WSDL\index{Web Services Description

Language} or {\em Web Services Description Language}

~\cite{Booth:07:WSD}. WSDL is used on the internet to specify the interface

that web services offer, and is (with some restrictions) a good match for NoTA

services as well.

In this chapter, we discuss the backgrounds of service definition files and

the stub-generator; you can find a practical example in the next chapter.

\section{Writing a service definition}

The starting point for using the stub-generator is to define the service

definition. You should start with doing some deep thinking about what your

service should do, and how it should do that. Designing good interfaces is an

art in itself - see chapter~\ref{chap:development} for some guidelines and

some pointers to other material.

In chapter~\ref{chap:h-in}, we mentioned that the {\tt H\_IN}-API is inspired

by the BSD-sockets API, but that you should be careful \emph{not} to make too

many assumptions about the {\tt H\_IN}-API based on knowledge of BSD-API. The

same is true for the WSDL; reading the WSDL specifications and applying all

that to your NoTA-WSDL files will generally not work. NoTA supports a subset

of WSDL 1.1.  However, this chapter should give you enough information to work

with NoTA-flavor of WSDL.

\subsection{Contracts}\index{contract}

One, somewhat surprising feature of the NoTA service definitions, is that they

describe \emph{both} the client-side and the server-side. That is, the service

definition file describes all the messages the server will accept, but also

those for the client. In other words: {\bf a service definition is a contract

  between a Service Node and an application node}. It stipulates the

obligations of {\bf both} parties.

We emphasize this, because it is different from systems like CORBA or

COM\index{Component Object Model}, where the service (or interface)

definitions {\em only} describe the behavior of the 'server'.

\subsection{Using WSDL}

The NoTA {\tt stubgen} uses a WSDL\index{Web Services Description

Language}-based format for describing services. WSDL uses XML\index{extensible

markup language} as its substrate, which makes it a rather verbose format. On

the other hand, it can easily be processed with automated tools.

A service-description file looks something like this:

\begin{lstlisting}[language=XML,numbers=none]

<?xml version=¨1.0¨ encoding=¨UTF-8¨>

<definitions .....>

        <types>

                ..... some user-defined types ....

        </types>

        <message .... >

                .... message 1 details ....

        </message>

        <message .... >

                .... message 2 details ....

        </message>

</definitions>

\end{lstlisting}

Let's go through these section shortly, and discuss them in more detail after

that.

\begin{itemize}

    \item {\tt definitions} - this section includes meta-information about

  this service definition file, and may refer to outside resources;

    \item {\tt types} - this (optional) section defines types specific for

  this service definitions; 

    \item {\tt messages} - this section defines the actual messages that we

  can send or receive. This is the most interesting section of the service

  description.

\end{itemize}

\subsubsection{Definitions}

The {\tt definitions} part specifies meta-information about the service

definition. These are currently \textbf{ignored}  by the stub-generator, so

let's no go into them here.

\subsubsection{Types}

The \texttt{types} defines additional types for use in the service

definitions. It may include simple types (think: {\tt typedef}), complex types

(think: {\tt struct}) and enumerations (think: {\tt enum}). Obviously, you are

not {\bf required} to define your own types.

For an example of this, we can look at the service definition for the Resource

Manager (we'll discuss the Resource Manager in chapter~\ref{chap:stubgen});

you can find the full service definition for the Resource Manager in

appendix~\ref{chap:rm-sis}. Here is the \texttt{types}-part (edited for

readability):

\begin{lstlisting}[language=XML]

  <types>

    <!-- Status options. -->

    <simpleType name="sid_t">

       <restriction base="nota:uns16" />

    </simpleType>

    <simpleType name="status_t">

      <restriction base="nota:uns32">

        <!-- Operation completed successfully. -->

        <enumeration value="0x0000">S_OK</enumeration>

        <!-- Errors: -->

        <enumeration value="0x1000">E_GENERAL_ERROR</enumeration>

        <enumeration value="0x1010">E_SERVICE_NOT_FOUND</enumeration>

        <enumeration value="0x1020">E_UNKNOWN_EVENT</enumeration>      

        <enumeration value="0x2000">E_INSUFFICIENT_RIGHTS</enumeration>

      </restriction>

    </simpleType>

    <!-- Service list type. -->

    <complexType name="servicelist_t">

      <sequence>

        <element name="service_desc" type="nota:bdata" minOccurs="0" 

                             maxOccurs="unbounded" nillable="true"/>

      </sequence>

    </complexType>    

  </types>

\end{lstlisting}

Looking through this example:

\begin{itemize}

    \item lines 2-5 specify a {\tt simpleType}: {\tt sid\_t} is a '{\tt

  typedef}' for a {\tt nota:uns16}-type. We listed the NoTA-types in

  table~\ref{table:service-signals}; the corresponding name in the service

  definition is that name in small letters, namespaced with {\tt nota:}. So,

  in this case, we get {\tt nota:uns16}.

  In the WSDL way notation, we say that

  the {\em base restriction} on the {\tt sid\_t}-type is that its values must

  be in the range of a {\tt nota:uns16};

    \item lines 7-18 specify another {\tt simpleType}: {\tt status\_t} is an

  ´{\tt enum}'. Line 8 says that the base-type here is a {\tt

  nota:uns32}\footnote{apparently, the designer was expecting {\em many}

  event codes...}. 

  After that, some the {\tt enumeration}-element defines

  named values for various states. Note that that they are all part of the

  {\tt restriction};

    \item Finally, lines 21-26 define a {\tt complexType}, a named type that

  consist of {\tt element}s and {\tt sequence}s of elements. Think {\tt

  struct}.

  An {\tt element} is a named value with a certain type; in this case a {\tt

  service\_desc} of type {\tt nota:bdata}. The astute reader will note that

  that type is not defined; indeed. {\tt nota:bdata} can mean either {\tt

  BDAT1} or {\tt BDAT2}, and both AN an SN must support {\bf both};

  stubgen-generated code does this automatically.

  You can also specify attributes such as {\tt minOccurs}, {\tt maxOccurs} and

  {\tt nillable}; these attributes can be useful for descriptive purposes, but

  they are currently ignored by the stub-generator.

  The {\tt sequence}-tag tells us we have a {\em sequence} of $0~\ldots~n$

  of such {\tt

  service\_desc}-elements.

\end{itemize}

\subsubsection{Messages}

We continue with a discussion of \emph{messages}. The service definition

describe all messages that nodes can sent each other. As we already mentioned,

the service definition is like a two-party contract, and it describes the

messages of \textbf{both sides}, service node and application node.

We turn to the service definition of \emph{resource manager} (to be discussed

in chapter~\ref{chap:rm}) once more for an example; we look at some messages

dealing with \emph{registration}. As we said before, there's no need to

understand what the RM does, we just want to look at the messages.

\begin{lstlisting}[language=XML]

  <!--           Service message interface           -->

  <!--                 Registration                  -->

  <message name="Register_req" code="0x0001" direction="in">

    <documentation>

      Message for registering a service.

    </documentation>

    <part name="ontology_name" type="nota:bdata">

      <documentation>

        Name for the used service ontology (e.f. "NoTA").

      </documentation>

    </part>

    <part name="service_desc" type="nota:bdata">

      <documentation>

        Service description following the defined ontology 

        (e.g. "NoTA_ServiceName_R01_01_v02").

      </documentation>

    </part>

    <part name="cert_reg" type="nota:bdata">

      <documentation>

        Service registration certificate.

      </documentation>

    </part>

  </message>

  <message name="Register_cnf" code="0x0002" direction="out">

    <documentation>

      Returns SID and status for the registration request.

    </documentation>

    <part name="status" type="tns:status_t">

      <documentation>

        Error code (S_OK, E_GENERAL_ERROR, E_INSUFFICIENT_RIGHTS).        

      </documentation>

    </part>

    <part name="sid" type="nota:sid_t">

      <documentation>

        Device context unique Service Identifier (SID).

      </documentation>

    </part>

    <part name="cert_dereg" type="nota:bdata">

      <documentation>

        Certificate needed for deregistering the service 

        (NULL string = no certificate needed).

      </documentation>

    </part>

    <part name="cert_act" type="nota:bdata">

      <documentation>

        Certificate for activating the service 

        (NULL string = no certificate needed).

      </documentation>

    </part>

  </message>

\end{lstlisting}

The example show two messages. The first is \texttt{Register\_req}, sent by

the application node to the Service Node (the RM, in this case). The second

message is \texttt{Register\_cnf}, which is a confirmation message sent by

the Service Node back to the Application node, to report of the

success/failure of the \texttt{Register\_req}-message.

Let's go through the example. First, \texttt{Register\_req}.

\begin{itemize}

    \item lines 3-22 define the \texttt{Register\_req}-message. In line 3 the

  \texttt{message}-element is opened with 3 important elements:

  \begin{itemize}

      \item \texttt{name=''Register\_req''}: unsurprisingly, this defines the

    message name; note that the message name is only there for it's

    informational value; it's not used on the protocol-level;

      \item \texttt{code=''0x0001''}: this defines the signal-id; nodes use the

    signal-id (not the \texttt{name}) to identify messages. The signal-id must

    be unique for a service definition; Note that the \texttt{code}-attribute

    is NoTA-specific and \textbf{not} part of WSDL;

      \item \texttt{direction=''in''}: the \texttt{in} value means that this

    is an \emph{incoming message} for the \textbf{service node}. The

    \texttt{direction} is always from the SNs perspective.

  \end{itemize}

    \item After that there is the aptly-named \texttt{documentation}; this

  contains some information for human consumption, and ignored for anything

  else.

    \item Then follow some \texttt{part}-elements. Each of these describe a

  parameter, with \texttt{name} and \texttt{type} attributes describing

  respectively the parameter name and its type. As before, the

  \texttt{name}-attribute is only there for informational purposes. The

  \texttt{type}-attribute determines what kind of data the message contains;

  the type can be one of the basic NoTA types, or one of the types we defined

  before in the \texttt{types}-section discussed before. \texttt{part}s can

  also contain \texttt{documentation}.

\end{itemize}

Without the XML-verbosity, the message looks something like:

\begin{verbatim}

   in: [0x0001] Register_req (nota:bdata ontology_name, 

                              nota:bdata service_desc,

                              nota:bdata cert_reg);           

\end{verbatim}

Now, let's look at the second message, \texttt{Register\_cnf} (line 24-48)

Most of the above also applies there, but let's focus on the differences.

\begin{itemize}

    \item In line 24, we give \texttt{Register\_cnf} its unique signal-id,

  and, importantly, we define the \texttt{direction} to be \texttt{out}. That

  means that is a message for the \emph{application node} - the AN must accept

  it;

    \item The other parts of the message are similar to what we have seen

  before.

\end{itemize}

Using our made-up notation, the function looks something like:

\begin{verbatim}

   out: [0x0002] Register_cnf (tns:status_t status, 

                               nota:sid_t   sid,

                               nota:bdata   cert_dereg,

                               nota:bdata   cert_act);           

\end{verbatim}

\subsubsection{WSDL: concluding}

This concludes our initial discussion of service definition files (they will

be back!). One important thing we did not explicitly mention is the importance

of {\em comments}; in XML\index{extensible markup language}, comments look

like {\tt <!-- comment -->} and they priceless when trying to comprehend the

thoughts of others when they designed the service - or even to comprehend your

own thoughts, a few months later.

The information in this section should be sufficient for you to write your own

service definitions. We can recommend the guidelines in

chapter~\ref{chap:development}. As said, designing interfaces is a kind of

{\em art} - it's always good to think of the poor {\em other} programmers that

will have to use your interfaces\ldots.

\section{The stub-generator}

We went through the details of service definition files. Service definitions

are an important communication tool for describing your services to others,

and reason about them on a functional rather than implementation

level. However, and even more important reason for having the service

definition files if for using the \textbf{stub-generator}.

The stub-generator is a tool that reads service definition files and generates

the 'plumbing' code for both application nodes and service nodes. As we've

seen in chapters~\ref{chap:h-in}~and~\ref{chap:h-in-example}, programming

nodes \emph{by hand} can be quite tedious. The stubgen can ease the burden

significantly.

The best way to find out what the stubgenerator actually generates, is to go

through the generated files of some simple example. But in short, the stub

generator takes the NoTA messages and transfers those in functions; so,

instead of determining the bytes to send, you call a generated function. This

function will then take care of the actual conversion of its arguments into

sequences of bytes. The stubgenerator makes message passing (to some extent)

seem like ordinary function calls.

\subsection{\texttt{nota-stubgen3.pl}}

If you have installed NoTA on your system (if needed, see

appendix~\ref{chap:installation}), there will be a tool called

\texttt{nota-stubgen3.pl}.

When we run it without any arguments, it prints the following:

\begin{verbatim}

Usage:

nota-stubgen3.pl {-option value} path wsdl_file {xsd_file} [output_file]

Options may be

        -platform name	the name of the platform for which the files

                        will be generated

                        Valid platform names are symbian, posix

Arguments

        path            path where the generated files will be created

        wsdl_file       name of the wsdl file of which the stub code is to be

                        generated

        xsd_file        optional; name of the xsd files with additional type

                        definitions

                        The file extension must be xsd, because they are

                        recognised as xsd files based on the extension

        output_file     optional; name for the output files

Example:

nota-stubgen3.pl -platform posix OutputDir file.wsdl typedef.xsd outname

	giving minimum number of parameters:

nota-stubgen3.pl -platform posix . file.wsdl

\end{verbatim}

We're assuming we are on a \texttt{posix}-platform here. Suppose we have a

service definition file \texttt{myservice.xml} in the current directory. We

can simply run:

\begin{verbatim}

  $ nota-stubgen3.pl -platform posix . myservice.xml

\end{verbatim}

Except for the somewhat unexpected '\texttt{.}'-parameter (the current

directory), it is quite straightforward. Running this will create:

\begin{itemize}

    \item \texttt{myservice\_service.c} and \texttt{myservice\_service.h}:

  these are the \emph{stubs} for the Service Node implementation;

    \item \texttt{myservice\_user.c} and \texttt{myservice\_user.h}:

  these are the stubs for the application node implementation;

    \item \texttt{myservice\_common.h}: contains common definitions for use by

  both the AN and SN implementations.

\end{itemize}

You will need to combine these stub-files with your own implementation of the

functions, and compile them to get working programs. We feel that is best

explained with an example: in the next chapter we will revisit the

Caesar-example of chapter\ref{chap:h-in-example} and re-implement it using the stub-generator.

\section{Questions}

\begin{enumerate}

    \item What are the advantages of using the stub-generator compared to

      writing the code 'by hand'? Are there any disadvantages?

    \item Are the NoTA service definitions compatible with WSDL? If not,

      what's the difference? 

\end{enumerate}