Changes between Version 25 and Version 26 of BluePrint/Synchronisation


Ignore:
Timestamp:
07/06/09 13:13:52 (13 years ago)
Author:
Hasanat Kazmi
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • BluePrint/Synchronisation

    v25 v26  
    11= WEB SERVICES API =
    22
     3(This API is also used by daemonX which drives automatic p2p syncing between clients)
     4
     5Supported web services:
     6JSON[[BR]]
     7JSON-RPC[[BR]]
     8[[BR]]
     9To do (partial work has been done):
     10XML[[BR]]
     11XML-RPC[[BR]]
     12[[BR]]
     13'''Service Proxy''':
     14        JSON: http://localhost:8000/sahana/admin/call/json
     15                e.g. http://localhost:8000/sahana/admin/call/json/getdata?timestamp=0&.........
     16        JSON-RPC: http://server's-ip:port/sahana/admin/call/jsonrpc
     17        replace json and jsonrpc with xml and xmlrpc respectively for xml
     18
     19'''Available functions''':[[BR]]
     20'''putdata(uuid, username, password, nicedbdump):'''
     21        This function is used to insert data in the system.
     22        args:
     23                uuid (required):
     24                        uuid of the machine which is calling, uuid of machine is 16 character unique string. In the case when web services client is also a Sahana instance, uuid will be generated and stored by deamonX.
     25                Username, password (required):
     26                        Used for authentication purposes. Both are strings. A user must be registered at the host machine with data alteration privileges. e.g. Administrator of the system can put data in the system.
     27                nicedbdump (required):
     28                        nicedbdump can be best illustrated using diagrammatically representation. If [] represents a python list then:
     29                        nicedump = [   //each element of this list is another list representing a database table[[BR]]
     30                                [[[BR]]
     31                                        table name,[[BR]]
     32                                        [ comma separated table attributes as string][[BR]]
     33                                        [   //each element in this list is a list which represents a row in table[[BR]]
     34                                                [comma separated row values][[BR]]
     35                                                [][[BR]]
     36                                                ..[[BR]]
     37                                                ..      [[BR]]                         
     38                                        ][[BR]]
     39                                ]       [[BR]]
     40                                [][[BR]]
     41                                [][[BR]]
     42                                ..[[BR]]
     43                                ..[[BR]]
     44                                ..[[BR]]
     45                        ]
     46       
     47        Note that if you pass a table using nicedbdump which is not present in database, it will be simply ignored.
     48        If nicedbdump is not formated properly then an error string will be returned. Following situations will raise an error:
     49        If nicedbdump is not a list.
     50        If nicedbdump is not list of lists.
     51        Each list in nicedbdump represents a table, say n:
     52                If n does not exactly has 3 elements.
     53                If first of these three elements is not a string data type.
     54                If second of these three elements, say s,  is not a list:
     55                        if s in this list is not a string
     56                If third of these three elements, say t, is not a list:
     57                        if each element in t is not a list, let such an element be r:
     58                                if number of elements in r is not equal to number of elements in s
     59                               
     60        If a table (s in the case described above) is not having 'id', 'uuid' and 'modified_on' as attribute. 'id' is unique id for each row in table. This 'uuid' is different from the 'uuid' which daemonX maintains, this is row uuid. 'modified_on' represents the last time data was modified (or created it not altered after creation)
     61        Note that only that data (referenced by row uuid) which has never life then the one in database will be added. In case of absence of that uuid in database, that data is be added.
     62        return:
     63                If user is authenticated and nicedbdump is successfully parsed, data will be added to the database and True will be returned. On the other hand, in case of error, error message will be returned as String.
     64
     65
     66'''getdata(uuid, username, password, timestamp = None):'''
     67        retruns data as nicedbdump defined in putdata. Data after timestamp time will returned, if None is passes as timestamp, then that data which has been added to the system after last getdata call from uuid will be returned.
     68        Args:
     69                uuid (required):
     70                        uuid of the machine which is calling, uuid of machine is 16 character unique string. In the case when web services client is also a Sahana instance, uuid will be generated and stored by deamonX.
     71                username, password (required except for local machine):
     72                        Both are strings. used for authentication, user must have privileges for reading the database. If service is called from local machine (i.e. with IP 127.0.0.1) username and password are ignored and user is given access. e.g. deamonX accesses this function locally without providing username and password.
     73                Timestamp (optional):
     74                        timestamp is of string type. It should be like “YYYY-MM-DD HH:MM:SS”. If timestamp = null is passes, system will automatically return data after last getdata operation between uuid and machine. deamonX uses this setting
     75
     76        return:
     77                In case of error (like failure to authenticate), error message as string will be returned. If successful, then nicedbdump will be returned which is described above.
     78
     79'''Example code''':[[BR]]
     80'''Python''':[[BR]]
     81
     82
     83{{{
     84from jsonrpc import ServiceProxy, JSONRPCException
     85#jsonrpc needs simplejson which we have to install first
     86s = ServiceProxy("http://localhost:8000/sahana/admin/call/jsonrpc")
     87try:
     88        nicedbdump = s.getdata("machinename12345","email@lums.edu.pk", "myPassword")
     89        if type(result) == str:
     90                #it means there is an error, now result has error messege
     91                pass
     92        else:
     93                #result is list type for sure,
     94                #result is nicedbdump type
     95               
     96        putit = s.putdata("machinename12345", "email@lums.edu.pk", "myPassword", nicedbdump)
     97        if putit == True:
     98                #data sucessfully sent, parsed and processes at server (but in this case no data will be added because you just queried data and sent it back)
     99                pass
     100        else:
     101                #its an error
     102                pass
     103except JSONRPCException, e:
     104        print repr(e.error)
     105
     106}}}
     107
     108
     109To do:
     110        Client examples for JAVA and .NET should be added … specially parsing of nicedbdump.
     111
     112Help:
     113        IRC: #sahana at freenode
     114        email: <Fran Boon> francisboon at googlemail dot com or hasanatkazmi at gmail dot com
    3115= Blueprint for Synchronization =
    4116