Rendering

The rendering stage of provisioning is driven by application of Velocity Templates. However, in some cases, there may be additional processing applied to the resulting text:

· Merge processing.  This processing stage merges generated content with existing target artifact content, subject to various merge control options specified in the generated content.

· Formatting.  Depending upon content type, eclipse content formatting utilities will be applied to the result.

· Conditional commit.  If the result is the same as the existing target artifact content, no output will occur.  This will preserve file time-stamp for unaltered target artifacts, enabling expected behavior for incremental project builds and repository updates.

· Post processing actions.  Depending upon content/file type, actions may be invoked to process the result, such as construction of an eclipse project in the workspace when a “.project” file is rendered.

Merge Processing

The following forms of merge processing are implemented:

· Java merge

· model merge

Java merge

A specialized generation mechanism provides for user override of generated java code.

• The underlying technology is named “JMerge”, an open source technology developed by and used by Eclipse/EMF.
• With respect to modelPro, JMerge is used to implement a rule-based merge of generated java code (termed “Source” in following discussion) and user-modifiable java code in the target artifact directories (termed “Target” in following discussion).
• The rules established are focused on variations of EMF java method generation; including:

• @unmodifiable, enforces inclusion of generated methods into target java artifact.
• @generated, enforces inclusion of generated methods into target java artifacts, but enables user to turn off @generated flag and override the method body.
• @modifiable,  enables fine-grained user override of method body statements within a designated user-code block.
• User may add his own methods as required.
• In addition to method body, similar constraints apply to the method’s javadoc comment block.

• Since this is a significant change to the generation process, a convention is adopted for the template-specified @projectPath:

• An @projectPath ending with “.java” will behave as before, namely no “override” logic is implemented and the result will be as generated.
• An @projectPath ending with “.java.or” will invoke the override machinery with a result placed at the location specified in @projectPath, less the “.or” pseudo-extension.

• It should be noted that the underlying technology may cause unanticipated results under some circumstances.   In particular, this may happen when either generation or user modifications result in significant java syntax errors.  Please report any other unexpected behavior so that adjustments to rule specifications and/or user advisories may be adjusted.
• This approach to “override” is applicable to java only, it cannot be applied to any other type of target artifact.

The implementation utilizes tag values in the javadoc comment block preceding a method, plus blocks demarcated by specific string patterns.  The following tags are currently defined:

• @unmodifiable
• @modifiable
• @generated

Within a method body, the following pattern is used:

Within a javadoc comment, the following pattern is used:

Example:

Assume following code is generated initially (for new Target)

Assume user modifies above so that he sees:

Result of re-running ModelPro would be:

Additional variations:

User removes tags, producing following in target:

Regeneration via ModelPro produces:

Model merge

A specialized generation mechanism provides for fine-grained user override of model-backed target artifacts.

• This mechanism applies to target artifacts which are underpinned by an EMF model, such as xsd or wsdl.
• The mechanism is a merge of generated model artifacts (termed “Source” in following discussion) and user-modifiable model artifacts in the target artifact directories (termed “Target” in following discussion).
• The established rules are focused on variations of model element generation; including:

• @unmodifiable, enforces inclusion of generated model elements into target model artifact.
• @generated, enforces inclusion of generated model elements into target model artifacts, but enables user to turn off @generated flag and override the model element.
• @modifiable, explicitly allows user override of model element.
• User may add his own model elements, subject to above constraints.

• Since this is a significant change to the generation process, a convention is adopted for the template-specified @projectPath:

• An @projectPath not ending with “.or” will behave as before, namely no “override” logic is implemented and the result will be as generated.
• An @projectPath ending with “.or” will invoke the override machinery with a result placed at the location specified in @projectPath, less the “.or” pseudo-extension.

• It should be noted that the underlying technology may cause unanticipated results under some circumstances.   In particular, this may happen when either generation or user modifications result in significant syntax errors within the serialized model artifact.  Please report any other unexpected behavior so that adjustments to rule specifications and/or user advisories may be adjusted.
• This approach to “override” is applicable to model-backed artifacts only, it can not be applied to any other type of target artifact.   Furthermore, specializations may be required for each meta-model to accommodate element matching logic and/or specification of tags.  Initial specializations are for xsd, wsdl.

The implementation utilizes tag values associated with a model element.  The mechanism for associating tags with model elements depends on the serialization form for the target artifacts plus any underlying model constraints.  The following tags are currently used:

• @unmodifiable .   If this tag is associated with a source model element, the corresponding target model element can not be overridden by user; it is always generated.
• @modifiable.   If this tag is associated with a source model element, one of the following rules are applicable, depending upon the value:

• “”  (empty string).  If the corresponding target model element exists, the target model element overrides the generated model element.
• “name1;name2;…”   (a semicolon delimited set of names).  Indicates that the source model element overrides the target model elements except for the named attributes.   The named attributes, if present in the target, will override the generated source values.

• @generated.   If this tag is associated with a source model element, then the corresponding target model element is generated unless the tag is removed from the target.  If the tag is removed from the target, then the target model element overrides the generated model element.

The default behavior for override in absence of tags is that source model elements override “matching” target model elements.  Target model elements which do not appear in source will be included in resulting target.   A “match” determination is model-specific.

For xsd and wsdl, tags are specified as attributes on the serialized document element.  The namespace for these override attributes  is http://modelDriven.org/schema/modelPro/override”.   Thus a xsd/wsdl document may have the form:

Example:

Assume following is generated initially (for new Target xsd)

Assume user modifies above so that he sees: