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).

XModel and type safety problem

1. In configuration meta files, one can bind entity with any implementation (extending XModelObject). XModelObject will be created with that implementation. Then, if it is necessary to work with implementing type, casting must be performed. That is not type safe operation.

2. If developer works with a large project that contains several modules, he can carelessly make use in *.meta file of one module features defined in other modules. Then, if one of these modules is not included into build for product, then build will pass but will not work.

These two and other related problems are due to lack of validation for XModel. They can be solved by adding new builder/validator for *.meta files and contribution to Java builder that would check casting types. The lack of validation is currently the greate drawback of XModel that hinders developers from using it.