[Bioperl-l] Re: mutable accessors

[Hilmar Lapp]

This is a known issue in bioperl. Everybody who is willing to help 
amend this situation is more than welcome. The problem arises from two 
facts, both of which you have noticed:

	- interfaces in bioperl traditionally do not mandate write access, and 
historically only the read access (i.e., only the mandated part) has 
been documented
	- implementors simply copy&pasted documentation from the interfaces

As we've learned meanwhile, the combination of the two gave rise to a 
significant hurdle and source of frustration for newcomers, and as it 
turns out even for old-time users ;)

While the lacking piece of documentation (and hence required guesswork) 
is fairly straightforward for scalar properties, the problem is 
aggravated for array properties first by the fact that two different 
methods need to be used to modify the property (add_XXXX(), and 
remove_XXXXs()) whose existence would have to be guessed by someone who 
only reads the interface POD, and second by the existence of different 
naming conventions for those two mutator methods.

No-one on the core is proud of this situation, and I understand that 
this can raise serious frustration for a well-intentioned user. Fixing 
this, OTOH, is a serious amount of work, that I'm afraid will not get 
addressed soon enough if everybody just waits for the core people to 
step up. This is an opportunity for one or more people out there to 
enter the hall of bioperl fame in the minds of legions of new users to 
come, or those already frustrated.

Among the suggestions to mitigate the problem are:-

	a) The interface PODs don't change, but every implementor carefully 
documents how to modify a property, instead of just dumb copy&pasting

	The problem with this is that there are supposedly more 
implementations than interfaces, a user will always have to consult 
(and hence know) the implementations in addition to the interfaces, and 
the fundamental problem will have to solved every single time an 
implementation is created (with the continued risk that an implementor 
forgets to do this)

	
	b) The way we define interfaces changes fundamentally to include and 
document mutators, but mandate only read-access from implementations.

	The benefit is that the problem would be solved once and for all, even 
if there was a forgetful implementor. Also, implementors may still 
copy&paste documentation and would just need to remove the line that 
says that this is not mandated (or alternatively, change it to say that 
write-access is expressly supported).

	The problem with this is how would a read-only implementation signal 
that it doesn't support mutability. Obviously, it should do so in a 
standard manner so that client code can be prepared for it.

	Options are to throw a Not-Supported exception, or to ignore the 
modification silently, or to have a standard property that controls 
whether unsupported write-access throws an exception or is ignored, 
much like $obj->verbose(2) which turns warnings into exceptions.

	Another option is to introduce change handlers which may throw an 
exception if a certain modification is not supported. The advantage of 
that would be that anybody can turn any read/write implementation into 
a read-only one by just substituting the change handler to one that 
disallows any change.

AFAIR biojava a whole while ago faced a very similar problem. I believe 
they solved it by including mutators on all interfaces, and have 
implementations generate change events for which listeners can 
register. A change listener, if any is registered, may veto any change 
or only specific ones by throwing an exception. Mat, Thomas, am I 
representing this at least remotely correct? How has this worked out 
over time?

I strongly favor b) (all interfaces document mutators, but don't 
mandate support of mutability). I don't have a strong opinion on how 
read-only status of properties should be signaled, but the change event 
with listeners at least sounds very sensible (in the majority of cases 
there won't be an event handler registered, and hence the performance 
impact would be negligible for standard read/write use cases).

	-hilmar

On Saturday, January 10, 2004, at 01:48  PM, Mark Wilkinson wrote:

> cool.  Will do.
>
> This came up only because one of my colleagues at the university here
> called on me with frustration that he wasn't able to change the 
> alphabet
> without creating a new sequence object, and when I told him how to do 
> it
> he sent me a copy of the documentation showing that it couldn't be done
> that way :-)
>
> Cheers all!
>
> M
>
> On Sat, 2004-01-10 at 15:33, Ewan Birney wrote:
>> On Sat, 10 Jan 2004, Mark Wilkinson wrote:
>>
>>> But... surely the documentation for the modules that DO implement it
>>> this way should reflect that... or?  As it stands, all implementers 
>>> have
>>> simply copy/pasted the documentation from the interface module, even
>>> though their implementation adds this functionality.
>>>
>>
>> Feel free to update the implementations, putting a break to show that 
>> this
>> is an implementation-specific aspect.
>>
>> the interface should be strict read-only.
>>
>>
>> _______________________________________________
>> Bioperl-l mailing list
>> Bioperl-l at portal.open-bio.org
>> http://portal.open-bio.org/mailman/listinfo/bioperl-l
> -- 
> Mark Wilkinson <markw at illuminae.com>
> Illuminae
>
> _______________________________________________
> Bioperl-l mailing list
> Bioperl-l at portal.open-bio.org
> http://portal.open-bio.org/mailman/listinfo/bioperl-l
>
>
-- 
-------------------------------------------------------------
Hilmar Lapp                            email: lapp at gnf.org
GNF, San Diego, Ca. 92121              phone: +1-858-812-1757
-------------------------------------------------------------