\chapter{The resource manager}\label{chap:rm}

\index{resource manager}

\begin{quote}

  Seek and ye shall find.\\

  -- Luke 11:9

\end{quote}

\section{Introduction}

The resource manager is a special kind of the SN ({\em service

  node})\index{service node} that keeps track of the NoTA-services in a given

NoTA system. It can be compared to Domain Name Servers\index{Domain Name

  Server} (DNS) on the internet. You can find the official specification

(WSDL) for the resource manager in appendix~\ref{chap:rm-sis}.

Note, in previous chapters, we've over talked about SNs or service nodes. In

this chapter we'll mostly mention \emph{serivices}\index{service}, which is a

bit more abstract - an SN is a concrete, running implementation, which offers

a certain service.

\section{Ontology and service description}

Many of the RM functions refer to the \emph{ontology} and \emph{service

  description} of a certain service.

\emph{Ontology}\index{ontology} is a philosophical concept referring to the

nature of reality. In information science, the word is use slightly

differently -- it denotes a \emph{domain} or \emph{namespace} in which a set

of concepts live. This is also what it means in NoTA, with the 'concepts'

being our services.

A \emph{service description} is a name describing a service. Within an

ontology, usually there is some rule or convention for what the service

descriptions look like. The resource manager lives in the

\emph{NoTA}-ontology. It's service description is shown in

table~\ref{table:rm-service-desc}.

\begin{table}[h]\label{table:rm-service-desc}

  \caption{Resource Manager Service Description}

  \begin{tabular} {| l| l | l | l |}

    \hline

    {\bf \#} & {\bf element} & {\bf

      value} &  {\bf notes} \\ 

    \hline

    \hline

    1&{\tt SRV\_AREA } &  {\tt SYSTEM} & \\

    2&{\tt SRV\_NAME } &  {\tt ResourceMng} & \\

    3&{\tt SRV\_MAJOR } &  {\tt 01} & \\

    4&{\tt SRV\_MINOR } &  {\tt 00} & \\

    5&{\tt VERSION }    & \emph{xxx}  & three digit source code version\\

    \hline

  \end{tabular}

\end{table}

Note that the ontology for your other services (SNs) can look quite different

-- the ontology defines the fields etc.

Implementation note: the reference implementation requires both ontology and

service description to be valid C-strings - ie., not contain embedded

\texttt{\\0}-characters. You can try of course, but don't say we did not warn

you.

\section{Service definition}

As mentioned, the Resource Manager is 'just another' Service Node - and as

things go, it has its service definition file. 

As we have seen before, the XML service definitions are a bit verbose. So once

more, we'll use our little shorthand notation.

\subsection{Registration and de-registration}

If you want to register your NoTA-service (SN) with the resource manager,

you'll need to send the \texttt{Register\_req}-message, with an \emph{ontology

name}, a \emph{service description} and a \emph{registration certificate}:

\begin{verbatim}

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

                            nota:bdata service_desc,

                            nota:bdata cert_reg);

\end{verbatim}

After registration, the Resource Manager will respond with

\texttt{Register\_cnf}. In case there is no error (see the

\texttt{status}-parameter), it will give you the service-id, and two

certificates (that you should save carefully), for de-registration and

activation.

\begin{verbatim}

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

                           nota:sid_t sid,

                           nota:bdata cert_dereg,

                           nota:bdata cert_act);

\end{verbatim}                       

When you're closing down your service, you should to deregister it:

\begin{verbatim}

in: [0x0003] Deregister_req (nota:sid_t  sid,

                             nota:bdata  certificate);

out: [0x0004] Deregister_cnf (tns:status_t  status);

\end{verbatim}

\subsection{Challenge/response}

The resource manager also uses a simple one-way challenge-response mechanism;

as you can see from the \texttt{\_ind}-suffix, \texttt{Challenge\_ind} message

arrive unsollicited: your RM-using service might receive it any time, and

should then give the appropriate response.

\begin{verbatim}

out: [0x0010] Challenge_ind  (nota:bdata  challenge);

in:  [0x0011] Challenge_rsp  (nota:bdata  response);

\end{verbatim}

The exact nature of the algorithm to use for challenge/response is

implementation-defined. \textbf{Note}: currently, challenge/response is not

implemented in the reference implementation.

\subsection{Service resolution and discovery}

The main purpose of the resource manager is to provide for service resolution

and discovery. For \texttt{ResolveService\_req}, you need to know the

\emph{exact} ontology name and service description.

\begin{verbatim}

in:  [0x0020] ResolveService_req  (nota:bdata  ontology_name,

                                   nota:bdata  service_desc);

out: [0x0021] ResolveService_cnf  (tns:status_t  status,

                                   nota:sid_t    sid);

\end{verbatim} 

When the requested service is found (or not), you will receive

\texttt{ResolveService\_cnf} with either the SID (status = \texttt{S\_OK}, or

some error code (\texttt{E\_SERVICE\_NOT\_FOUND},

\texttt{E\_GENERAL\_ERROR}). If you get one of the error codes, you should

ignore the \texttt{sid} parameter.

Instead of asking for specific services, you can also request the full list of

services that have been registered with the resource manager, using th

\texttt{ListOfServices}-messages. You \textbf{do} need to know the ontology

name though.

\begin{verbatim}

in:  [0x0030] ListOfServices_req  (nota:bdata ontology_name);

out: [0x0031] ListOfServices_cnf  (tns:servicelist_t servicelist);

\end{verbatim}

\subsection{Events}

The Resource Manager also has an events-interface; that is, it can notify of

certain things happening, such as new services becoming available or having

left.

To get notifications about a new service registration, use \texttt{

  EVENT\_SERVICE\_REGISTERED}; for notifications about services

de-registering, use (not surpringly) \texttt{EVENT\_SERVICE\_DEREGISTERED}.

When registering for events succeeds, the RM will return you

(\texttt{NewEvent\_cnf} an \texttt{event\_id}, which is a number that

identifies this particular event-notification. When the RM notifies you about

something (with \texttt{NewEvent\_ind}, it will include this number. Note

these \texttt{NewEvent\_ind} messages could come at any time.

\begin{verbatim}

/* for some reason, the RM defines the codes in octal notation;

   0100 ==> 0x40; */

in:  [0100] NewEvent_req    (tns:event_t event

                             nota:bdata  ontology_name,

                             nota:bdata  service_desc);

out: [0101] NewEvent_cnf    (nota:uns32   event_id,

                             tns:status_t status); 

out: [0102] NewEvent_ind    (nota:uns32   event_id,

                             tns:event_t  event); /* event_t param?! */

\end{verbatim}

With the \texttt{DeleteEvent}-messages, you can tell the Resource Manager that

you are no longer interested in certain notifications. 

\begin{verbatim}

in:  [0103] DeleteEvent_req  (nota:uns32  event_id);

out: [0104] DeleteEvent_cnf  (tns:status_t  status); 

\end{verbatim}

\section{How to find the Resource Manager}

As we have seen, you can use the RM to find other service nodes. But how can

we find the resource manager itself? This chicken-and-egg problem is solved by

giving the resource manager a well-know service-id and port.

\textbf{Important:} The resource manager can be found on SID \textbf{0} and

port \textbf{0}.

From chapter~\ref{chap:h-in} you may remember what a NoTA-address looks like:

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

struct nota_addr {

  sid_t        sid;       /* service identifier */

  unsigned int port;      /* port of the sid */

  vdid_t       device;    /* virtual device id */

};

typedef struct nota_addr nota_addr_t;

\end{lstlisting}

So, for the RM we can write\footnote{note that we will ignore the

  \texttt{device}-parameter for now}:

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

const nota_addr nota_addr_t NOTA_RM_ADDRESS = { 0, 0, 0 };

\end{lstlisting}

You should make sure that your own services do not conflict with the

RM-address.

Another important thing to remember is that one should communicate with the RM

using message sockets, i.e., \texttt{SOCK\_SEQPACKET}.

\section{Questions}

\begin{enumerate}

\item What's the purpose of the Resource Manager?

\item What's an ontology in the NoTA-context? And what's a service

  description?

\item How can we find from our application node the Resource Manager?

\item How can I find out about if some service is available, if I know it's

  ontology and service description?

\item How can I find out when the list of registered services changes?

\end{enumerate}