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