Re: [e4-dev] Suggestion to restructure UIEvents to increase clarity and

[David M Williams <david_williams@xxxxxxxxxx>]

Yep, and, as I said, I can see the point
of it. "almost API" just kind of jumped out at me. Is that the
opposite of "internal API" :) 

But, in all seriousness, I was just
asking because I didn't know status of various packages and their API-ness
or how the team defines "provisional API". And now that "4.2
is mainstream" it is good that e4 APIness gets some focus. Maybe it
would be helpful to have a clear statement of "API plans" and
communicate it well, for example, on cross-project list? (And, apologies,
if there already is one, and I'm just not aware of it).  As far as
I know, no one on the release train is writing directly to e4 APIs ...
but ... it is hard to know, and some might be (I know BIRT once mentioned
they planned to ... but, that was from a casual conversation long ago,
and I am not sure of their current plans for Juno). 

For example, a statement such as following
might help establish the right message (rewritten by e4 committers to be
accurate! :)  

"writing to the API compatibility
layer will (continue) to be stable, but until now, the e4 packages have
been provisional API, and might evolve some still during Juno, and then
become API in M5 API freeze. If you write anything directly to APIs in
e4 packages, you should follow xyz list to catch announcements or discuss
issues and make suggestions about e4 packages in Eclipse 4.2". 

And ... I say vaguely "xyz list"
above on purpose ... at what point do "4.2 issues" (about e4
packages/apis) start to be discussed/announced on the regular eclipse-dev
or eclipse-ui-dev lists and e4-dev left for pure "e4 incubator"
discussions?  Its already kind of confusing (to community) where e4
ends and Eclipse 4x begins so I'd think anything in Eclipse 4x (even if
from e4 package) should be treated as mainstream. But ... I know there's
some years long history here I'm not aware of, so not sure what or when
to change list focus. Maybe, if clearer to community, the e4-dev list left
as is, and ask for new e4-incubator-dev list? Then e4-dev list used for
"writing e4 native applications, without the compatibility layer"
or similar. Again, just suggestions from "first impressions"
as I started following this list. 

Thanks, 






From:      
 Eric Moffatt <emoffatt@xxxxxxxxxx>
To:      
 E4 Project developer
mailing list <e4-dev@xxxxxxxxxxx>
Date:      
 09/23/2011 10:17 AM
Subject:    
   Re: [e4-dev]
Suggestion to restructure UIEvents to increase        clarity
       and        performance
Sent by:    
   e4-dev-bounces@xxxxxxxxxxx

---

I hadn't seen this when I wrote my previous reply... I do take the 'API'
issue seriously and even it it's just tacitly API now I realize that breaking
existing e4 users is not good which is why I suggested that this be put
on the mailing list... 

To me this is a 'performance improvement....for the developer subscribing
to events...;-), 
Eric

From:	David M Williams <david_williams@xxxxxxxxxx>
To:	E4 Project developer mailing list <e4-dev@xxxxxxxxxxx>
Date:	09/22/2011 10:46 PM
Subject:	Re: [e4-dev] Suggestion to restructure UIEvents to increase clarity        and        performance
Sent by:	e4-dev-bounces@xxxxxxxxxxx

---

Well ... since you asked for opinions ... doesn't seem worth it to me ...
but, does not seem all that bad to do so, if important to you (that is,
I see your point) ... but, not that bad the way it is (to me). 

The part that caught my attention was "... since this class is essentially
API, if we don't change it now, we will never be able to make the change."
It sure looks like API to me already (not almost API) so ... is it stated
somewhere (and, more important, is it accepted, common knowledge) that
things in e4 packages are not API yet? Seems like it is just good discipline
to assume they are API, if they are "provisional API" ... unless
there is a required technical reason to change it. I suspect the performance
difference would not be measurable (once JIT compiled it) ... but ... if
you have data that shows the performance improvement, that might make it
defensible? 
 
my 2 cents worth 






From:        Dean
Roberts <Dean_Roberts@xxxxxxxxxx> 
To:        e4-dev@xxxxxxxxxxx
Date:        09/22/2011
03:39 PM 
Subject:        [e4-dev]
Suggestion to restructure UIEvents to increase clarity and    
   performance 
Sent by:        e4-dev-bounces@xxxxxxxxxxx

---

While trying to understand UIEvents and how the topics are built up for
subscribe operations I found the buildTopic() methods a little cumbersome
and a barrier to understanding what was really going on.

I would like to make a suggestion that I think would

      1) Make the code look cleaner
      2) Make the concepts clearer 
      3) Improve run time performance (albeit marginally)

For illustration purposes, here is an example of an interface definition
from UIEvents for the UIElement model object generated by GenTopic

      public
static interface
UIElement { 
              public
static final
String TOPIC
= UIModelTopicBase
+ "/ui/UIElement";
//$NON-NLS-1$ 
              public
static final
String ACCESSIBILITYPHRASE
= "accessibilityPhrase";
//$NON-NLS-1$ 
              public
static final
String CONTAINERDATA
= "containerData";
//$NON-NLS-1$ 
              public
static final
String CURSHAREDREF
= "curSharedRef";
//$NON-NLS-1$ 
              public
static final
String ONTOP
= "onTop";
//$NON-NLS-1$ 
              public
static final
String PARENT
= "parent";
//$NON-NLS-1$ 
              public
static final
String RENDERER
= "renderer";
//$NON-NLS-1$ 
              public
static final
String TOBERENDERED
= "toBeRendered";
//$NON-NLS-1$ 
              public
static final
String VISIBLE
= "visible";
//$NON-NLS-1$ 
              public
static final
String VISIBLEWHEN
= "visibleWhen";
//$NON-NLS-1$ 
              public
static final
String WIDGET
= "widget";
//$NON-NLS-1$ 
      } 

To subscribe to an event that tracks a UIElements visible change you would
write 

eventBroker.subscribe(UIEvents.buildTopic(UIEvents.UIElement.TOPIC,
UIEvents.UIElement.VISIBLE),
visibilityHandler);

To subscribe to all changes to UIElement you would write

eventBroker.subscribe(UIEvents.buildTopic(UIEvents.UIElement.TOPIC),
visibilityHandler);

I think it would be much nicer to write, for the first case,

eventBroker.subscribe(UIEvents.UIElement.VISIBLE),
visibilityHandler);

or, for the second case, 

eventBroker.subscribe(UIEvents.UIElement.ALL),
visibilityHandler);

To make this possible I propose that we would generate the UIElement interface
definition like this. 

      public
static interface
UIElement { 
              public
static final
String ALL=
UIModelTopicBase
+ "/ui/UIElement/*";
//$NON-NLS-1$ 
              public
static final
String VISIBLE
= UIModelTopicBase
+ "/ui/UIElement/" +
"visible";
//$NON-NLS-1$ 
              ...
      } 

This would allow us to delete two of the buildTopic() methods.  We
could leave the 3 argument version of buildTopic() to retain construction
of topics that filter based on event type ( although nobody calls this
internally at this time so do we really need it?).

The code would also be more efficient as we would be removing method calls
that do string concatenation with simple static references.  In fact,
I believe the compiler will just in line the references at compile time.

Although I would be a fan of simply making these changes and requiring
consumers to make a few small simplifying changes, we could provide a stepping
stone by regenerating the new shape, deprecating the buildTopic() methods
and all the TOPIC fields.  We would then change the implementation
of the buildTopic methods to return the appropriate constant directly without
concatenating. 

Admittedly there is higher priority work to be done but since this class
is essentially API, if we don't change it now, we will never be able to
make the change.  And I think the clarity in the subscribe statements
make the change worth it.  This change seems to fit well with the
Eclipse 4 mantra that simple things should be simple.  

I also believe the effort required to change GenTopic to generate the new
shape is small, and I volunteer to create the patch.  Admittedly changing
the calling code to use the new shape is more wide spread, but a very simple
task.  Although an actual committer probably wants to do that work
as it would be a LOT of patches to apply :-) 

What does the community think?  Does it make sense?  Am I totally
off base? 

Dean_Roberts@xxxxxxxxxx_______________________________________________
e4-dev mailing list
e4-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/e4-dev
_______________________________________________
e4-dev mailing list
e4-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/e4-dev

_______________________________________________
e4-dev mailing list
e4-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/e4-dev