| | 1 | = XML-RPC developing with gnowsis = |
| | 2 | 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: |
| | 3 | |
| | 4 | {{{ |
| | 5 | #!java |
| | 6 | // Example: call method getPossibleTagsForTagName of API 'tagging' on service 'gnowsis-server' |
| | 7 | // (include gnowsis.js and jsolait dependencies) |
| | 8 | |
| | 9 | // call method |
| | 10 | var tags = gnowsis_callXmlMethod("gnowsis-server", "tagging", "getPossibleTagsForTagName", rlabel); |
| | 11 | // result is an array of maps |
| | 12 | for (var i = 0; i < tags .length; i++) |
| | 13 | { |
| | 14 | // tag is a map, an array with named index. |
| | 15 | var tag = tags[i]; |
| | 16 | // read uri and name of result |
| | 17 | var tagUri = tag["uri"]; |
| | 18 | var tagName = tag["name"]; |
| | 19 | alert("hey, I found "+tagName+" ("+tagUri+")"); |
| | 20 | } |
| | 21 | }}} |
| | 22 | |
| | 23 | == What happens in this script? == |
| | 24 | |
| | 25 | 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. |
| | 26 | {{{ |
| | 27 | // (include dependencies) |
| | 28 | <head> |
| | 29 | <script type='text/javascript' src='web/jsolait/init.js'></script> |
| | 30 | <script type='text/javascript' src='web/jsolait/lib/urllib.js'></script> |
| | 31 | <script type='text/javascript' src='web/jsolait/lib/xml.js'></script> |
| | 32 | <script type='text/javascript' src='web/jsolait/lib/xmlrpc.js'></script> |
| | 33 | <script type='text/javascript' src='gnowsis.js'></script> |
| | 34 | </head> |
| | 35 | }}} |
| | 36 | |
| | 37 | When you have done that, the gnowsis_callXmlMethod() function is available. You can test that by calling something simple as this: |
| | 38 | {{{ |
| | 39 | // show the uri of the current user. |
| | 40 | alert(gnowsis_callXmlMethod('gnowsis-server','configure','getUserUri')); |
| | 41 | }}} |
| | 42 | |
| | 43 | 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). |
| | 44 | {{{ |
| | 45 | var tags = gnowsis_callXmlMethod("gnowsis-server", "tagging", "getPossibleTagsForTagName", rlabel); |
| | 46 | }}} |
| | 47 | |
| | 48 | 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. |
| | 49 | |
| | 50 | = So what services can I call? = |
| | 51 | You can call all services that are listed in the corresponding {{{service.xml}}} files. |
| | 52 | We encourage you to look at this service first: |
| | 53 | * TaggingApi, you can call the methods defined in the [http://www.gnowsis.org/statisch/0.9/doc/gnowsis-server/javadoc/org/gnowsis/pimo/TaggingApi.html TaggingApi - Javadoc] |
| | 54 | * PimoStorage, you can add/remove triples from the pimo via [http://www.gnowsis.org/statisch/0.9/doc/gnowsis-server/javadoc/org/gnowsis/api/DataAccessApi.html this api]. |
| | 55 | * every [http://www.gnowsis.org/statisch/0.9/doc/gnowsis-server/javadoc/org/gnowsis/api/package-summary.html gnowsis-server API] that is listed. |
| | 56 | * '''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. |
| | 57 | |
| | 58 | = And what about Mozilla and XUL? = |
| | 59 | 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. |
| | 60 | |
| | 61 | So, all Mozilla fanatics that want to SPARQL from out there, please look at the code of this SVN project: |
| | 62 | * https://dragontalk.opendfki.de/repos/dragontalk/trunk/dragontalk_tagging_thunderbird |
| | 63 | * [https://dragontalk.opendfki.de/repos/dragontalk/trunk/dragontalk_tagging_thunderbird/content/dragontalk_tagging_thunderbird/dt_tagging_messenger.js this file] for example, loads the tags for each e-mail when its browsed in TB. |
| | 64 | |
| | 65 | 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. |
| | 66 | |
| | 67 | = Ok, I want to do AJAX with gnowsis, what to do? = |
| | 68 | 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}}}. |
| | 69 | |
| | 70 | 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. |
| | 71 | |
| | 72 | |
| | 73 | |
| | 74 | |
| | 75 | = Restrictions and caveats = |
| | 76 | 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. |
| | 77 | |
| | 78 | |
| | 79 | = Links = |
| | 80 | Apache XML/RPC doc |
| | 81 | * [http://ws.apache.org/xmlrpc/ xml-rpc doc] |
| | 82 | * [http://ws.apache.org/xmlrpc/types.html xml/rpc types] |
| | 83 | |
