Documentation:User:GettingStarted
From SIDE-Labs.org
Introduction
This chapter is intended as a reference for those working with SIDE for the first time. It is intended to explain the common steps for all modelers, generators and deployers; it will also dig into the handhold of some modelers, generators and deployers.
It is assumed at this point that you have downloaded and installed SIDE on your local machine. If not, please refer to the SIDE Installation Guide instructions.
It is also assumed at this point that you have a fair knowledge of Eclipse environment. If not, refer to the tutorials on www.eclipse.org.
We propose in the next steps to create a sample application based on Alfresco. So, it is assumed that you have downloaded and installed Alfresco on your local machine. If not, please refer to the SIDE Installation Guide instructions.
General Synopsis
SIDE is composed of modelers, generators and deployers Eclipse plug-ins.
The SIDE application plug-in which will be used to modelize the models, generators and deployers you use to create your application.
Application's Project Creation
Open the Topcased Modelling perspective:
Window -> Open perspective -> Other -> Topcased Modeling
Figure 2.1. Topcased Modelling Perspective
The first thing to do is to create a project in your workspace:
File -> New -> Project
Figure 2.2. Topcased Project selection
SelectTopcased projectunderTopcasedcategory.
Figure 2.3. Application's Project Creation
Give a name to your project, for instance:myProject
Figure 2.4. Application's Project in your workspace
Your project has been created in your workspace.
We will now create the models which will be used to generate some functional parts of the application.
Data Modeling and Generation
Usually, the first one to create is the content type model which describes the structure of the data which will be used by the application. For Alfresco-based application, data is composed of content types and their metadata including attributes and associations.
Note that this structure may already exist and may be reversed in a model using SIDE reversing mechanisms.
The following paragraphs gives for beginners a basic overview of data modeling and generation and for users more familiar a quick solution for the need at hand. For additional information, Refer to the SIDE Data user guide.
Model Creation
Let's create a data model:
File -> New -> Other... -> SIDE Modeler -> Class Diagram
Figure 3.1. Data Model Creation pane
Enter the name of your model, for instancemediaLibrary, select the type of diagramClass Diagramand clickFinish.
Two files are created in your project:
- 'mediaLibrary.clazz' is the data model containing all the designed data structure.
- 'mediaLibrary.clazzdi' is synchronized with the data model and contains the designed data structure complemented with the graphical information necessary to position the data elements in the SIDE Data modeler.
The mediaLibrary.clazzdi model is automatically opened in the SIDE data modeler:
Figure 3.2. SIDE Data Modeler
The SIDE Data modeler is composed of 3 main parts:
- TheB 'Outline'pane displays on the upper part the position of the display in the C pane and on the lower part the packages and diagrams tree structure.
- TheC 'main'pane is the graphical working part where is build the data structure: the left part provides the elements which can be integrated in the right part
- TheD 'Properties'pane displays the properties of the current selected elements; the properties may be directly updated in this pane.
Package and diagram Creation
For all models, a good practice is to initially create the package structure in order to organize your design (like for Java program development), especially when you work in a team.
For instance, we will design the data structure of the mediaLibrary data model under the package configuration org/myCompany/media.
Click on the root package in order to give it the name org in the Class Package property view:
Figure 3.3. Class Package Property view
In the outline view, on the root package Class package org, right click to open the contextual menu:
Create child -> Class PackageClick on the newly created package and give the name myCompany in the Package property view.
Proceed the same way to create the class package media:
In order to put the data elements under the media package, right click on the package media in the outline view to open the contextual menu and select
Add diagram -> Class Diagram
Figure 3.4. Class Diagram Creation
Click on the newly created diagram and change its name library in the properties view.
We are ready to design the data structure of our application in the C 'main' pane of the SIDE modeler.
Data structure design
Click on the Class
item of the objects list of the left panel; then click in the white part at the right on the name of the newly created Data box. Set the name to media and double click on the media element:
Figure 3.5. Data element creation
Set the Title to Media Video and click Ok.
On the left part, click on Property in the Object list and then click on the data element MediaVideo: a property Attribute1 is added. Double click on the property to open a dialog box and set the name and the title to Title and set the type to String.
Proceed the same way to create a String attribute 'Author' and a Date attribute 'PublishingDate'.
Note: you can also use the Property view to update the data element properties.
Figure 3.6. Properties of Data element creation
Click on Class in the Object list and create a new data element MediaCategory with a String property 'categoryName'.
Click on Associationin the link list, then click on the MediaVideo element and finally click on the MediaCategory element.
Double click on the newly created association:
Figure 3.7. Properties of Data element creation
Rename the association belongs to.
In the Association first end, change Upper bound of the cardinality to * to indicate that a media category may contain several media video.
In the Association second end, remove the default R2 role and check isNavigable if not already done to indicate that from a media video, one can create or update the associated media category.
This basic data model indicates that two new content types have been created, one to declare video content and another to declare the categories of video.
We will now proceed to the generation of the data elements on a targeted framework like Alfresco.
Application creation
Prior to generate the data model, we must create an Application model which will store the description of our application and its components.
Click on models in the Navigation pane and select:
File -> New -> Other… -> SIDE Modeler -> Application Diagram
Figure 3.8. Application model creation
Enter the File name library.application and click on Finish.
The application model library.application is created in your project.
Select this file and right click to open the contextual menu; select the menu item Manage Configuration to start the panel in which we will declare the steps of generation of your application:
Figure 3.9. Application Generation configuration of model lists
The application generation configuration is divided in 4 main parts.
Application Configuration List
The List of configurations allows defining several generation configurations. The first time there is no configuration and you must click on
to create the first configuration labeled by default New Configuration. Click on
to change the name of the configuration: Enter Main in the name of the configuration input view.
You may create several configurations all along your project: for instance, after finalizing a functional layer of your application, it is no more necessary to generate and deploy it all the times with the models you are working on.
Application configuration 'Models' tab
The Models tab allows to declare the models you want to generate on the targeted frameworks.Click on Add Model and select mediaLibrary.clazz under myProject'/models.
You can add as many models as you need for your application.
Application Configuration Generation tab
The Generation tab allows selecting the generators you want to use on top of the models you declare in the Models tab : the selected generators produce the artifacts on specific frameworks they are associated to.This pane proposes, in the upper part, common options to set up:
- 'Log path' must be set up to indicate where to store the log of the generations; enter '/myProject/Models/logs'.
- 'Generation path' must be set up to indicate where to store the result of the generations; enter '/myProject/Models/generation'.
- Click on 'verbose' to have detailed information during the generation and deployment process.
- Click on 'Skip validation' if you do not want to perform model validation before generation. Model validation is by default automatically performed to avoid generating on incorrect or inconsistent models. But, if you are sure that your models are valid (use 'Validate' to perform a direct validation), select this option.
- Click on 'Documentation generation' if you want to generate the documentation associated to your models.
It proposes, in the lower part, a structured tree where each branch is conforming to the following schema:
- The first level indicates the type of metamodel.
Note that if you select a meta-model but you do not have declared under the models tab at least a model conform to this metamodel, obviously no generation will be performed.
- The second level indicates the targeted technology: this is the kind of framework on which a part or all the application must be deployed. For instance, 'Alfresco' is a technology.
- The third level indicates the version of the targeted technology.
- The fourth level indicates the generator to use: it may exist several generators for a metamodel, a framework and a release.
- The fifth level gives the generation options.
Click on the label of each level to have description in the upper right part of the window.
Figure 3.10. Application Generation configuration of generators
To select a particular generator to apply on your models, first click on the circle checkbox of the metamodel first level, then on the technology second level, then on the version third level and then on the generator. Click on:
KSR500 Data -> Alfresco -> Alfresco 3.x Labs and Enterprise -> SIDE Alfresco Content Generator 1.0.0Then select the options of the generator. Click on:
all the optionsSome parameters of the generator must be set up on the right lower table of the window.
For instance, for the SIDE Alfresco Content Generator 1.0.0, it is necessary to set up the Module Version if you want to keep an historic of the generated artifacts. Click on:
Saveto save the generation configuration.
Application configuration Deployer tab
The Deployer tab contains a single tree similar to the generation one but without the first metamodel level.
The purpose of the deployer tree is to select installed framework instance to install generated artifacts on them.
Let's suppose that you follow the SIDE Installation guide and that you installed Alfresco 3.2 Enterprise.
In the deployment tree, you can select:
Alfresco -> Alfresco 3.x Labs and Enterprise -> SIDE Alfresco Deployerto indicate that you want to deploy the generated artifacts on this special instance of Alfresco: in this case, all the models which have been generated using generators on the technology “Alfresco� and the release “3.x� will be deployed on this Alfresco instance through the SIDE Alfresco deployer.
It is important to note that deployers are independent of meta-model; for instance, the SIDE Alfresco Deployer will deploy on the same Alfresco instance artifacts generated with a Data model and a Workflow model.
Deployers are based on the deployment technique of the targeted framework. The SIDE Alfresco Deployer uses AMP – Alfresco Module Package – and WAR files to deploy the generated artifacts on Alfresco instance.
On selection of a deployer, you usually have to set up some parameters which indicate where is installed the framework instance: for instance, for the “SIDE Alfresco deployer�.
If you previously install Alfresco on your machine, you can set up the Tomcat Installation directory to point on the 'tomcat' directory of Alfresco and the alfresco-mmt.jar path to point on the 'bin/alfresco-mmt.jar'.
You need to stop Alfresco before running the generation & deployment to avoid conflicts during deployment.
Application data structure generation & deployment
At this point we can launch the generation of our 'mediaLibrary.clazz' model. Click on'
LaunchNote: you can also launch the generation of one specific application configuration directly by right clicking the application model file and selecting 'Launch Generation':
Figure 3.11. Quick launch of generation
A generation window is opened and displayed the generation steps.
At the end of the generation, it indicates if the generation is complete with or without errors: In case, there is error, errors are listed in the window and in the log files (one per generator) under the log paths.
In case of no errors, the generation path will contain all the generated artifacts.
Moreover, the side_result.xml page has been generated in the logs path and gives information on the generation process. You can load this page directly in a browser:
- 'Stats' gives a consolidated view of the generation for all the generators and deployers and per generator and deployer.
- 'Generators' gives a detailed view of the generated artifacts per generator: you have access through this view to all the generated artifacts.
- 'Deployers' gives a detailed view of the deployed package per deployer: you have access through this view to the package the deployer has deployed on the targeted frameworks. These packages may be deployed on other instances of the framework on other machines.
- 'Documentation' gives access to the generated documentation for all the models declared in the application configuration.
- 'Services' gives entry points to load per generator all the services which have been generated and deployed on the targeted framework instances.
The SIDE Alfresco deployer deployed the generated artifacts on the Alfresco instance.
In order to check that the new content type has been created, connect to the Alfresco Explorer and create a new content: in the content type list, you will see MediaVideo and MediaCategory; create one of each of them to access metadata form.
Workflow Modeling and Generation
TBD
Form and View Modeling and Generation
TBD
Portal Modeling and Generation
TBD
