== Overview ==
The goal of the SimpleTransformationsChain plug-in is gathering the [[MoDisco#Infrastructure|infrastructure]] and [[MoDisco#Technologies|technologies]] plug-ins and providing orchestration of these plug-ins. These additional facilities reuse the features offered by the other plug-ins in order to allow performing more elaborate operations and complex tasks, such as directly generating a UML model from a Java project. It also provides an additional feature trying to detect bidirectional associations in target UML model.

''Quality disclaimer: this discoverer is provided without any guarantee: it was only tested on a small number of projects of relatively small sizes. It may not be suitable for production environments.''

==Quick Start Guide==

After discovery of your application, you will obtain a UML model. This model could be imported in some usual modelers like [http://www.eclipse.org/modeling/mdt/papyrus/ Papyrus] from the Modeling project.

[[Image:../img/MoDisco_simpletransformationschain_tutorial_PetStore_UML_inModelBrowser.png|frame|center|An example of UML model discovered from the famous Pet Store application]]

==Contextual menu==

The SimpleTransformationsChain plugin offers simple Eclipse contextual actions to dynamically launch the additionally provided features.

You can launch the "Discover UML model from Java project" action from a Java project by right-clicking on the corresponding Java project (in your workspace) and then selecting the appropriate action under '''Discovery > Discoverers''' in the provided contextual menu:

[[Image:../img/MoDisco_DiscoverUMLfromJavaProject_menu.png|frame|center|Contextual menu populated with MoDisco entries]]

==Launch configuration==

The SimpleTransformationsChain plugin is registered with the "discoverer" extension point, so in launch configurations, you are able to create a discoverer launcher dedicated to a project:

Open the launch configurations:

[[Image:../img/MoDisco_Run_RunConfigurations.png|frame|center|Launch Configurations...]]

Create a new '''MoDisco Discovery''' launch configuration, and select the discoverer "discoverUMLModelWithBidirectionalAssociationsFromProject" from the drop-down list:

[[Image:../img/MoDisco_LaunchConfigs_selectDiscoverUmlModelWithBidiAssocFromProject.png|frame|center|Select the discoverer]]

Then, select your project in the "Source element" field:

[[Image:../img/MoDisco_LaunchConfig_SelectSourceProject.png|frame|center|Selecting a source project]]

And finally, click '''Run''' to start the discovery.

==Description==

To illustrate the SimpleTransformationsChain plug-in, we will use a sample inspired from the [http://java.sun.com/developer/technicalArticles/J2EE/petstore/ Pet Store Application].

== Setup ==

Sources of the Pet Store application are  available here: http://www.oracle.com/technetwork/java/petstore1-3-1-02-139690.html

You may have to download several libraries to obtain an eclipse project without errors (JPA, JTA, JSF-apis and Servlets-jsp-apis).
A complete bundle is also available from [http://www.mia-software.com/html/miaStudio/download/modisco/examples/javapetstore-2.0-ea5.zip Mia-Software...]
To view this application in your Eclipse workspace, you will have to extract the content of this archive, and use the "import" wizard (import project in workspace).

== Get UML model of Pet Store application ==

We will explain different ways to obtain the UML model; it will demonstrate how several simple steps have been combined to build a complex task : discover a UML model from a java project.

===Basic way===

There are several tools that are each able to perform a specific task; we will see how each task works.

====Get the java model====

* Open the '''Run configurations...''' dialog.
* Then, press the "New" button to create a configuration of type "MoDisco Discovery".
* Enter a name for this configuration, "PetStore reverse to Java model" for example. 
* Select the discoverer named "org.eclipse.modisco.java.discoverer.project".
* Enter the path to the project containing the PetStore application in the "Source element" field.
* Set SERIALIZE_TARGET to true

[[Image:../img/MoDisco_Run_Configurations_PetStore_reverseJava.png|frame|center|Java Discoverer configuration]]

Finally, press the '''Run''' button to get the Java model.

You could also use the the contextual menu (right click) when the project containing the Pet Store application is selected. Select '''Discovery > Discoverers > Discover Java Project''':

[[Image:../img/MoDisco_DiscoverJavaProject_Menu.png|frame|center|Menu to discover a Java project]]

[[Image:../img/MoDisco_simpletransformationschain_PetStore_JavaXMI_inModelBrowser.png|frame|center|The Java model, with a focus on the SimpleCaptcha class.]]

==== Get the KDM model  ====

Using the ATL transformation [https://dev.eclipse.org/svnroot/modeling/org.eclipse.mdt.modisco/plugins/trunk/org.eclipse.modisco.java.discoverer/src/org/eclipse/modisco/java/discoverer/internal/resources/transformations/javaToKdm.atl javaToKdm], we will transform the Java model into a KDM model. We have to define another configuration to perform this transformation:

* Open the '''Run configurations...''' dialog
* Press the "New" button to create a configuration of type '''ATL Transformation'''
* Enter a name for this configuration, "Java to Kdm transformation" for example
* Select the ATL module in your workspace, "/Transformations/JavaToKdm.atl" for example
* Select metamodel URIs from the EMF Registry (<nowiki>http://www.eclipse.org/MoDisco/Java/0.2.incubation/java</nowiki> and <nowiki>http://www.eclipse.org/MoDisco/kdm/action</nowiki>)
* '''Note''': the source metamodel parameter must be named "java" and the source model parameter must be named "IN", otherwise the transformation won't work
* Select the source model ("_java.xmi" file) in your workspace, and enter a path for your target model ("_kdm.xmi" file).

[[Image:../img/MoDisco_simpletransformationschain_tutorial_Run_Configurations-JavaToKDM.png|frame|center|configuration of the Java to Kdm ATL Transformation]]

Finally, press the '''Run''' button to get the KDM model. 

You could also use the the contextual menu (right click) when the Java model of the Pet Store application is selected: '''Discovery > Discoverers > Discover KDM model from Java model'''.

[[Image:../img/MoDisco_PetStore_kdm_xmi_inModelBrowser.png|frame|center|The KDM model, with a focus on the SimpleCaptcha class.]]

==== Get the UML model====

Using the ATL transformation [https://dev.eclipse.org/svnroot/modeling/org.eclipse.mdt.modisco/plugins/trunk/org.eclipse.modisco.kdm.uml2converter/src/org/eclipse/modisco/kdm/uml2converter/internal/resources/transformations/KDMtoUML.atl KDMtoUML], we will transform the KDM model into a UML model.

We have to define another launch configuration to perform this transformation:

* Open the '''Run configurations...''' dialog
* Press the "New" button to create a configuration of type '''ATL Transformation'''
* Enter a name for this configuration, '''Kdm to Uml transformation''' for example.
* Select the ATL module in your workspace, "/Transformations/KdmToUml.atl" for example.
* Select metamodel URIs from EMF Registry (<nowiki>http://www.eclipse.org/MoDisco/kdm/action</nowiki> and <nowiki>http://www.eclipse.org/uml2/2.1.0/UML</nowiki>)
* '''Note''': the source metamodel parameter must be named "kdm", and the source model parameter must be named "kdmInput", otherwise the transformation won't work
* Select the source model in your workspace, and enter a path for your target model.

[[Image:../img/MoDisco_simpletransformationschain_tutorial_Run_Configurations_KDMtoUML.png|frame|center|configuration of the Java to Kdm ATL Transformation]]

Finally, press the '''Run''' button to get the UML model.

You could also use the the contextual menu (right click) when the kdm model of the Pet Store application is selected: '''Discovery > Discoverers > Discover UML model from KDM model'''.

[[Image:../img/MoDisco_simpletransformationschain_tutorial_PetStore_UML_inModelBrowser.png|frame|center|The UML model, with a focus on the SimpleCaptcha class.]]

====Initialize a workflow====

To be able to chain previous tasks, MoDisco provides a workflow initializer:

* Open the '''Run configurations...''' dialog
* Pess the '''New''' button to create a configuration of type '''MoDisco Workflow'''.
* Enter a name for this configuration, for example "Discovery of PetStore application".
* Press the '''Load...''' button to successively add configurations "PetStore reverse to Java model", "Java to Kdm transformation" and "Kdm to Uml transformation" (or whatever you named your previous launch configurations).

[[Image:../img/MoDisco_Run_Configurations_DiscoveryOfPetStoreApplication.png|frame|center|The workflow configuration to execute all steps to get a UML model from a java project]]

* Finally, press the '''Run''' button to get the UML model.

This is a first way to get a UML model from a java application. However when parameters change (the selected java application, target UML model, ...), you will have to change the different configurations in order to restore the coherence of all steps, by making sure the input of each step is produced by the previous step.

===The SimpleTransformationsChain way===

* Open the '''Run configurations...''' dialog
* Press the '''New''' button to create a configuration of type '''MoDisco Discoverers'''.
* Enter a name for this configuration, "PetStore reverse to UML model" for example.
* Select Discoverer kind "org.eclipse.modisco.usecase.simpletransformationschain.discovererUMLModelFromProject".
* Enter the path to the PetStore application project
* Set the '''SERIALIZE_TARGET''' parameter to '''true'''

[[Image:../img/MoDisco_Run_Configurations_PetStoreReverseToUMLModel.png|frame|center|SimpleTransformationsChain Discoverer configuration]]

* Finally, press the '''Run''' button to get the UML model.

You could also use the the contextual menu (right click) when the Pet Store application project is selected: '''Discovery > Discoverers > Discover UML model from Java project'''

[[Image:../img/MoDisco_simpletransformationschain_tutorial_PetStore_UML_inModelBrowser.png|frame|center|The UML model, with a focus on the SimpleCaptcha class.]]

==Visualize the UML model==

There are different possibilities for visualizing and exploring the target model.

===Using MoDisco model browser===

The MoDisco model browser displays the model as a tree. It proposes a view of all instances sorted by metaclass, and offers the possibility to visualize all links in the model (whether empty or not, with cardinality, etc.)

* [../../org.eclipse.modisco.infrastructure.doc/mediawiki/model_browser/user.html More details on the MoDisco model browser]

===Using UML2 Tools===

After the installation of UML2 Tools, a component of the Modeling/MDT project, you will be able to initialize class diagrams from the UML model.

[[Image:../img/MoDisco_SimpleCaptchaExample_UMLDiagramView.jpg|center|One UML class diagram, a focus on SimpleCaptcha class.]]

===Using Papyrus===

See [http://www.eclipse.org/modeling/mdt/papyrus/ the Papyrus project page]

==Current limitations==

As this component is an aggregation of existing components, its limitations reflect this architecture: the main limitations come from the [../../../org.eclipse.modisco.infra.omg.doc/mediawiki/kdm/user.html#Current_Limitations KDM to UML converter].

== Team ==

Gabriel Barbier ([http://www.mia-software.com Mia-Software])

== Included Plug-ins ==

* core plug-in : org.eclipse.modisco.usecase.simpletransformationschain
* UI plug-in : org.eclipse.modisco.usecase.simpletransformationschain.ui