Re: [handly-dev] Choice of interface detail and parameter types

[Vladimir Piskarev <pisv@xxxxx>]

Hi Vlad,

I'm very glad that this list is becoming active, at last!
You're making excellent points that deeply resonate with
the intent and thinking behind Handly. I'd like to thank you
again for coming!

Now let's return to the issues at hand :-)

I didn't see much value in IParent and IOpenable precisely
because IMO clients rarely if ever need to know if something
**is a** IParent or IOpenable.

In Handly, every model element is 'IParent', and 'IOpenable' is
an implementation detail (as you noted). Just for clarification,
it would be wrong to test for 'IOpenable' with "x.peekAtBody()!=null",
the notion of openable is largely incorporated in Handle#getOpenableParent()
 (by default handles simply return their parent; source constructs
always return their source file).

I still prefer arrays in Handly API methods for the following reasons:

* Consistency with Eclipse Platform APIs (the first and foremost reason).
  Especially Platform Resources API that Handly essentialy provides
  a mapping onto

* Arrays.asList can provide a high-performance "collection view" on the array
  when such a view is necessary

* Clients rarely if ever need to modify the returned values that are currently
  represented by arrays in Handly APIs. Were they not the arrays, they would
  become Iterables (like in Xtext APIs, for example). But an Iterable can't
  readily provide its length. And for those cases when you do need an Iterable,
  see the point above :-)

* Even though I retain certain open-mindedness regarding whether or not arrays
  should be used in Handly API methods, I really think it is a good idea
  to use them in the implementation for reasons of scalability. Please see
  the Body implementation for an example -- in this case, the array gives
  smaller memory footprint and allows to avoid locking (a volatile field
  is sufficient).

* We have had no complaints so far from our big adopter.
  Okay, maybe they are just shy, we work in the same company :-)

* I'm old school. And not especially partial to generics.
  Okay, let's not count this one ;-)

Having said that, I think we should investigate it further and come up with
a final verdict within 0.3 time frame.

A compromise would be to have methods like getChildrenIterable, but it
doesn't scale well IMO (for example, IHandleDelta currently has 6 methods
returning arrays).

And of course, a specific model built on top of Handly can provide its own
API in the style it sees fit. In a sense, Handly API is meant first and
foremost for generic infrastructure components built on top of it, it was
never meant to be **the** client API, as each model can (and should)
define its own rich API on top.

Perhaps our esteemed mentors from the Eclipse Architecture Council
would weigh with their infinite wisdom! I could not find anything
in the Eclipsepedia regarding arrays in API methods.

Warm regards,
Vladimir