perfsonar development work

[Maciej Glowiak <>]

Hello Jochen,

Thanks for your very interesting e-mail.
I have similar impression how the client API should look like.

There are several levels of client API in Java.
Of course a developer of a client application may always send just 
textual message on port 8080 using TCP. But that's not the solution.
There are NMWG classes for Message construction and Axis functionality 
for SOAP. Unfortunately Axis uses DOM Document to store date, so our 
NMWG "DOM representation" must be converted into DOM Document. That's 
the performance issue to be resolved in the future.

But anyway, using such functionality is easy for client. It's only 
example (syntax errors are possible) for EchoRequest

=====================================================================

  //create NMWG Message -------------------------------------------

  Message requestMessage = new Message();
  requestMessage.setType("EchoRequest");

  Metadata m = new Metadata();
  m.setId("meta1");

  EventType et = new EventType();
  et.setEventType(
      "http://schemas.perfsonar.net/tools/admin/echo/2.0";);

  Data d = new Data();
  d.setMetadataIdRef("meta1");
  m.addEventType(et);
  requestMessage.addMetadata(m);
  requestMessage.addData(d);

  //convert Message to Document -----------------------------------

  DocumentBuilder builder = DocumentBuilderFactory.
                newInstance().newDocumentBuilder();

  Document requestDocument = builder.newDocument();
  requestDocument = message.getDOM(requestDocument);


  //send message as Document --------------------------------------

  AxisClient client = new AxisClient();

  Document responseDocument =  client.sendRequest(
                                          lsUrl,requestDocument);


  //convert responseDocument to Message ---------------------------
  Message msg = XMLUtils.convertToMessage(
                        responseDocument,
                        parserFile);

=====================================================================


So, basicaly that's the first layer. That's what we have now. In the 
future we intend to have all requests as just a simple methods (or at 
least the most important ones). I mean (basing on example above):

=====================================================================

  Message req = EchoRequestGenerator(
                  "http://schemas.perfsonar.net/tools/admin/echo/2.0";);
  AxisClient client = new AxisClient();
  Message resp = client.sendMessage(lsUrl, req);

=====================================================================

But of course someone must implement Generators for his request first.
That's the challenge for next months.

That was my understanding of Client API (for LS). I think it's the same 
as you proposed for Perl.

Best regards

Maciej



That's what we have for LS registration now.

Jochen Reinwand wrote:
> Hi all,
>
> In Utrecht there was some discussion about some sort of "client API". I had 
> the impression that sometimes people were talking about different things. But 
> it wasn't easy for me to follow the discussion since I'm neither a developer 
> nor user of the perfSONAR core. I always had our Perl implementation in 
> mind...
> I think it might be useful to give you an impression of our implementation. 
> Perhaps it helps to understand what at least I have in mind when talking 
> about some sort of perfSONAR API.
> I have to admit that our code is not as clean and nice as presented here, 
> because we still don't have some sort of "full blown API". I will only give 
> some excerpts with a lot of comments to give you an idea. This is not ready 
> to run code ;-)
>
> The following code is from our general message handler that gets the received 
> NMWG message to process it. Somehow it is called with the raw XML code of the 
> message. At the moment it gets it from the Perl SOAP implementation. But it 
> doesn't really matter. The only important fact is that the message can be 
> found in the variable $xmlmsg.
>
> First we are creating a NMWG::Message object that will give us an abstract API 
> to the message. We do NOT care about any XML stuff! We get some XML and 
> without even looking at it we are creating the object:
>
> $reqmsg =  NMWG::Message->new($xmlmsg);
>
> Now the variable $reqmsg contains the reference to the object. I hope the 
> Perlish code is not to confusing...
>
> What kind of message have we received?
>
> $messagetype = $reqmsg->get_message_type();
>
> Did we get a SetupDataRequest? If so, we will later on fill the request 
> message with the requested data turning it into a response message. But we 
> can already change the message type:
>
> if ($messagetype eq "SetupDataRequest"){
>   $reqmsg->set_message_type("SetupDataResponse");
> } elsif ($messagetype eq "EchoRequest"){
>   $returnstring = "I'm still alive and happy to talk to you!";
>   $reqmsg->set_message_type("EchoResponse");
>   return $reqmsg->return_result_code(
>     "success.echo", "$returnstring", "message"
>   );
> } else {
>   $errorstring = "Unknown messagetype: $messagetype";
>   $reqmsg->set_message_type("ErrorReturn");
>   return $reqmsg->return_result_code(
>     "error.common.action_not_supported", "$errorstring", "message"
>   );
> }
>
> There is a lot more code above. What's its purpose? The branch for the 
> EchoRequest message type is our (current) implementation of the EchoRequest 
> feature. Yes, these four lines.
> The last else is sending back an error if the message type is unknown.
>
> Perhaps later we are interested in a data section ("trigger"):
>
> $metaid = $reqmsg->get_data_trigger();
>
> All code above is generic code used in our generic perfSONAR service daemon 
> that can handle all requests for all services. The service the request is 
> addressed to (BWCTL MP, Hades MA, OWAMP MP etc.) is determined by looking at 
> the URI of the request. I don't want to go into further details, but the 
> system is quite nice and fully configurable using a small configuration file.
> The following code hands over the $reqmsg object to the responsible handler 
> after doing the generic processing and awaits the response:
>
> $response = $services{$service}->{handler}->handle_request($reqmsg);
>
> =====
>
> I hope you got a good impression of our code. The basic idea: Separate the 
> work between different modules/classes. Our generic message handler has no 
> idea about how to parse XML. The message class has no idea where the source 
> XML comes from or what to do with the content, it just makes it available.
> Also the generic message handler only knows about the generic parts of a 
> NMWG/perfSONAR message. Other, more specific handling is done by the 
> responsible "service module". You can compare this with a plug-in 
> architecture. For creating a new service, you only need to develop a module 
> handling the specific parts of the message and add it to the service daemon 
> via the configuration file.
>
> This is exactly the same way, I think, a generic client API should be 
> implemented. It should be possible to create a message using this API by just 
> adding the information specific for the service you want to send the request 
> to. Sending the messages and parsing the response should also be done by the 
> client library. Afterwards the client programmer only needs to call a few 
> methods via the API to get the received data. The client programmer does not 
> need any knowledge about XML, SOAP or network protocols. It just uses the 
> perfSONAR API abstracting everything.
> Most likely it would be useful to add some sort of plug-in architecture to the 
> client API as well. This way creating service specific messages would be very 
> easy for services that already have a plug-in available:
>
> $response = send_msg(
>   perfSONAR::Message::BWCTL_MP->new(
>     src => "localhost",
>     dst => "mp.nowhere.com",
>     int => 2,
>     dur => 10
>   )
> );
>
> No XML, no SOAP, no NMWG. Only BWCTL parameters.
>
>
> Well, I think I finally finished this e-mail. Sorry for sending such a big 
> e-mail. I hope you enjoyed reading it nevertheless ;-)
>
> greetings,
> Jochen


--

 --------------------------------------------------------------------
| Maciej Glowiak        Network Research and Development            ||
| 

     Poznan Supercomputing and Networking Center ||
| (+48 61) 858 2024          -- skype_id: maciej_psnc   GG: 4526858 ||
 ====================================================================