Some features of JBoss Tools have XModel for their internal model. This model framework was created 8 years but remains undocumented.
It is time to fill the gap with some notes to be of use to those who might fix issues in or contribute to XModel based features.
Basics for XModel is in plugin org.jboss.tools.common.model. Basic ui components that visualize objects of XModel are in org.jboss.tools.common.model.ui.
The idea of XModel is that one can minimize Java coding by describing any model object by meta information about its structure and actions that can be done on it and bind this meta info with common implementation, which can be customised but in many cases is good by default.
That info is xml (*.meta) file registered with XModel by extension point 'org.jboss.tools.common.model.meta'.
All objects in XModel have common super interface XModelObject, and even common super class XModelObjectImpl. But of course, for the sake of
customization there are opportunities to override the default implementation.
For the start, look into *.meta files and make sure that it contains only a few basic notions. But there are some tricks that make it difficult to understand without explanations. Just several, for the beginning:
1) Entity name convention.
There are no packages and all entity names must be unique.
It is solved by common prefix for a set of entities for a project. For
example, all entities for Seam start with 'Seam'. With one exception: root
entity of file usually starts with 'File', so root entity for components.xml
starts with 'FileSeam'. That is not the requirement, but it is conveniency,
which one can use within a project to filter/find entities by prefix.
Version is provided by digital suffix, otherwize digits are not welcome in
entity name, e.g. entities 'FileSeamComponent12', 'FileSeamComponent20' etc.
are for versions 1.2, 2.0, etc. I regularly use code that assumes such
suffixing to compute version (it is limited to a project, common features do
not make such assumptions).
2). What is "%Regular%" in the next fragment?
<XModelEntity ImplementingClass="%Regular%" name="EclipseWorkspace">
It is quite evident that 'ImplementingClass' is a java class for XModel
object that implements XModelObject (actually even always extends
XModelObjectImpl). There are a few standard implementations and I decided
that it would not do always to type qualified name. So, there is an idea of
simple mappings with predefined names. Most of them are introduced in
org.jboss.tools.common.model/resources/meta/base.meta
and contributed where needed (kind of trivial extension point, invented when
there were no Eclipse around). In this case it is
<MAPPING name="Implementations">
<PAIR name="Regular"
value="org.jboss.tools.common.model.impl.RegularObjectImpl"/>
</MAPPING>
So, loader of *.meta files looks for either qualified class names or %...%
expressions, and for 'ImplementingClass' attribute looks into mapping
'Implementations'.
3) What are PROPERTIES in the next fragment?
<XModelAttribute PROPERTIES="id=true;category=general"
name="component-name" xmlname="name"/>
Actually, this is the most gross trick in XModel. As I told above, there are
but few basic notions in it, but one may without limitation add any set of
them by PROPERTIES attribute.
Being fully aware of the danger of such approach, I introduced new property
names only when quite necessary and useful.
- Property 'id' is used by implentation class
org.jboss.tools.common.model.impl.CustomizedObjectImpl, usually referenced
%Custom%. It marks attribute as the one which value must be unique in
parent, and by default that value is used for object's path part and
presentation (e.g. label in Tree)
- Property 'category' with two values 'general' and 'advanced' is used to
automatically generate ui editor forms if no specific form is defined. If
category=advanced, field editor for the attribute is added to Section
'Advanced', if 'category' is not set, it will not be present in ui form at
all.
4) What is <XModelAttributeReference>?
<XModelEntity name="SeamJmsQueueConnection"
...
<XModelAttributeReference
attributes="class,scope,precedence,installed,auto-create"
entity="SeamComponent" name="component"/>
...
</XModelEntity>
Entities SeamComponent and SeamJmsQueueConnection have a lot in common, meta
information for attributes 'class', 'scope', etc. can be inherited by the
later from the former.
The meta model inheritance in XModel is rather trivial, I admit it, but
improving it is next to impossible because of potentially huge refactoring
that it might involve (I am afraid that similar consideration will loom in
the way of many a sensible suggestions for XModel improvements).