[livesupport-dev] File Storage RFC
  • ----java_obsysa1727095457
    Content-Type: text/plain
    Content-Disposition: inline
    Content-Transfer-Encoding: 8bit

    Hi,
    for synchronization of development I send a "File Storage RFC"
    with brief explanation of storing metadata and quick API overview.
    I hope it reflects specifications sent by Akos.

    Comments are welcome

    --
    Tomas Hlava
    th@red2head.com

    P.S. my response may delay next week due to problematic connection ...


    ----java_obsysa1727095457
    Content-type: message/external-body; access-type=URL; URL=http://sympa.mdlf.org/sympa-bin/wwsympa.fcgi/attach/livesupport-dev/elmo109061432745192100888680@dell/gbrfc_html; name="gbrfc_html"; size="10001"

    Content-type: text/html
    Content-Transfer-Encoding: 8bit

    ----java_obsysa1727095457--

    ------------------------------------------
    Posted to Phorum via PhorumMail
  • 2 Comments sorted by
  • Tomas,

    > for synchronization of development I send a "File Storage RFC"
    > with brief explanation of storing metadata and quick API overview.
    > I hope it reflects specifications sent by Akos.

    thanks for the document.

    first a general remark on the XML-RPC function call parameters. I think
    that the way XML-RPC handles parameters, e.g. they are not named, nor
    typed, but you rely on their sequence, is quite error prone. Therefore
    I'd push for a pattern in which we would basically send only one
    parameter, which is an XML-RPC structure. As structures are nested
    associative arrays basically in XML-RPC, this would allow us to bind
    parameter values to names.

    The reasoning behind this would be to accomodate future channges in our
    parameter lists for our XML-RPC functions. Consider the case when we
    would have a functions:

    xmlRpcFunction( param1, param2);

    (let's use the notations params[0] = param1, params[1] = param2, etc.)

    but we find out, that actually param1 is not enough for it's purpose, so
    a param1.1 is also needed. With the sequencing-only method, if we do:

    xmlRpcFunction( param1, param1.1, param2);

    then we break the implementation that relied on params[1] = param2. If
    we do:

    xmlRpcFunction( param1, param2, param1.1);

    then it's quite counter-intuitive, as param1 and param1.1 are closely
    related, by they appear quite apart.

    If we would only send a structure, we could use it's association feature:

    xmlRpcFunction( {param1 = param1, param2 = param2} );

    and you'd have params[0]['param1'] = param1, params[0]['param2'] =
    param2. extending the parameter list would lead to:

    xmlRpcFunction( {param1 = param1, param1.1 = param1.1, param2 = param2} );

    and it would still hold, that params[0]['param1'] = param1,
    params[0]['param2'] = param2, while the new parameter would be
    params[0]['param1.1] = param1.1, also quite straightforward.


    What is your opinion on the matter?


    With respect to the proposed API, I see the pattern that a $sessionid is
    passed to all functions requiring authentication. I think this is a good
    solution.

    (As a sidenote, if we used my pattern proposed above, it could always be
    params[0]['sessionid'], and would make programing easier. Whereas now,
    it's always a parameter at a different index.)

    Some specific remarks:


    > XMLRPC API for local storage
    >
    > * |login(/*string*/ $login, /*string*/ $pass)| returns string
    > returns auth token or error
    > * |logout(/*string*/ $sessid)| returns boolean
    > * |authenticate(/*string*/ $login, /*string*/ $pass)| returns boolean
    > basic authentication check
    > * |existsAudioClip(/*string*/ $gunid)| returns boolean
    > Check if an Audio clip with the specified id is stored in local storage.

    this call might be missing the sessionid parameter?

    > * |storeAudioClip(/*string*/ $gunid, /*string*/ $mediaFileLP, /*string*/
    > $mdataFileLP, /*string*/ $sessid)| returns gunid
    > Store a new audio clip or replace an existing one.

    ...

    > * |updateAudioClipMetadata(/*string*/ $gunid, /*string*/
    $newMetaData,
    > /*string*/ $sessid)| returns boolean
    > Update the metadata of an Audio clip stored in Local storage.


    why the different parameter formats for metadata for these two
    functions? (mdataFileLP vs. newMetaData?) Also, I'd make AudioClip an
    XML-RPC stucture, and put that in the parameter list. That would contain
    the metadata, reference to the raw audio, and all other stuff that will
    be in there.

    > * |deleteAudioClip(/*string*/ $gunid, /*string*/ $sessid)| returns boolean
    > Delete an existing Audio clip.
    > * |accessRawAudioData(/*string*/ $gunid, /*string*/ $sessid)| returns string
    > Get access to raw audio data of an AudioClip.
    > * |releaseRawAudioData(/*string*/ $gunid, /*string*/ $sessid)| returns boolean
    > Release access for raw audio data.

    here, I would not have gunid as a parameter, but the exact value
    instead, that was returned bt accessRawAudioData. this way the function
    could identify exaclty which accessRawAudioData call is being matched by
    this releaseRawAudioData function.

    > * |searchMetadata(/*string*/ $criteria, /*string*/ $sessid)| returns array
    > Search through the metadata of stored AudioClips, and return all matching
    > clip ids.
    >
    > Methods may return XMLRPC error response if fails ...
    >
    > Common parameters:
    >
    > |$sessid| - session id (token returned by login method)
    > |$gunid| - global unique id of file
    >
    >
    > XMLRPC API of interface to central archive
    >
    > * |downloadRawAudioData(/*string*/ $gunid, /*int*/ $offset, /*string*/
    > $sessid)| returns boolean
    > * |searchMetadata(/*string*/ $criteria, /*string*/ $sessid)| returns array
    > Search through the metadata of stored AudioClips, and return all matching
    > clip ids.

    and what about the store and update functions? why I'm asking is that
    the parameter type there (medaFileLP) suggests that this would be some
    pointer (or what does LP stand for?). But in case of the media archive,
    there is no chance the client showing pointers - it has to upload all
    binary data with the XML-RPC request itself.



    Akos

    ------------------------------------------
    Posted to Phorum via PhorumMail
  • Hi from palmtop,

    ad XMLRPC parameters: very good idea - I will use structure as
    one parameter.

    ad missing sessid param in existsAudioClip: yes - I missed it there Smile

    ad mdataFileLP vs. newMetaData: it's the same parameter - different names
    are only for mnemotechnic reason (not important - I could use same
    names)

    ad releaseRawAudioData: yes - I's better to identify released object by path
    returned by accesssRawAudioData instead of gunid.

    ad store and update functions for central archive:
    This part Is not clear to me yet - I think about method for upload from
    local storage to central - using files previously saved and not sending it
    with this call.
    If You have any idea related to this, it will help me.
    (BTW LP in mdataFIleLP means "Local Path")

    thank for comments

    Tomas

    ------------------------------------------
    Posted to Phorum via PhorumMail