Sweet Project
XSWT Requirements and Design

Acknowledgements

Nobody can create something optimally and elegantly without "standing on the shoulders of giants". The following people participated in the initial discussion of XSWT in bug #38109 on Eclipse Bugzilla and have each made substantial contributions toward the XSWT effort. They are listed here in the order in which they contributed to the bug report. (If I missed anyone, please email and I'll be glad to add you to the list):

Chris McLaren <chris_mclaren@ca.ibm.com>
Bob Foster <bob@objfac.com>
Joe Winchester <winchest@uk.ibm.com>
Daniele Gariboldi <gardian@libero.it>
Konstantin Scheglov <scheglov_ke@nlmk.ru>
Ed Burnette <ed.burnette@sas.com>
Andrew Fawcett <andrew.fawcett@coda.com>

All additional feedback and constructive criticism is welcomed and will be acknowledged along with all of the above contributors.

What is XSWT?

The name XSWT was coined by Chris McLaren of IBM to describe his design and implementation of an XML-based markup language for describing SWT layouts.

XSWT Requirements

In the process of proposing, describing, and discussing XSWT, the following requirements have emerged as desirable:

• Design XSWT to be maximally human and machine-readable/writable

• Keep the XML markup portion of XSWT as thin as possible. This requires some form of one-to-one mapping between XSWT markup elements and SWT classes / properties / style bits, etc.

• Provide an XSWT rendering engine that is as simple and lightweight as possible. This engine should be easy to embed inside an application.

• Maintain compatibility with Sweet metadata for describing new SWT controls.

• Facilitate machine-generation of XSWT from GUI builders, etc.

• Enable event handlers to be set on SWT objects as simply as possible.

• Return a simple data structure representing the SWT layout for the purpose of dynamically registering and unregistering event handlers from client code.

Just as importantly, XSWT does not try to do any of the following:

• Implement XUL.
• Implement XMLForms.
• Implement anything higher-level than SWT and JFace native constructs.

The intent is that for those who desire it, XSWT can be generated via XML transformations from XUL, XMLForms, etc.

This document will discuss various design choices affecting how the above characteristics could be implemented. It will also justify and describe the approach that will be adopted by Sweet.

Design Choices

XSWT has three basic decisions to make affecting the outcome of the above requirements.

1. Should the XML format itself be generic and keep all meaningful data inside the attribute values? This would mean that all of the SWT-specific "smarts" would be inside the XSWT rendering engine and none of it could be in some XML schema describing XSWT. Alternatively, should each tag correspond directly to some SWT or JFace construct similar to the original XSWT implementation?
2. Should XSWT's SWT control metadata be described as Sweet BeanInfo classes, as XML schemas, or both?
3. Should the XSWT engine attempt to automatically register event handlers using reflection on a target class or provide a manual method for registering and unregistering event handlers?

In the remainder of this document, we will answer these questions.

Generic XML versus SWT-specific Tags

This first question hits at the core of all the other XSWT design choices. It is both a philisophical question and a pragmatic one: Should the XML file format "know" about SWT or should that be a function of the XSWT rendering engine? In other words, which of the following examples describes what XSWT should be the best?

Snippet A: Original XSWT Design

<composite>
   <layoutData grabExcessHorizontalSpace="true" 
      grabExcessVerticalSpace="true" 
      horizontalAlignment="FILL" 
      verticalAlignment="FILL"/>
   <layout class="gridLayout"
      marginHeight="0" 
      marginWidth="0"/>
   <children>
      <label text="Java Editor Settings:"/>
         ....
   </children>
</composite>
	      

Snippet B: Generic XML Format

<object class="composite">
   <prop name="layoutData">
      <object class="GridData">
         <field name="grabExcessHorizontalSpace" value="true"/>
         <field name="grabExcessVerticalSpace" value="true"/>
         <field name="horizontalAlignment" value="FILL"/>
         <field name="verticalAlignment" value="FILL"/>
      </object>
   </prop>
   <object class="Label" style="SWT.NULL">
      <prop name="text" value="Java Editor Settings:"/>
   </object>
      ....
</object>
	      

The following table lists advantages and disadvantages of the design represented by Snippet A versus the design represented by Snippet B:

On balance, it appears that the original XSWT design, represented by Snippet A, is the better design. Although it will be more challenging to create a generic rendering engine for that format, the format permits its SWT metadata to be easily described by an XML schema. The result is that it will be much easier to use XML editors like XMLBuddy to edit XSWT represented by Snippet A than by Snippet B. The overall result is that the original XSWT design will be much easier for humans to work with than the alternative.

Using BeanInfo, Schemas, or Both

Now that we have determined that we want to keep the current XSWT design as much as possible, we ask, "Do we want to describe SWT component metadata to XSWT as Sweet-style BeanInfo classes, XML Schemas, or possibly both?" In asking this question, the crucial issue is, "Are there use-cases supporting use of BeanInfo, and/or XML Schemas?" Let's look at each in turn:

Is Sweet BeanInfo Useful With XSWT?

The current XSWT rendering engine hard-codes the translation between XSWT tags and SWT objects/properties/fields. A production implementation would need a generic way to map from a XSWT tag or attribute to the appropriate object class and/or field. In this case, BeanInfo classes along with a healthy dose of reflection appear to be the most convenient tool for the job.

Therefore, we conclude that XSWT most likely needs to depend on BeanInfo classes possibly with Sweet extensions.

Are XML Schemas useful as XSWT Metadata?

When editing an XSWT file by hand, it may be useful to use an XML editor like XMLBuddy. Providing XMLBuddy with an XML Schema describing all of the SWT metadata will enable XMLBuddy to provide content-assist features specific to SWT classes. This is clearly a useful thing to have.

Therefore, we also conclude that XSWT will benefit from describing its SWT metadata as XML Schemas.

Reconciling BeanInfo with XML Schemas

Since it appears that there are solid use-cases supporting both BeanInfo and XML Schemas being used as SWT metadata for XSWT, I propose that a tool be created that can generate one given the other. It should be possible, for example, to generate a correct XML Schema for XSWT given a Sweet-style BeanInfo class. The reverse is also possible, but would be more challenging to implement optimally.

Therefore, XSWT will provide a translation tool for generating XSWT XML schemas given a Sweet BeanInfo class and for generating BeanInfo source code given an XSWT XML schema.

Automatic, Manual, or Automatic and Manual Event Registration

Once the XSWT renderer engine has created an XSWT layout from an XSWT file, an application developer will want to process events generated by the SWT controls in that layout. Two mechanisms have been discussed for doing this:

1. Returning a map (String -> SWT object) so that application code can look up objects in the SWT layout and attach or detach event handlers.
2. Using reflection to automatically attach event handlers to methods that are named according to JavaBeans event handler naming conventions. To quote from Ed Burnette:

   Why not let event handlers be discovered by reflection, similar to the way JUnit finds tests? If the goal is developer productivity, then if the tool can figure something out, it should! So to use your example,

     <button id="mybutton" style="CHECK" text="Add..." >
       <gridData horizontalSpan="2"/>
     </button>
   

   then in the code:

   mybuttonSelectionListener(...) {
      ...
   }
   

   If there is no handler for something then the system could warn about it if it's important but should continue to run anyway (to help rapid prototyping and UIDD - User Interface Directed Development).

It seems apparent that both methods of event management will be useful in different contexts. For example, Ed's idea for using reflection will be useful for quickly assigning static event handlers. However, explicitly adding and removing event handlers will be necessary in situations where the event handler can change dynamically.

Therefore, it appears that the XSWT rendering engine will benefit from supporting both methods event management.

XSWT Deliverables

Based upon all of the above, the following XSWT deliverables are proposed:

1. An XSWT markup language that is consistent with Chris McLaren's original design, differing only in respects necessary to make it easily generated by machine in addition being machine-readable.

2. An XSWT rendering engine that uses Sweet BeanInfo metadata and/or reflection to construct a SWT layout from an XSWT layout description file.

   This rendering engine should return a map data structure containing the SWT controls it created similar to the current XSWT implementation. In addition, it should provide a mode whereby it will attempt to use reflection to automatically attach events to event handlers as described above.

3. A translator to generate an XML schema suitable for use with XSWT for a SWT control given it's Sweet BeanInfo class.

4. A translator to generate a Sweet BeanInfo class (by convention, extending OverrideComponentInfo) given an XSWT XML schema for some SWT control.