[dev] Api consistency for share listing

[Michael J.Rubinsky]

Quoting Jan Schneider <jan at horde.org>:

> Zitat von "Michael J.Rubinsky" <mrubinsk at horde.org>:
>
>>
>> Quoting Jan Schneider <jan at horde.org>:
>>
>>> Zitat von "Michael J.Rubinsky" <mrubinsk at horde.org>:
>>>
>>>>
>>>> Quoting Jan Schneider <jan at horde.org>:
>>>>
>>>>> Zitat von "Michael J.Rubinsky" <mrubinsk at horde.org>:
>>>>>
>>>>>>
>>>>>> Quoting Jan Schneider <jan at horde.org>:
>>>>>>
>>>>>>> Zitat von "Michael J.Rubinsky" <mrubinsk at horde.org>:
>>>>>>>
>>>>>>>>
>>>>>>>> Quoting Alfonso Marín Marín <almarin at um.es>:
>>>>>>>>
>>>>>>>>> Hello,
>>>>>>>>>
>>>>>>>>> Cheking module APIs, i have noticed that listCalendars in  
>>>>>>>>> kronolith return an array of ID's, but listTasklists in nag  
>>>>>>>>> and listNotepads in mnemo return the datatree objects  
>>>>>>>>> instead the ID's.
>>>>>>>>>
>>>>>>>>> ¿Is it any reason to do that? I think all of then should  
>>>>>>>>> behave like listCalendars
>>>>>>>>
>>>>>>>> Agreed. Can you create a ticket on bugs.horde.org so it  
>>>>>>>> doesn't get forgotten about?
>>>>>>>
>>>>>>> We should probably have both: a generic listShares() method in  
>>>>>>> all apps that support shares, and (still consistent)  
>>>>>>> listCalendars/Tasklists/Etc() methods for the specific  
>>>>>>> applications.
>>>>>>
>>>>>> What would the difference(s) be between these two? If it is  
>>>>>> that one method returns the actual share object, is that  
>>>>>> something we really want to do via the API? Having an  
>>>>>> application-level object be returned via the API doesn't make  
>>>>>> much sense to me.  Alternatively, if we want the information  
>>>>>> available in the share object, we could return some sort of  
>>>>>> array/hash/json/whatever representation of the object  
>>>>>> properties, not the object itself.
>>>>>>
>>>>>> Or, are you just suggesting that we have a listShares() method  
>>>>>> that is just an alias of list[Calendars|Tasklist]()?
>>>>>
>>>>> No, I indeed want listShares() to return the shares. It doesn't  
>>>>> matter if they contain application-specific information,
>>>>
>>>> It's not so much the information I'm concerned about, but the  
>>>> fact that some of the methods may rely on the application being  
>>>> active/pushed on the top of the registry stack.
>>>
>>> Just like any API call, or what do you mean?
>>
>> Yes, the application is on the stack *during* the listShares()  
>> call, but in the client code, you now have a collection of, e.g.  
>> Ansel_Gallery objects. Calling methods on those objects from client  
>> code could potentially be problematic.
>
> That's a good point, though in practice I don't think this is going  
> to be a problem. We can only use the general share API anyway, and  
> those methods shouldn't have any application-dependent stuff in it.

Why not? That might be _mostly_ true, but applications can (and do)  
extend the Horde_Share_Object class. Ansel, for instance has numerous  
places where it needs application level objects in the Ansel_Gallery  
object. Setting property values and saving the share object are two  
examples of places this happens.  Using composition instead of  
inheritance in Ansel_Gallery might solve this particular instance, but  
causes all kinds of other problems since (among other things) it's  
much more efficient (and may even be necessary) to both have access to  
the Share_Object's protected properties/methods and be able to  
override them.

In a more general sense, IMO, I think it's asking for trouble to make  
any application level object with callable methods available via the  
API. *We* may know what is and is not ok to call on any particular  
object, but for other developers consuming our API, I would think we  
would want a "if it's available, it's usable" mindset. Not to mention  
the fact that none of these methods would work if the object is  
obtained via RPC. One idea is to maybe protect the methods that return  
objects somewhat by putting them in Application.php in stead of  
Api.php. This doesn't solve the application scope issue, but at least  
makes the actual Api a bit more consistent/understandable for other  
devs.



> Actually I already use Nag shares in Kronolith all the time without  
> any problems.

Yea, though Nag doesn't extend the Horde_Share_Object at all...


--mike

The Horde Project
http://www.horde.org