Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "JWT Metamodel Extension"

(Setting up simple (key-value) additional model extensions)
 
(45 intermediate revisions by one other user not shown)
Line 1: Line 1:
 
 
== What are aspect model extensions for ==
 
== What are aspect model extensions for ==
JWT provides a mechanism allowing to store typed custom information in workflow models (actually, it works for any kind of EMF model). Profiles describe what kind of additional information (or Aspects) can be stored on model elements. They can be provided by JWT integrators to let their users provide complex information needed by their custom features, or designed by end users to let them add information as simple as key-value properties.
+
JWT provides a mechanism allowing to store typed custom information in workflow models, thanks to an additional *_conf file (actually, it works for any kind of EMF model). Profiles describe what kind of additional information (or Aspects) can be stored on model elements. Such profiles and aspects can be provided by JWT integrators to let their users provide complex information needed by their custom features, or designed by end users to let them add information as simple as key-value properties.
  
  
Line 7: Line 6:
  
 
=== Installation ===
 
=== Installation ===
Aspect model extensions should be available by default in your JWT installation starting from 0.6 (upcoming).
+
Aspect model extensions are available by default in your JWT installation starting from JWT 0.6.
  
 
If they are not, here are the additional JWT eclipse plugins you need in your JWT installation (or workspace) :
 
If they are not, here are the additional JWT eclipse plugins you need in your JWT installation (or workspace) :
 
* jwt-we obviously as well as jwt-we-conf.we, which contains aspect integration in jwt-we
 
* jwt-we obviously as well as jwt-we-conf.we, which contains aspect integration in jwt-we
* conf (aspects) plugins : jwt-we-conf and .edit (or)
+
* conf (aspects) plugins : jwt-we-conf, jwt-we-conf.edit, jwt-we-conf.editor
* if you plan to use "dynamic" Properties, their plugins : jwt-we-conf-property and .edit
+
* if you plan to use "dynamic" Properties, their plugins : jwt-we-conf-property, jwt-we-conf-property.edit
* TEMPORARY 20081223 patch the jwt-we HEAD using the patch provided at https://bugs.eclipse.org/bugs/show_bug.cgi?id=241567
+
 
 +
Example : open this TODO metamodel, it should show custom information.
  
 
=== Enabling model extensions ===
 
=== Enabling model extensions ===
Line 25: Line 25:
 
=== Using existing model extensions ===
 
=== Using existing model extensions ===
 
To enrich your (workflow) model with custom information using Aspects from existing Profiles provided in your JWT installation,
 
To enrich your (workflow) model with custom information using Aspects from existing Profiles provided in your JWT installation,
* ensure the conf file is not in embeddedConf mode,
+
* provided the conf file is not in embeddedConf mode,
 
* then using the ManageProfiles dialog, select which profiles you want to activate for your (workflow) model
 
* then using the ManageProfiles dialog, select which profiles you want to activate for your (workflow) model
 
* then design your (workflow) model and enrich them with custom information stored in allowed aspects
 
* then design your (workflow) model and enrich them with custom information stored in allowed aspects
Line 31: Line 31:
 
** or merely creating new nodes which have automatically created aspects registered on it
 
** or merely creating new nodes which have automatically created aspects registered on it
 
** or using aspect-enriched views (like the "dynamic" Property PropertySheet tab, or the StaticAspect example PropertySheet tab)...
 
** or using aspect-enriched views (like the "dynamic" Property PropertySheet tab, or the StaticAspect example PropertySheet tab)...
* NB. extensions information and configuration are stored in the *_conf file, which must be provided along with your (workflow) model file
+
 
 +
IMPORTANT
 +
* extensions information and configuration are stored in the *_conf file, which must be provided along with your (workflow) model file
 +
* if you try to open up a (workflow) model that uses extensions of unknown type (i.e. their EMF plugin is not installed in your Eclipse installation), the *_conf file will backed up as *_conf.bak and automatically patched by removing unknown extensions to allow you to still open the it. In the future, it will ask before doing so.
 +
 
 +
Example : use this TODO default extension.
  
 
=== Installing third-party model extensions ===
 
=== Installing third-party model extensions ===
Line 37: Line 42:
 
* if they are provided as plugin(s), install them from their update-site or put their jars in the "plugins" directory of your JWT installation and restart
 
* if they are provided as plugin(s), install them from their update-site or put their jars in the "plugins" directory of your JWT installation and restart
 
* if they are provided as autodiscovered _conf and .ecore (dynamic EMF case) files, put them in the "conf" autodiscovery directory and restart
 
* if they are provided as autodiscovered _conf and .ecore (dynamic EMF case) files, put them in the "conf" autodiscovery directory and restart
 +
 +
Example : try this TODO _conf file or look in jwt-we-conf-model/samples .
  
  
 
== Creating custom aspect model extensions ==
 
== Creating custom aspect model extensions ==
  
=== Setting up simple additional model extensions ===
+
=== Setting up simple (key-value) additional model extensions ===
This can be done (without code nor EMF design) by designing and using "dynamic" Properties :
+
This can be done (without code nor EMF design) thanks to the jwt-we-conf-property official JWT metamodel extension.
* put the (workflow) model file in profile design mode (also called "embeddedConf" mode, by using the ManageProfile UI, or the PropertySheet on the ConfModel). This will allow the (workflow) model to directly use profiles available in its _conf file, and not only Profiles that are provided by the JWT installation.
+
* create your own custom Profile in the _conf file, ex. by right-click > New Child> Profile on the ConfModel in the outline. Give it a distinct name and URL.
+
* then start designing and testing new Property aspects in it :
+
** ex. define one (or more) aspect(s) on your Profile using right click on it > New Child > New Aspect
+
** then select jwt.we.conf.property.Property as its aspect instance type,
+
** also give it a unique id and select which model element type(s) it will be available on
+
** optionally, disable "autocreated" (so it will not be automatically created on any newly created node but will have to be created explicitly), enable "multiple" (so more than one can be created) or give it a default value (works only with primitive types for now)
+
* and when they are ok, export it using the ManageProfile UI to astandalone .conf file,
+
* which you'll register in a plugin or put in the "conf" autodiscovery directory of your JWT installation.
+
* Now you can put the ConfModel's "embeddedConf" property to false again, since your new profile is available among the installed ones.
+
* Therefore you can start using your custom designed model extensions in (workflow) models as shown previously.
+
* NB. as said, property information and configuration are stored in the *_conf file, which must be provided along with your (workflow) model file
+
  
 +
1. Create your own custom profile (if you don't have one already) :
 +
* double-click on a base (workflow) model related *_conf file (or a standalone .conf file created with the Conf Wizard) to open it in the Conf Editor
 +
* create your own custom Profile in it, ex. by right-click > New Child> Profile on the ConfModel root element. Give it a distinct name and URL.
 +
 +
2. Design a new Property aspect in it :
 +
* create one (or more) aspect(s) on your Profile using right click on it > New Child > New Aspect
 +
* then right-click on the editor, choose "Load Resource..." > "Browse Registered Plugins..." and select "org.eclipse.jwt.conf.property", so you can select jwt.we.conf.property.Property as its Aspect Instance Type,
 +
* also give it a unique id, and select which target model element type(s) it will be available on
 +
 +
3. When they are ok, install your extension :
 +
* if you were working on a (workflow) model related *_conf file, export it to a standalone .conf file. To do so, select the ManageProfile tab of the (workflow) model editor, and in the "Export profiles that are not among installed ones" part, click on "Choose target" to choose a new target .conf file and click on the "Export" button, as in the following screenshot :
 +
[[Image:Eclipse_JWT_Aspects-profiles-property_sample2.png]]
 +
* put your standalone .conf file in the "conf" autodiscovery directory of your JWT installation, or register in a plugin with the "org.eclipse.jwt.we.conf.model.conf" extension.
 +
* If you put it to true, you can now put the (workflow) model's related ConfModel's "useEmbeddedConf" property to false again, since your new profile is available among the installed ones.
 +
 +
You can now use your custom designed model extensions in (workflow) models as shown previously.
 +
 +
NB. as said, property information and configuration are stored in the *_conf file, which must be provided along with your (workflow) model file
 +
 +
Example : see on the SVN at [http://dev.eclipse.org/svnroot/soa/org.eclipse.jwt/trunk/examples/] in jwt-we-conf-property-model/samples , and screenshot below :
 +
 +
[[Image:Jwt aspect property sample.png]]
 +
 +
=== Additional features ===
 +
On your self-designed aspect, you can
 +
* disable "autocreated" (so it will not be automatically created on any newly created node but will have to be created explicitly),
 +
* enable "multiple" (so more than one can be created)
 +
* or give it a default value (works only with primitive types for now)
 +
 +
To test it while designing it :
 +
* put the (workflow) model file in profile design mode, by putting the "Use Embedded Conf" property to "true" in or the PropertySheet on the ConfModel, or using the Manage Profiles tab of the (workflow) model editor
 +
* NB. Also called "embeddedConf" mode, it allows the (workflow) model to directly use profiles available in its _conf file, and not only Profiles that are provided by the JWT installation. But you can also directly edit a .conf file, then install it and test it from a regular (workflow) model file.
 +
* you can now add aspects on your (workflow) model element by right-clicking on it, selecting "New Child..." and from there the aspect of your choice. This works in the Conf Editor as welle as in the (workflow) model editor.
 +
 +
Others
 +
* FAQ : if your _conf file is broken (i.e. contains bad XML or EMF, or refers to unknown EMF packages), it can't be opened by the Conf Editor and only the "Enable profiles" button is avalable in the ManageProfile tab. To solve it, open it with the text editor instead, then either open it again with the Conf Editor and do right-click > Reload Conf Model, or open the ManageProfile tab and click on "Enable profiles".
 +
* more wizards are in the works.
  
 
=== For advanced users : designing complex additional model extensions without code ===
 
=== For advanced users : designing complex additional model extensions without code ===
 
This can be done by designing and using "dynamic EMF" aspects, i.e. with EMF design but without code :
 
This can be done by designing and using "dynamic EMF" aspects, i.e. with EMF design but without code :
* design an EMF type extending jwt.we.conf.AspectInstance :
+
1. design an EMF type extending jwt.we.conf.AspectInstance :
** create a new EMF model file near your (workflow) model file by using the Eclipse New Ecore EMF model wizard
+
* create a new EMF model file near your (workflow) model file by using the Eclipse New Ecore EMF model wizard
** in it, name its package as you want and create there a new EMF type
+
* in it, name its package as you want and create there a new EMF type
** in the sample EMF editor, right-click on it, choose "Load Resource..." and select among plugin resources jwt-we-conf-model's the ConfMetaModel.ecore
+
* in the sample EMF editor, right-click on it, choose "Load Resource..." and select among plugin (devtime) resources jwt-we-conf-model's the ConfMetaModel.ecore , so you can let your new type extend jwt.we.conf.AspectInstance using the Extend Type dialog
** so you can let your new type extend jwt.we.conf.AspectInstance using the Extend Type dialog
+
* design your custom model extension : add EMF attributes and references on your type, create other types or load them from other resources and refer to it...
** design your custom model extension : add EMF attributes and references on your type, create other types or load them from other resources and refer to it...
+
 
* then set it up in a custom Profile :
+
2. then set it up in a custom Profile :
** as above for setting up custom "dynamic" Properties, go in profile design mode, and in a custom Profile create a new Aspect
+
* as above for setting up custom "dynamic" Properties, open a (workflow) model-related *_conf or a standalone *.conf file with the Conf Editor, and in a custom Profile create a new Aspect
** in the sample EMF editor, right-click on it, choose "Load Resource..." and select among file resources your custom metamodel
+
* in the Conf Editor, right-click on it, choose "Load Resource..." and select among file resources your custom metamodel, so you can let your aspect's instance type by the custom EMF type you've just designed
** so you can let your aspect's instance type by the custom EMF type you've just designed
+
 
* NB. you must provide your custom EMF metamodel file (and possible additional loaded file models), along with the _conf file in the same directory as your workflow models.
+
NB. you must provide your custom EMF metamodel file (and possible additional loaded file models), along with the _conf file in the same directory as your workflow models.
 +
 
 +
Example : see on the SVN at [http://dev.eclipse.org/svnroot/soa/org.eclipse.jwt/trunk/examples/] in jwt-we-plugins/jwt-we-sample-registereddynamicaspect . See screenshot below :
  
 +
[[Image:Jwt aspect static sample.png]]
  
 
=== For developers : developing complex additional model extensions using EMF-generated code ===
 
=== For developers : developing complex additional model extensions using EMF-generated code ===
 
This can be done by designing a custom EMF metamodel and generating its code to be used in Aspects :
 
This can be done by designing a custom EMF metamodel and generating its code to be used in Aspects :
 
* use the Eclipse new EMF plugin project wizard to create a new project with an EMF model in it and its .genmodel companion file for configuring java code generation
 
* use the Eclipse new EMF plugin project wizard to create a new project with an EMF model in it and its .genmodel companion file for configuring java code generation
* like above, design in this new EMF model your own type extending jwt.we.conf.AspectInstance
+
* see above how to design in this new EMF model your own type extending jwt.we.conf.AspectInstance
 
* open the companion .genmodel file and configure it accordingly, then use it to generate the model and .edit code, and optionally .editor code.
 
* open the companion .genmodel file and configure it accordingly, then use it to generate the model and .edit code, and optionally .editor code.
* then again, set it up in a custom Profile, like above, and export it to its own .conf file.
+
* then again, see above how to set it up in a custom Profile, and export it to its own .conf file.
* Finally, register this .conf file in the project's plugin.xml using the jwt.we.conf extension point, along with the EMF model.
+
* Finally, register this .conf file in the project's plugin.xml using the "org.eclipse.jwt.we.conf.model.conf" extension point, along with the EMF model.
** NB. this solution of registering the conf file can also be used in the "dynamic" EMF case above, though it is too complex for it
+
** NB. this solution of registering the conf file can also be used in the "dynamic" EMF case above (though it is arguably too heavy a solution for dynamic EMF).
  
 +
Example : see on the SVN at [http://dev.eclipse.org/svnroot/soa/org.eclipse.jwt/trunk/examples/]
 +
* Logging : in jwt-we-plugins/jwt-we-sample-logging and its jwt-we-plugins/jwt-we-sample-logging.edit companion project.
 +
* StaticAspect : in jwt-we-plugins/jwt-we-sample-staticaspect and its jwt-we-plugins/jwt-we-sample-staticaspect.edit companion project.
  
== For EMF-based tool developers : enriching a model with extensions ==
+
=== See also ===
 +
* Existing aspect model extensions for JWT at [[JWT_Metamodel_Extensions/Official]], [[JWT_Metamodel_Extensions/Labelized]] and [[JWT_Metamodel_Extensions/Others]]
 +
* Ideas of what to do with it in [[JWT_Metamodel_Extension_Specifications/Requirements]]
 +
* How they fit int the whole [[JWT_Metamodel]]
 +
* Their initial specifications: [[JWT Metamodel Extension Specifications]]
 +
 
 +
== For other EMF-based tool developers : enriching a model with extensions ==
 
WARNING: this is only of interest if you're developing your own EMF-based tool and are interested in JWT Aspect metamodel extensions to let your own model accept custom information.
 
WARNING: this is only of interest if you're developing your own EMF-based tool and are interested in JWT Aspect metamodel extensions to let your own model accept custom information.
  
Line 89: Line 133:
  
 
If you're developing an EMF-based tool, there are three ways to add custom information to an EMF model :
 
If you're developing an EMF-based tool, there are three ways to add custom information to an EMF model :
* extend an existing type of the model with your own type. This is only interesting to create well identified subtypes, i.e. that could have been provided in the base model beforehand. If it is the case, please consider contributing it to JWT's core metamodel.
+
* extend an existing type of the model with your own type. This is only interesting to create well identified subtypes, i.e. that could have been provided in the base model beforehand. If it is the case, please consider contributing it to JWT's core metamodel. To enable child extenders, extensibleProviderFactory="true" has to be set on the genModel package of the EMF class you want to extend, and on your side you have to set childCreationExtenders="true" on the genModel package of your extending EMF class. See an example in jwt-we-plugins/jwt-we-sample-aspectchildextenders and Ed Merks' blog at http://ed-merks.blogspot.com/2008/01/creating-children-you-didnt-know.html .
 
* add instances of your own type to an openly typed reference (Any, EObject...). This is a good all-around solution but requires that such a reference exists in the model, and doesn't provide management of information coming from different third-party providers. Therefore we didn't do so in JWT.
 
* add instances of your own type to an openly typed reference (Any, EObject...). This is a good all-around solution but requires that such a reference exists in the model, and doesn't provide management of information coming from different third-party providers. Therefore we didn't do so in JWT.
 
* manage instances of your own types in another model that let them refer to the main model's elements. This non-intrusive solution works with any model without prerequisite and allows to share type extensions between model types. In JWT, Aspects do this in a simple, typed way that allows for having custom-information coming from different third-party providers, while the genmodel file is a more complex example.
 
* manage instances of your own types in another model that let them refer to the main model's elements. This non-intrusive solution works with any model without prerequisite and allows to share type extensions between model types. In JWT, Aspects do this in a simple, typed way that allows for having custom-information coming from different third-party providers, while the genmodel file is a more complex example.
Line 95: Line 139:
 
=== Allowing aspects (jwt-we-conf*) in your EMF model ===
 
=== Allowing aspects (jwt-we-conf*) in your EMF model ===
 
* put the aspects (jwt-we-conf*) plugins in your plugin Feature
 
* put the aspects (jwt-we-conf*) plugins in your plugin Feature
* let your model plugin depend from jwt-we-conf and the base classes of your EMF.edit's ItemProviders extend AspectsEnrichedBaseItemProvider rather than BaseItemProvider. This enables right-click > New Child > aspectxxx commands, as well as aspect behaviours (mainly autocreated aspects). Alternatively, you can write its code in your root generated class.
+
* let your model plugin depend from jwt-we-conf and the base classes of your EMF.edit's ItemProviders extend AspectsEnrichedItemProviderAdapter rather than BaseItemProvider. To achieve this, set in your extending EMF class' genmodel root the "Provider Root Extends Class" property to org.eclipse.jwt.we.conf.aspects.provider.AspectEnrichedItemProviderAdapter, and regenerate your EMF .edit java code. This enables right-click > New Child > aspectxxx commands, as well as aspect behaviours (mainly autocreated aspects). NB. Alternatively, you can write its code in your root generated class.
 
* that's it ! If you want, you can now also develop a custom Property Sheet tab for your aspect, or a view, an editor sheet...
 
* that's it ! If you want, you can now also develop a custom Property Sheet tab for your aspect, or a view, an editor sheet...
 +
 +
== Aspect model extension samples ==
 +
 +
=== Logging Aspect sample ===
 +
Provide a simple Aspect that has business meaning, like an Aspect for configuring Logging level on an Action.
 +
 +
Available in the SVN under [http://dev.eclipse.org/svnroot/soa/org.eclipse.jwt/trunk/examples/] in the jwt-we-sample-logging and jwt-we-sample-logging.edit projects.
 +
 +
See screenshots in the latest slides of the [http://www.slideshare.net/mdutoo/eclipse-summit-2009-aspect-oriented-modeling ESE '09 Aspect Oriented Modeling presentation].
 +
 +
Features
 +
* a property typed by a predefined enumeration (for logging) such as "WARN", "SEVERE", "INFO". This translates to a listbox in the property sheet UI.
 +
* a dedicated "Logging" property tab in the property sheet
 +
* an installed conf comprising of a single aspect definition allowing Logging aspect instances to decorate Actions
 +
* sample workflows with Logging conf and instance decorations on Actions.
 +
 +
=== Technical examples ===
 +
See samples mentioned within each previous paragraph.
 +
 +
Summarizing them all, available in the SVN under [http://dev.eclipse.org/svnroot/soa/org.eclipse.jwt/trunk/examples/] :
 +
* Standalone Dynamic Aspect sample
 +
* Registered Dynamic Aspect sample
 +
* Static Aspect sample
 +
* Child Extenders Aspect sample : shows how to combine Aspects with EMF Child Extenders (which could also be used on their own).
 +
 +
 +
== Aspects Howto ==
 +
 +
=== How to have a profile activated on every new workflow ===
 +
The best way is to do it programmatically : if you don't already have one, create your own "New workflow" action that extends JWT's, and see in [http://dev.eclipse.org/svnroot/soa/org.eclipse.jwt/trunk/we/jwt-we-conf-model.edit/src/org/eclipse/jwt/we/conf/edit/ui/ManageActivatedProfilesUI.java?view=markup&root=Technology_Project] how to write code that
 +
* create a _conf file for a model that had none : ex. see "enableProfileButton.addListener(SWT.Selection," :
 +
<source lang="java">
 +
  ConfModel newlyLoadedConfModel = ConfModelResourceManager.INSTANCE.loadConfModelOfModel(selectedModel, true);
 +
</source>
 +
* the profile you want to activate on all models has to be "installed" in your JWT install (best way is to have a plugin with the right .conf and extensions in its plugin.xml)
 +
* then "activate" this installed profile so it'll be copied in your model's _conf file : ex. see "activateInstalledProfileAction" :
 +
<source lang="java">
 +
  AspectManager.INSTANCE.activateProfile(getSelectedModel(), installedProfile);
 +
</source>
 +
 +
And it should be OK !
 +
 +
=== How to activate a profile on all existing workflows ===
 +
See above, same idea : customize the "Open" action with code that
 +
* "activates" your installed profile so it'll be copied in your model's _conf file : ex. see "activateInstalledProfileAction" :
 +
<source lang="java">
 +
  AspectManager.INSTANCE.activateProfile(getSelectedModel(), installedProfile);
 +
</source>
 +
 +
=== How to programmatically set custom properties (or any other aspect) ===
 +
This can be useful e.g. in a Wizard.
 +
You have to use AspectManager (in [http://dev.eclipse.org/svnroot/soa/org.eclipse.jwt/trunk/we/jwt-we-conf-model/src/org/eclipse/jwt/we/conf/model/aspects/]) which is the entry point to aspects, including custom properties, and :
 +
* if you didn't do it yet, define a profile describing on which model elements you want which custom properties (see the wiki above at [http://wiki.eclipse.org/JWT_Metamodel_Extension])
 +
* activate this profile on your model (see above [http://wiki.eclipse.org/JWT_Metamodel_Extension#How_to_have_a_profile_activated_on_every_new_workflow])
 +
* set the custom properties you want on the model elements they decorate, and finally save it all :
 +
<source lang="java">
 +
  // look for your custom property aspect
 +
  List<Aspect> aspects = getAspects(EObject modelElement)
 +
  Property myCustomPropertyAspect = null;
 +
  String myCustomPropertyAspectId = "my.aspect.id"
 +
  for (Aspect aspect : aspects) {
 +
      if (myCustomPropertyAspectId.equals(aspect.getId())) {
 +
        myCustomPropertyAspect = (Property) aspect;
 +
      }
 +
  }
 +
 +
  // and
 +
  Property myCustomPropertyInstance = AspectManager.INSTANCE.getAspectInstance(modelElement, myCustomPropertyAspect)
 +
  // or (if multiple or not autocreated)
 +
  Property myCustomPropertyInstance = AspectManager.INSTANCE.createAndAddAspectInstance(myCustomPropertyAspect, modelElement)
 +
 
 +
  // set the value
 +
  myCustomPropertyInstance.setValue("wizard value");
 +
 +
  // don't forget to save the model at the end of the wizard, that will also save the custom properties
 +
</source>

Latest revision as of 06:05, 23 May 2011

What are aspect model extensions for

JWT provides a mechanism allowing to store typed custom information in workflow models, thanks to an additional *_conf file (actually, it works for any kind of EMF model). Profiles describe what kind of additional information (or Aspects) can be stored on model elements. Such profiles and aspects can be provided by JWT integrators to let their users provide complex information needed by their custom features, or designed by end users to let them add information as simple as key-value properties.


Using aspect model extensions

Installation

Aspect model extensions are available by default in your JWT installation starting from JWT 0.6.

If they are not, here are the additional JWT eclipse plugins you need in your JWT installation (or workspace) :

  • jwt-we obviously as well as jwt-we-conf.we, which contains aspect integration in jwt-we
  • conf (aspects) plugins : jwt-we-conf, jwt-we-conf.edit, jwt-we-conf.editor
  • if you plan to use "dynamic" Properties, their plugins : jwt-we-conf-property, jwt-we-conf-property.edit

Example : open this TODO metamodel, it should show custom information.

Enabling model extensions

To enable its custom Conf in your (workflow) model : if it is not already enabled for your xxx.workflow model, i.e. if it has no custom Conf already (xxx.workflow_conf file),

  • start from a vanilla (workflow) model xxx.workflow and open it.
  • open the ManageProfiles UI. One way is to select the corresponding editor sheet, or open it if it is not already by right click > Editor sheets > Manage Profiles. Another way could be : right click and select ExternalActions > ManageProfiles, which opens the ManageProfiles dialog.
  • Since there is no conf yet, the ManageProfiles UI is empty and only permits to activate profiles by clicking on a button
  • click on this button, which creates a related, empty conf file, named xxx.workflow_conf .

NB. this would also work for any kind of EMF model.

Using existing model extensions

To enrich your (workflow) model with custom information using Aspects from existing Profiles provided in your JWT installation,

  • provided the conf file is not in embeddedConf mode,
  • then using the ManageProfiles dialog, select which profiles you want to activate for your (workflow) model
  • then design your (workflow) model and enrich them with custom information stored in allowed aspects
    • ex. creating aspects on nodes using right click on node > New Child > xxxaspect
    • or merely creating new nodes which have automatically created aspects registered on it
    • or using aspect-enriched views (like the "dynamic" Property PropertySheet tab, or the StaticAspect example PropertySheet tab)...

IMPORTANT

  • extensions information and configuration are stored in the *_conf file, which must be provided along with your (workflow) model file
  • if you try to open up a (workflow) model that uses extensions of unknown type (i.e. their EMF plugin is not installed in your Eclipse installation), the *_conf file will backed up as *_conf.bak and automatically patched by removing unknown extensions to allow you to still open the it. In the future, it will ask before doing so.

Example : use this TODO default extension.

Installing third-party model extensions

To install third-party model extensions in your JWT installation,

  • if they are provided as plugin(s), install them from their update-site or put their jars in the "plugins" directory of your JWT installation and restart
  • if they are provided as autodiscovered _conf and .ecore (dynamic EMF case) files, put them in the "conf" autodiscovery directory and restart

Example : try this TODO _conf file or look in jwt-we-conf-model/samples .


Creating custom aspect model extensions

Setting up simple (key-value) additional model extensions

This can be done (without code nor EMF design) thanks to the jwt-we-conf-property official JWT metamodel extension.

1. Create your own custom profile (if you don't have one already) :

  • double-click on a base (workflow) model related *_conf file (or a standalone .conf file created with the Conf Wizard) to open it in the Conf Editor
  • create your own custom Profile in it, ex. by right-click > New Child> Profile on the ConfModel root element. Give it a distinct name and URL.

2. Design a new Property aspect in it :

  • create one (or more) aspect(s) on your Profile using right click on it > New Child > New Aspect
  • then right-click on the editor, choose "Load Resource..." > "Browse Registered Plugins..." and select "org.eclipse.jwt.conf.property", so you can select jwt.we.conf.property.Property as its Aspect Instance Type,
  • also give it a unique id, and select which target model element type(s) it will be available on

3. When they are ok, install your extension :

  • if you were working on a (workflow) model related *_conf file, export it to a standalone .conf file. To do so, select the ManageProfile tab of the (workflow) model editor, and in the "Export profiles that are not among installed ones" part, click on "Choose target" to choose a new target .conf file and click on the "Export" button, as in the following screenshot :

Eclipse JWT Aspects-profiles-property sample2.png

  • put your standalone .conf file in the "conf" autodiscovery directory of your JWT installation, or register in a plugin with the "org.eclipse.jwt.we.conf.model.conf" extension.
  • If you put it to true, you can now put the (workflow) model's related ConfModel's "useEmbeddedConf" property to false again, since your new profile is available among the installed ones.

You can now use your custom designed model extensions in (workflow) models as shown previously.

NB. as said, property information and configuration are stored in the *_conf file, which must be provided along with your (workflow) model file

Example : see on the SVN at [1] in jwt-we-conf-property-model/samples , and screenshot below :

Jwt aspect property sample.png

Additional features

On your self-designed aspect, you can

  • disable "autocreated" (so it will not be automatically created on any newly created node but will have to be created explicitly),
  • enable "multiple" (so more than one can be created)
  • or give it a default value (works only with primitive types for now)

To test it while designing it :

  • put the (workflow) model file in profile design mode, by putting the "Use Embedded Conf" property to "true" in or the PropertySheet on the ConfModel, or using the Manage Profiles tab of the (workflow) model editor
  • NB. Also called "embeddedConf" mode, it allows the (workflow) model to directly use profiles available in its _conf file, and not only Profiles that are provided by the JWT installation. But you can also directly edit a .conf file, then install it and test it from a regular (workflow) model file.
  • you can now add aspects on your (workflow) model element by right-clicking on it, selecting "New Child..." and from there the aspect of your choice. This works in the Conf Editor as welle as in the (workflow) model editor.

Others

  • FAQ : if your _conf file is broken (i.e. contains bad XML or EMF, or refers to unknown EMF packages), it can't be opened by the Conf Editor and only the "Enable profiles" button is avalable in the ManageProfile tab. To solve it, open it with the text editor instead, then either open it again with the Conf Editor and do right-click > Reload Conf Model, or open the ManageProfile tab and click on "Enable profiles".
  • more wizards are in the works.

For advanced users : designing complex additional model extensions without code

This can be done by designing and using "dynamic EMF" aspects, i.e. with EMF design but without code : 1. design an EMF type extending jwt.we.conf.AspectInstance :

  • create a new EMF model file near your (workflow) model file by using the Eclipse New Ecore EMF model wizard
  • in it, name its package as you want and create there a new EMF type
  • in the sample EMF editor, right-click on it, choose "Load Resource..." and select among plugin (devtime) resources jwt-we-conf-model's the ConfMetaModel.ecore , so you can let your new type extend jwt.we.conf.AspectInstance using the Extend Type dialog
  • design your custom model extension : add EMF attributes and references on your type, create other types or load them from other resources and refer to it...

2. then set it up in a custom Profile :

  • as above for setting up custom "dynamic" Properties, open a (workflow) model-related *_conf or a standalone *.conf file with the Conf Editor, and in a custom Profile create a new Aspect
  • in the Conf Editor, right-click on it, choose "Load Resource..." and select among file resources your custom metamodel, so you can let your aspect's instance type by the custom EMF type you've just designed

NB. you must provide your custom EMF metamodel file (and possible additional loaded file models), along with the _conf file in the same directory as your workflow models.

Example : see on the SVN at [2] in jwt-we-plugins/jwt-we-sample-registereddynamicaspect . See screenshot below :

Jwt aspect static sample.png

For developers : developing complex additional model extensions using EMF-generated code

This can be done by designing a custom EMF metamodel and generating its code to be used in Aspects :

  • use the Eclipse new EMF plugin project wizard to create a new project with an EMF model in it and its .genmodel companion file for configuring java code generation
  • see above how to design in this new EMF model your own type extending jwt.we.conf.AspectInstance
  • open the companion .genmodel file and configure it accordingly, then use it to generate the model and .edit code, and optionally .editor code.
  • then again, see above how to set it up in a custom Profile, and export it to its own .conf file.
  • Finally, register this .conf file in the project's plugin.xml using the "org.eclipse.jwt.we.conf.model.conf" extension point, along with the EMF model.
    • NB. this solution of registering the conf file can also be used in the "dynamic" EMF case above (though it is arguably too heavy a solution for dynamic EMF).

Example : see on the SVN at [3]

  • Logging : in jwt-we-plugins/jwt-we-sample-logging and its jwt-we-plugins/jwt-we-sample-logging.edit companion project.
  • StaticAspect : in jwt-we-plugins/jwt-we-sample-staticaspect and its jwt-we-plugins/jwt-we-sample-staticaspect.edit companion project.

See also

For other EMF-based tool developers : enriching a model with extensions

WARNING: this is only of interest if you're developing your own EMF-based tool and are interested in JWT Aspect metamodel extensions to let your own model accept custom information.

EMF model extension alternatives

Here we provide a short foray into EMF model extension alternatives. For more information, look up JWT Metamodel Extension Specifications.

If you're developing an EMF-based tool, there are three ways to add custom information to an EMF model :

  • extend an existing type of the model with your own type. This is only interesting to create well identified subtypes, i.e. that could have been provided in the base model beforehand. If it is the case, please consider contributing it to JWT's core metamodel. To enable child extenders, extensibleProviderFactory="true" has to be set on the genModel package of the EMF class you want to extend, and on your side you have to set childCreationExtenders="true" on the genModel package of your extending EMF class. See an example in jwt-we-plugins/jwt-we-sample-aspectchildextenders and Ed Merks' blog at http://ed-merks.blogspot.com/2008/01/creating-children-you-didnt-know.html .
  • add instances of your own type to an openly typed reference (Any, EObject...). This is a good all-around solution but requires that such a reference exists in the model, and doesn't provide management of information coming from different third-party providers. Therefore we didn't do so in JWT.
  • manage instances of your own types in another model that let them refer to the main model's elements. This non-intrusive solution works with any model without prerequisite and allows to share type extensions between model types. In JWT, Aspects do this in a simple, typed way that allows for having custom-information coming from different third-party providers, while the genmodel file is a more complex example.

Allowing aspects (jwt-we-conf*) in your EMF model

  • put the aspects (jwt-we-conf*) plugins in your plugin Feature
  • let your model plugin depend from jwt-we-conf and the base classes of your EMF.edit's ItemProviders extend AspectsEnrichedItemProviderAdapter rather than BaseItemProvider. To achieve this, set in your extending EMF class' genmodel root the "Provider Root Extends Class" property to org.eclipse.jwt.we.conf.aspects.provider.AspectEnrichedItemProviderAdapter, and regenerate your EMF .edit java code. This enables right-click > New Child > aspectxxx commands, as well as aspect behaviours (mainly autocreated aspects). NB. Alternatively, you can write its code in your root generated class.
  • that's it ! If you want, you can now also develop a custom Property Sheet tab for your aspect, or a view, an editor sheet...

Aspect model extension samples

Logging Aspect sample

Provide a simple Aspect that has business meaning, like an Aspect for configuring Logging level on an Action.

Available in the SVN under [4] in the jwt-we-sample-logging and jwt-we-sample-logging.edit projects.

See screenshots in the latest slides of the ESE '09 Aspect Oriented Modeling presentation.

Features

  • a property typed by a predefined enumeration (for logging) such as "WARN", "SEVERE", "INFO". This translates to a listbox in the property sheet UI.
  • a dedicated "Logging" property tab in the property sheet
  • an installed conf comprising of a single aspect definition allowing Logging aspect instances to decorate Actions
  • sample workflows with Logging conf and instance decorations on Actions.

Technical examples

See samples mentioned within each previous paragraph.

Summarizing them all, available in the SVN under [5] :

  • Standalone Dynamic Aspect sample
  • Registered Dynamic Aspect sample
  • Static Aspect sample
  • Child Extenders Aspect sample : shows how to combine Aspects with EMF Child Extenders (which could also be used on their own).


Aspects Howto

How to have a profile activated on every new workflow

The best way is to do it programmatically : if you don't already have one, create your own "New workflow" action that extends JWT's, and see in [6] how to write code that

  • create a _conf file for a model that had none : ex. see "enableProfileButton.addListener(SWT.Selection," :
   ConfModel newlyLoadedConfModel = ConfModelResourceManager.INSTANCE.loadConfModelOfModel(selectedModel, true);
  • the profile you want to activate on all models has to be "installed" in your JWT install (best way is to have a plugin with the right .conf and extensions in its plugin.xml)
  • then "activate" this installed profile so it'll be copied in your model's _conf file : ex. see "activateInstalledProfileAction" :
   AspectManager.INSTANCE.activateProfile(getSelectedModel(), installedProfile);

And it should be OK !

How to activate a profile on all existing workflows

See above, same idea : customize the "Open" action with code that

  • "activates" your installed profile so it'll be copied in your model's _conf file : ex. see "activateInstalledProfileAction" :
   AspectManager.INSTANCE.activateProfile(getSelectedModel(), installedProfile);

How to programmatically set custom properties (or any other aspect)

This can be useful e.g. in a Wizard. You have to use AspectManager (in [7]) which is the entry point to aspects, including custom properties, and :

  • if you didn't do it yet, define a profile describing on which model elements you want which custom properties (see the wiki above at [8])
  • activate this profile on your model (see above [9])
  • set the custom properties you want on the model elements they decorate, and finally save it all :
   // look for your custom property aspect
   List<Aspect> aspects = getAspects(EObject modelElement)
   Property myCustomPropertyAspect = null;
   String myCustomPropertyAspectId = "my.aspect.id"
   for (Aspect aspect : aspects) {
      if (myCustomPropertyAspectId.equals(aspect.getId())) {
         myCustomPropertyAspect = (Property) aspect;
      }
   }
 
   // and
   Property myCustomPropertyInstance = AspectManager.INSTANCE.getAspectInstance(modelElement, myCustomPropertyAspect)
   // or (if multiple or not autocreated)
   Property myCustomPropertyInstance = AspectManager.INSTANCE.createAndAddAspectInstance(myCustomPropertyAspect, modelElement)
 
   // set the value
   myCustomPropertyInstance.setValue("wizard value");
 
   // don't forget to save the model at the end of the wizard, that will also save the custom properties

Copyright © Eclipse Foundation, Inc. All Rights Reserved.