wiki:XmlRpcDeveloping

Version 11 (modified by sauermann, 18 years ago) (diff)

--

XML-RPC developing with gnowsis

Yes, we have AJAX, and we love it. You can call many services of gnowsis using XML/RPC. The nice thing about this approach is, that every object that is defined as API of gnowsis inside a service.xml file is automatically hosted as XML/RPC server. A small example to show what you can do when calling the TaggingApi: 

// Example: call method getPossibleTagsForTagName of API 'tagging' on service 'gnowsis-server'
// (include gnowsis.js and jsolait dependencies)

// call method
var tags = gnowsis_callXmlMethod("gnowsis-server", "tagging", "getPossibleTagsForTagName", rlabel);
// result is an array of maps
for (var i = 0; i < tags .length; i++)
{
  // tag is a map, an array with named index.
  var tag = tags[i];
  // read uri and name of result
  var tagUri = tag["uri"];
  var tagName = tag["name"];
  alert("hey, I found "+tagName+" ("+tagUri+")");
}

What happens in this script?

First the dependencies: to make this run, include the gnowsis.js dependencies. If you run gnowsis, go to ​http://127.0.0.1:9993/gnowsis-server/PimoTaggingAPI.html for an example. 

// (include dependencies)
<head>
<script type='text/javascript' src='web/jsolait/init.js'></script>
<script type='text/javascript' src='web/jsolait/lib/urllib.js'></script>
<script type='text/javascript' src='web/jsolait/lib/xml.js'></script>
<script type='text/javascript' src='web/jsolait/lib/xmlrpc.js'></script>
<script type='text/javascript' src='gnowsis.js'></script>
</head>

When you have done that, the gnowsis_callXmlMethod() function is available. You can test that by calling something simple as this: 

// show the uri of the current user.
alert(gnowsis_callXmlMethod('gnowsis-server','configure','getUserUri'));

We called a method to get tags with a certain name in it. The gnowsis_callXmlMethod() method takes three (or more) parameters. The result value is an XML/RPC result. If you want to know what is possible in XML/RPC see at the bottom for the external links. The result value is, in this case, an array containing named arrays (maps). 

var tags = gnowsis_callXmlMethod("gnowsis-server", "tagging", "getPossibleTagsForTagName", rlabel);

Note that when the server throws an exception, the exception message will be passed to the xml/rpc client, so you know whats happening when it fails.

The real Javascript example

Download gnowsis and run this page:

using only these lines of code: 

function runSerqlExample()
{
   // turn debug alerts off
   gnowsis_showdebugalert = false;
   var formC = document.forms["formserqlexample"];
   var queryString = formC.elements["rquery"].value;  
   try  {
	   var res = gnowsis_callXmlMethod("gnowsis-server", "dataaccess", "querySelect", 
    	  queryString, "serql");
   } catch (e)
   {
     alert("error querying: "+e);
   }
   renderSerqlExample(res);
}

/**
 * render the serql query result.
 * query result is a vector of hashmaps, pretty easy.
 */
function renderSerqlExample(res)
{
   gnowsis_debug("rendering table");
   var render = "<table>";
   for (var i = 0; i < res.length; i++)
   {
      var row = res[i];
      
      // render header?
      if (i==0)
      {
      	render+="<tr>";
		for (col in row)
		{
          render += "<td>"+col+"</td>";   
        }
        render += "</tr>";
      }
      
      // render row
      render+="<tr>";
      for (col in row)
      {
        render += "<td>"+row[col]+"</td>";  
      }
      render += "</tr>";
   }
   render += "</table>";
   var exampleOut = document.getElementById('SerqlExampleoutput');
   gnowsis_debug(render);
   exampleOut.innerHTML = render;
   gnowsis_debug("finished");
}

yes, you want to dig this?

A Visual Basic example

You need ​pocket-xmlrpc to run this. 

Public Sub testXMLRPC()
    Set f = CreateObject("pocketXMLRPC.Factory")
    Set enquireeditor = f.Proxy("http://localhost:9993/RPC2", "enquire2006_editor.")
    ' fake return value, required by vb in outlook
    Dim hurz As Variant
    hurz = enquireeditor.editResource("http://www.gnowsis.org", True, True)
End Sub

So what services can I call?

You can call all services that are listed in the corresponding service.xml files.

A list of all XML-RPC apis is kept on [GnowsisComponents], together with links to the javadoc.

We encourage you to look at this service first:

  • TaggingApi, you can call the methods defined in the ​TaggingApi - Javadoc
  • PimoStorage, you can add/remove triples from the pimo via ​this api.
  • every ​gnowsis-server API that is listed.
  • note that you can only call methods that have really simple input/output values. Not every method is allowed for XML/RPC access, we are currently working on making more methods available. Only methods with the following datatypes as input/output work:
    • no void result supported (XML/RPC standard)
    • Integer, Boolean, String, Double, javaa.util.Calendar, java.util.Date, byte[], java.util.Map, java.util.List
    • no more. espacially this will not work: com.hp.hpl.jena.rdf.model.Resource !
    • we are working on providing String-based interfaces for most of our methods.

And what about Mozilla and XUL?

Now comes the tricky part: You want to write an XPI plugin for Mozilla Firefox or Mozilla Thunderbird and access the nice sesame repository of gnowsis. That is possible, but it needs an adapted version of the jsolait library and it is easier to copy/paste our working prototype than to hack something from scratch.

So, all Mozilla fanatics that want to SPARQL from out there, please look at the code of this SVN project:

All you have to do is copy/paste the whole project, change some parameters, run the build.xml and you have a plugin for Thunderbird 1.5.

Ok, I want to do AJAX with gnowsis, what to do?

So the first thing you have to do, is run through the usual GnowsisDevelopingBeta. Then, you have a running gnowsis server with all the XML/RPC services available on localhost:9993.

The best way to use gnowsis XML/RPC and AJAX services is, at the moment, to edit the HTML files in /services/gnowsis-server/*.html. They form a nice basis to get started, we frequently enlarge them with more examples. You can also start any other HTML project on your harddisk, Javascript and JSOLAIT are rock-hard technology and run pretty easy.

Restrictions and caveats

No real ajax library used yet. Did you notice? we did not use coldfusion or any other cool Ajax library. We will, surely, soon do that.

Be aware that our server only answers to requests coming from 127.0.0.1. So, you will not be able to run server-to-server programs with it. That is good that way: gnowsis is a desktop server, not a web server. If you feel to change that, you may want to look at that jetty.xml file closer, but be warned: opening gnowsis to the network is not just a small security risk, its really a problem. Don't open the gnowsis ports to outside, people can easily run shell commands via the XML/RPC port with your user's rights and cause havoc on your machine.

Links

Apache XML/RPC doc

Dynamic HTML and XML: The XMLHttpRequest Object