[ui-best-practices-working-group] Annotation and XML configuration discu

[Neil Hauge <neil.hauge@xxxxxxxxxx>]

As mentioned on the call earlier today, I would like to discuss a 
current UI direction/best practice issue with the group related to 
annotation and XML configuration.  We have touched on this issue briefly 
in the past, but our project is currently trying to decide what 
direction to pursue and needs to determine the correct direction as soon 
as possible.  Guru has agreed to switch presentation dates with me, so I 
think we have everyone's agreement that we'll do the TPTP Show and Tell 
on Dec 6th, and the Dali/Webtools JPA  S&T on November 22nd.  Let's get 
things started with an email discussion and go from there.

Here is basic problem.  In the WTP-JPA Dali Tools, we need to assist the 
user with configuring the persistence of their object model.  This can 
be a fairly complicated task, especially for large and complex object 
models.  With the introduction of EJB 3.0, users can choose to configure 
persistence via Java source annotations and XML descriptors 
(persistence.xml), or solely by using XML descriptors(orm.xml and 
persistence.xml). It's not really important to understand what the files 
are and what they do, it's only important to understand that there are 2 
different ways to configure the same meta data in different artifacts, 
and this needs to be handled in some way in the UI..  *See enhancement 
request 154781 for more information on the question of how we should 
deal with annotation based configuration in the UI - 
https://bugs.eclipse.org/bugs/show_bug.cgi?id=154781.

So, in our tooling we must support a very similar configuration ability 
in two very different artifacts (Java classes and XML).  In our initial 
approach to this problem, we thought it would be advantageous to the 
user and to us to have a consistent approach to configuring these 
artifacts.  We accomplished this by creating our own Persistence 
Properties View which served as a rich UI that stayed in sync with the 
Java Editor.  We are also using this view with the orm.xml file, 
providing a similar experience in configuring the persistence 
properties, regardless of where they are being configured.  When you are 
editing an annotated Java class, you see the persistence properties for 
that class, and changes you make in the PersistencePropertiesView change 
the state of the annotations in that class file.  When you are editing 
the orm.xml file, you see the persistence properties for that XML 
descriptor, and changes you make in the PersistencePropertiesView change 
the state of the xml content in that xml file.  (As a side note, we also 
plan to support in-Java-source annotation value code completion and 
in-xml-source completion).

What are the high level problems with this approach?  1. We are using 
our own properties view, while the platform already has a generic Tabbed 
Properties View (as of 3.3) 2. We are using a properties view to 
configure an XML descriptor.  A more standard approach would be to have 
an XML editor for editing an XML file (such as the plugin.xml editor).  
So what are the problems with solving those problems?  1. The 
TabbedProperties are not enabled for the Java editor (bug 154781).  It 
also can only have one true contributor (bug 158607), so different 
plugins from different domains would have a hard time using the standard 
TabbedProperties for a generic editor like the Java Editor.  2. As for 
the editor for the orm.xml file, this removes the consistency with the 
"properties" based solution for both artifacts. 

In summary, we have several different options at this point.  We want to 
be integrated with the platform, but this is proving to be difficult 
given the current limitations of TabbedProperties (there are more that I 
haven't mentioned).  We want to be consistent with the platform (have an 
editor for XML files), but this will cause our UI editing experience 
between Java and XML to be somewhat inconsistent.

What I am looking for here is some discussion around what is best for 
Eclipse, our extenders, and our users, given our current situation.  I 
think the decision we make here will likely have an impact on future 
groups who end up in the same position, as annotation usage become more 
and more prevalent.

Thanks for any input,
Neil


Neil Hauge
WTP-Dali JPA Tools Lead
Oracle TopLink Tools