Changes between Version 29 and Version 30 of BluePrint/Synchronisation


Ignore:
Timestamp:
08/18/09 20:33:13 (12 years ago)
Author:
Hasanat Kazmi
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • BluePrint/Synchronisation

    v29 v30  
    1 = WEB SERVICES API =
    2 
    3 (This API is also used by daemonX which drives automatic p2p syncing between clients)
    4 
    5 Supported web services:[[BR]]
    6 
    7 JSON[[BR]]
    8 JSON-RPC[[BR]]
    9 [[BR]]
    10 To do (partial work has been done):[[BR]]
    11 
    12 XML[[BR]]
    13 XML-RPC[[BR]]
    14 [[BR]]
    15 '''Service Proxy''':
    16         JSON: http://localhost:8000/sahana/admin/call/json
    17                 e.g. http://localhost:8000/sahana/admin/call/json/getdata?timestamp=0&.........
    18         JSON-RPC: http://server's-ip:port/sahana/admin/call/jsonrpc
    19         replace json and jsonrpc with xml and xmlrpc respectively for xml
    20 
    21 '''Available functions''':[[BR]]
    22 '''putdata(uuid, username, password, nicedbdump):'''
    23         This function is used to insert data in the system.
    24         args:
    25                 uuid (required):
    26                         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.
    27                 Username, password (required):
    28                         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.
    29                 nicedbdump (required):
    30                         nicedbdump can be best illustrated using diagrammatically representation. If [] represents a python list then:
    31                         nicedump = [   //each element of this list is another list representing a database table[[BR]]
    32                                 [[[BR]]
    33                                         table name,[[BR]]
    34                                         [ comma separated table attributes as string][[BR]]
    35                                         [   //each element in this list is a list which represents a row in table[[BR]]
    36                                                 [comma separated row values][[BR]]
    37                                                 [][[BR]]
    38                                                 ..[[BR]]
    39                                                 ..      [[BR]]                         
    40                                         ][[BR]]
    41                                 ]       [[BR]]
    42                                 [][[BR]]
    43                                 [][[BR]]
    44                                 ..[[BR]]
    45                                 ..[[BR]]
    46                                 ..[[BR]]
    47                         ]
    48        
    49         Note that if you pass a table using nicedbdump which is not present in database, it will be simply ignored.
    50         If nicedbdump is not formated properly then an error string will be returned. Following situations will raise an error:
    51         If nicedbdump is not a list.
    52         If nicedbdump is not list of lists.
    53         Each list in nicedbdump represents a table, say n:
    54                 If n does not exactly has 3 elements.
    55                 If first of these three elements is not a string data type.
    56                 If second of these three elements, say s,  is not a list:
    57                         if s in this list is not a string
    58                 If third of these three elements, say t, is not a list:
    59                         if each element in t is not a list, let such an element be r:
    60                                 if number of elements in r is not equal to number of elements in s
    61                                
    62         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)
    63         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.
    64         return:
    65                 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.
    66 
    67 
    68 '''getdata(uuid, username, password, timestamp = None):'''
    69         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.
    70         Args:
    71                 uuid (required):
    72                         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.
    73                 username, password (required except for local machine):
    74                         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.
    75                 Timestamp (optional):
    76                         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
    77 
    78         return:
    79                 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.
    80 
    81 '''Example code''':[[BR]]
    82 '''Python''':[[BR]]
    83 
    84 
    85 {{{
    86 from jsonrpc import ServiceProxy, JSONRPCException
    87 #jsonrpc needs simplejson which we have to install first
    88 s = ServiceProxy("http://localhost:8000/sahana/admin/call/jsonrpc")
    89 try:
    90         nicedbdump = s.getdata("machinename12345","email@lums.edu.pk", "myPassword")
    91         if type(result) == str:
    92                 #it means there is an error, now result has error messege
    93                 pass
    94         else:
    95                 #result is list type for sure,
    96                 #result is nicedbdump type
    97                
    98         putit = s.putdata("machinename12345", "email@lums.edu.pk", "myPassword", nicedbdump)
    99         if putit == True:
    100                 #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)
    101                 pass
    102         else:
    103                 #its an error
    104                 pass
    105 except JSONRPCException, e:
    106         print repr(e.error)
    107 
    108 }}}
    109 
    110 Note:
    111         You can write a client in language of your choice.
    112 
    113 Help:
    114         IRC: #sahana at freenode
    115         email: <Fran Boon> francisboon at googlemail dot com or hasanatkazmi at gmail dot com
    116 
    117 
    118 
    119 
    1201= Choosing ZeroConf for Network discovery =
    1212Automatic synchronization between servers require automatic service discovery. We had two major options to choose from: