[Bioperl-l] Re: mutable accessors
hlapp at gmx.net
Sat Jan 10 21:16:59 EST 2004
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
- 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
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).
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
> without creating a new sequence object, and when I told him how to do
> he sent me a copy of the documentation showing that it couldn't be done
> that way :-)
> Cheers all!
> 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
>>> 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
>> is an implementation-specific aspect.
>> the interface should be strict read-only.
>> Bioperl-l mailing list
>> Bioperl-l at portal.open-bio.org
> Mark Wilkinson <markw at illuminae.com>
> Bioperl-l mailing list
> Bioperl-l at portal.open-bio.org
Hilmar Lapp email: lapp at gnf.org
GNF, San Diego, Ca. 92121 phone: +1-858-812-1757
More information about the Bioperl-l