Download Developer`s Manual
Transcript
SINTEF Developer'sManual SiSaSStudiov2.0 SINTEFICT 6/11/2012 DEVELOPER'SMANUAL F OR S I S A S S TUDIOV 2.0 Version:1.0 Contributors: FranckChauvel–SINTEF/ICT Summary: ThisdocumentbrieflyexplainshowtoaddnewfeaturesintheSiSaSstudiov1.0.Itfirst outlinesthebasicsoftwaretoolsetneeded,anddepictsthemainarchitectureoftheSiSaSStudio. Theadditionofasimplefeatureisgivenasatutorialandsomecommonissuesarediscussedto conclude. ChangeHistory: Version 1.2 1.1 1.0 0.1 Date June11,2012 June8,2012 Nov29,2011 Oct17,2011 ChangesDescription Addsectionaboutbundlecreation Introducethenewarchitecture FirstVersion InitialOutline Author F.Chauvel F.Chauvel F.Chauvel F.Chauvel ©2009–2011SINTEF 1 1 CONTENTS 2 Introduction................................................................................................................................................................3 3 SettingupyourDevelopmentEnvironment.................................................................................................3 4 5 3.1 InstallingtheDevelopmentToolset........................................................................................................3 3.2 CheckingouttheSiSaSStudioSourceCode.........................................................................................4 ArchitectureoftheSiSaSStudio.........................................................................................................................4 4.1 ASetofEclipsePlugins.................................................................................................................................4 4.2 InternalArchitecture.....................................................................................................................................4 4.2.1 TemplateProjects.................................................................................................................................4 4.2.2 ModelTransformations......................................................................................................................5 4.2.3 ExistingModelTransformations....................................................................................................6 Tutorials.......................................................................................................................................................................7 5.1 5.1.1 DevelopingtheGeneratorscript.....................................................................................................7 5.1.2 DevelopingtheCheckerScript........................................................................................................8 5.1.3 RegisteringtheTransformation......................................................................................................8 5.2 6 DevelopingaNewTransformation.........................................................................................................7 AddinganewProjectTemplate................................................................................................................9 Troubleshooting....................................................................................................................................................10 6.1.1 7 UnabletoStarttheWorkbench....................................................................................................10 References................................................................................................................................................................10 ©2009–2011SINTEF 2 2 INTRODUCTION SiSaSStudio[5]isanEclipsebundlethatenablestogeneratecode(Java[2]amongothers)from variousmodels,especiallyfromUMLmodels[7].ThecorepartoftheSiSaSstudio[1]isbasically asetofmodeltransformations,writteninMOFScript[4],andsomeadditionalJavaclassesthat ensuretheproperintegrationofthesetransformationswithintheEclipseGUI[1]. TheSiSaSstudiobundlealsoincludesotherEclipsepluginsthatsupportcommondevelopment tasksassociatedwiththemodel‐drivenmethodology:UMLmodellingusingthePapyrusUML Editor[10],MathematicalmodellingusingtheOpenModelicaplugin[8,12],etc.Althoughthese pluginsarebundledwithintheSiSaSStudio,theymustbeconsideredasthirdpartyelements, andaremaintainedseparately. ThisdocumentisaimedatpeoplewhoneedtoextendortofixbugsintheSiSaSStudio.It isNOTaimedatpeoplewhomerelywanttouseit.PleaseconsulttheUserGuide[5]in thiscase. TheaimofthisdocumentistointroducethetoolsetusedtodevelopandextendtheSiSaSStudio. Thefirstsectiondescribespreciselyhowtosetupyourdevelopmentenvironment.Thesecond partthenbrieflydescribesthearchitectureofthemodeltransformationsthathavebeen developedintheSiSaSStudio. 3 SETTINGUPYOURDEVELOPMENTENVIRONMENT 3.1 INSTALLINGTHEDEVELOPMENTTOOLSET BelowarethemainstepstofollowinordertoconfigureyourSiSaSdevelopmentenvironment. ThesestepsareonlyrelevanttosetuptheenvironmentneededtodeveloptheSiSaSStudioitself, andisNOTrelevantifyouonlywanttouseit. 1. JavaDevelopmentKit(JDKv1.6).ThefirstelementtoinstallistheJavaDevelopment Kit[2],whichincludestheJavavirtualmachine,andtheJavadevelopmenttools.Thisis neededtoruntheEclipseIDE.ItisworthtonotethatyoucanrunEclipseovernewer versionoftheJDK(e.g.,onJava7)butthecodeoftheSiSaSStudioitselfrequiresJava6. 2. Eclipse‐Modelling(v3.5.x,socalled"Galileo",NOThigher).Thesecondelementneeded isadistributionoftheEclipseModellingFramework.Werecommendtheversion3.5as someofthepluginsthatwillbelateraddedrequirethisspecificversion. 3. PapyrusUML[10]istheUMLeditoradvocatedbytheSiSaSstudio.Itcomesasan EclipsepluginandcanbeinstalledinEclipseusingtheupdatesite. 4. MOFScript[4](v1.4orhigher)istheprogramminglanguageusedtowritethemodel transformationsthatareprovidedbytheSiSaSStudio.TheMOFScriptlanguagecomesas wellasanEclipsepluginprovidingsyntaxhighlightingandautomaticcompletion.The MOFScriptplugincanbeinstalledusingtheupdatesite. 5. SVNPlugin.YoumightwantaswelltoinstallanadditionalSVNplugin,whichpermitsto directlycommitthechangesyoumadetotheSiSaSsourcecodeintotheSiSaSrepository (Sotheybecomeavailableforotherdevelopers).Basically,twomainpluginsare ©2009–2011SINTEF 3 available:SubclipseandSubversive.Bothofthemarecompatiblewiththerestofthe toolset. 3.2 CHECKINGOUTTHESISASSTUDIOSOURCECODE ThesourcecodeoftheSiSaSstudioisavailableonaSVNserver.Youcanretrieveitfromthe followingURL: https://cloud.catenda.no/svn/sisas/sisasstudio/ IfyouhavenotyetgotpropercredentialtoaccesstheSiSaSStudio,youmaycontacttheCatenda staffinchargeoftheSVNrepository. 4 ARCHITECTUREOFTHESISASSTUDIO 4.1 ASETOFECLIPSEPLUGINS TheSiSaSStudioismadeoffourmainEclipseplugins: ProfilesplugindefinesasetofUMLprofilesthat canbeusedwithintheSiSaSStudio,e.g.,SoaML, migration,etc. TransformationspluginbindstheEclipse graphicalinterfacestothesetofMoFScript transformations.Basically,itdrivesthe MoFScriptengineandselectstheproper transformationaccordingtotheUIevents. ProjectTemplatesprovidestheuserwiththe abilitytodefinehisownprojecttemplates, assumingthatthetransformationheneeds alreadyexistintheSiSaSStudio. Featurespluginisbasicallyacollectionof Figure4.1 Dependenciesbetweenthe pluginsthatcomposetheSiSaSStudio plugins.Itisusedasafaçade/containerbythe EclipseFramework.Itdependsonthetwoother plugins SitepluginpermitstocreateanEclipseupdate‐sitefromwhichtheSiSaSStudioplugin canberetrievedandinstall.ItisusedwhenbuildingtheSiSaSStudiobundle. ThedependenciesbetweenthesefourpluginsaredepictedbyFigure1,aside.Forabetter understandingoftheEclipsepluginframework,theinterestedreadermayconsult[5]. 4.2 INTERNALARCHITECTURE TheSiSaSStudioisbuiltasasortof"productline"ofmodelstransformations.Thebasicideais toseparatetheideadefinitionofspecificmodeltransformationsfromtheircombinationto generatecomplexcodestructures(e.g.,Mavenprojects).Tothisend,theSiSaSstudiolettheuser define"projecttemplates"whereshespecifiestheorganizationofthecodesheneedsintermsof adirectorystructurecontainingthe"to‐generate"artefacts. 4.2.1 TEMPLATEPROJECTS ©2009–2011SINTEF 4 edmodels(b bundleinasseparateEcllipsemodelss)whichcap pture TemplatteProjectsaareseparate theorgaanizationofthecodetogenerate,esspeciallycom mplexstructuresincluddingmultiple generateedartefacts.Althoughttheusercandefineisow wnprojecttemplates,thheSiSaSStudio comesw withasetofpredefinedprojecttem mplatessupp porting(POJOprojects,O OGC/WPSp projects, EJB,etc.) Figure4.2 2TheProjecttTemplateme etamodel Asshow wnbyFiguree4.2,"projeccttemplatess"basicallyd describead directorystrructureinwhichthe neededartefactscanbeplacesoastoensu uretheprop pergenerateofthecomppleteproject. dsetofgeneeratedartefaacttypes.Ad ddinganew wtypeofgen nerated Projectttemplatedeefinesafixed artefactrequirestomodifythemodelofprrojecttempllateandhen ncetoregeneerateandre ecompile dEclipseplu ugin. thecodeetherelated 4.2.2 MODELTRAANSFORMATTIONS TheSiSaaSStudioisactuallyare egistryofm odelstransfformation,e eachofthem mtargetinga aspecific typeofggeneratedarrtefact.Whileinstantiattingaspecifficprojectte emplate,theesisasstudio omerely triggertthetransformationrelevantforeacchgenerated dartefacts. Eachtraansformationregistered dintheSiSaaSStudiomaadeoftwoparts:generaatorsandch heckers. Generattorsareinch hargeofeffe ectivelygeneeratingthecode,where easacheckeerisinchargeof verifyingwhetherthemodelgivenasinputtbytheusercontainssufficientinfformationfo orthe generato ortorunproperly. Itisworrthtonotethattheconssistencybettweenagen neratorand ditsrelated dcheckerissthe responssibilityofth hetransform mationdeveeloper. Figure4 4.3,belowilllustrateshowmodeltraansformatio onregistered dwiththeSiiSaSStudio.The SiSaSStudioexplicitlydeclaresthetransfo rmationsth hatareavaila able,includiingthetwo separateeMofScriptfilesandthe etypeartefaacttheygen nerate.Invok kingthe"insstantiate"w willthen passthrroughthetemplatethat triggerthe generationofeacharte efactusingthherelevant transforrmation(orraiseanerrrorifnottraansformation nareavailab bletohandlleoneofthe e artefact)). TEF ©2009–2011SINT 5 class Class Model «singleton» SisasStudio + instantiate(Model, Template) : void 1..* «enumeration» ArtifactType +transformations 1..* +definedTypes +outputType JSF_BEANS SQL_DATA 1 JAVA_EJB JSF_PAGES XML_SERVICES_CONFIG +config 1 Transformation - description: String name: String + apply(Model) : void +checker 1 1 Preferences +implementation MofScript - path: String + process(Model) : void Figure4.3InternalrepresentationofmodeltransformationwithintheSiSaSStudio RegisteringanewtransformationintheSiSaSStudioishenceamattersofafewlines,inthe initializationoftheSisasStudiosingletonclass.Inthefollowingcodesnippet,weregisteredone transformationthataimsatgeneratedPOJO(plainoldjavaprojects). private SisasStudio() { transfoRegistry = new Hashtable<ArtifactType, Transformation>(); // ---// ADD BELOW ANY TRANFORMATION THAT MUST BE AVAILABLE BY DEFAULT OR ANY // NEW TRANSFORMATION THAT MUST BE SUPPORTED // List<Transformation> transformations = new LinkedList<Transformation>(); transformations.add(new Transformation("UML TO POJO", ArtifactType.POJO_JAVA_CODE, "uml_to_pojo/plain_java_checker.m2t", "uml_to_pojo/plain_java_generator.m2t")); transformations.add(new Transformation("UML to MAVEN POM FOR Java", ArtifactType.POJO_MAVEN_POM_FILE, "uml_to_pojo/maven_pom_checker.m2t", "uml_to_pojo/maven_pom_generator.m2t")); // ---// ... } 4.2.3 EXISTINGMODELTRANSFORMATIONS Scope Storage Persistence Business ©2009–2011SINTEF Input UML UML UML RequiredProfile SoaML/Persistence SoaML/Persistence SoaML Output XSDSchema SQLSchemaCreation SQLSchemaDeletion JavaClasses(POJO) JEE6– EntityBeans JEE6– EntityManagers WS‐ WSDL WS– Skeleton(JAX‐WS) JEE6–StatelessSessionBeans 6 Presentaation Develop pment Import//Export JSPWebSeerviceClientt UML JSFSampleeSite UML Noone MavenJEE EProjectStru ucture Noone Enterp prise ECoreModdel Archittect Table1.Overviewo ofthemodelltransformaationsinclud dedintheSiiSaSStudio wn in the taable above, the t SiSaS Sttudio contaiins a set of model trannsformationss that be As show applied on various models, mainly on UM ML model, extended e with adhoc pprofiles. The source nsiscontain nedintothe"transformation"plugiin. codeofaallthesetraansformation Thetran nsformation nsincludediintheSiSaS Studiocanb bedividedin nthreecateegories.Thefirstone containss all the traansformatio ons that prooduce "prod duction" code, i.e., codde that will be later integratted in the final f applica ation. In Taable 1, this first catego ory correspponds to first set of transforrmation (including sto orage, persisstence, bussiness and presentatio n). The seccond set containsstransformaationsthatg generateco deusefulto ocompilean ndpackagetthefinalapp plication: basicallyy the transformation generating g the Maven Infrastructture. Finallyy, the last group g of transforrmationcon ntaintransfo ormationsprrovidingcon nversionme eansbetweeendifferentttypesof models(e.g.,converrtingEnterp priseArchiteectModelin ntoECoremo odels). 5 TU UTORIAL LS 5.1 DEVELOPINGGANEWTRANSFORM R MATION Agoodp practicetoffollowwhile eaddingnew w transforrmationsinttotheSiSaSStudio,istoofirstdevelo op andtesttthetransfo ormationaside,andthen ntointegratte itwithin ntheSiSaSSStudio.Thissectiondesccribesbrieflly theseco ondparts,naamelyhowtointegra ateanew transfo ormation.IInterestedreadersmay yreferto[4] foradditionaldetaillsabouthow wtowriteM MoFScript transforrmation. Thisdon neisthreem mainsteps: 1. D Developtheegeneratorr,aseparateeMoFScript Figure e5.1Structu tureofthe ttransformattionthatgen neratesthen neededcode Transformationp plugin 2. D Developtheechecker,aMoFScript ttransformattionthatche eckswhetheeragivenUM ML m modelispro operregardingtherequ uirementsofthegenera ator 3. R Registeran newtransforrmationinth heSiSaSStu udiothatbin ndtogethertthegenerato or,the ccheckerand dthetypeoffartefactthaatisproduced. 5.1.1 DEVELOPIN NGTHEGEN NERATORSCR CRIPT Thecod desnippetbeelowisaverrysimplem modeltransfo ormationtha atmerelyprrintsawelco oming messageeontheEcliipseconsole e.ItiswritteenintheMO OFScriptlang guage[4].T Thenextpara agraph showsh howtointeggratethistra ansformation nintotheSiiSaSStudio. TEF ©2009–2011SINT 7 /** * Test.m2t * Test whether the MoFScript Engine is ready for use. * * date: 29/10/2011 * * author: Franck Chauvel - SINTEF */ texttransformation FooGenerator (in mdl:"http://www.eclipse.org/uml2/2.1.0/UML") { mdl.Model::main () { println("This is a test:" ) println("If you can read this message, MofScript is operational") } } Thefilethatcontainsthiscodesnippetmustbeplacedintothetransformationdirectoryofthe transformationplugin(oroneofitssubdirectories).Forthesakeofconsistentorganisation,we recommendtoplaceitin"transformations/uml_to_foo/foo_generator.m2t" 5.1.2 DEVELOPINGTHECHECKERSCRIPT Thefollowingcodesnippetsillustrateshowtowriteachecker,andespeciallyhowtoreturna valuesthatcanbeunderstoodintheJavalayeroftheSiSaSStudio.Inthissimpleexample,the checkeractuallychecksnothing,andrepliesthatthemodelsconformstherequirements, sendingthe"CHECKER_PASS"message. import "../configuration.m2t" texttransformation FooChecker(in mdl:"http://www.eclipse.org/uml2/2.1.0/UML") { mdl.Model::main () { print(CHECKER_PASS); } } This file must be saved in the transformation plugin in a separated directory (for sake of organization).Forinstance,wemayplaceitinto"transformation/uml_to_foo/for_checker.m2t" 5.1.3 REGISTERINGTHETRANSFORMATION ThesecondstepaimsatwritingapieceofJavacodethatregistersthegeneratorandthechecker intheSiSaSStudio.Hence,instantiatingtemplatescontainingtherelatedgeneratedartefacttype willhencetriggertheexecutionofboththegeneratorandthechecker.Thecodeexcerptbelow illustrates such a registration: In the initialization of the SisasStudio singleton class (org.sintef.no.sisas.transformation.SisasStudio), we add in the internal registry a new transformationpointtothechecker,thegenerator,andtheartefacttype. private SisasStudio() { transfoRegistry = new Hashtable<ArtifactType, Transformation>(); // ---// ADD BELOW ANY TRANFORMATION THAT MUST BE AVAILABLE BY DEFAULT OR ANY // NEW TRANSFORMATION THAT MUST BE SUPPORTED // List<Transformation> transformations = new LinkedList<Transformation>(); transformations.add(new Transformation("UML TO POJO", ArtifactType.POJO_JAVA_CODE, "uml_to_pojo/plain_java_checker.m2t", "uml_to_pojo/plain_java_generator.m2t")); transformations.add(new Transformation("UML to Foo", ©2009–2011SINTEF 8 ArtifactType.FOO_FILE, "uml_to_foo/foo_checker.m2t", "uml_to_foo/foo_generator.m2t")); // ---// ... } 5.2 ADDINGANEWPROJECTTEMPLATE Additionally,newprojecttemplatescanbedefined,andhavetobedefinedtosupportnewtypes of generated artefacts. The SiSaS studio includes a plugin which permit to build new project templates. To do so, just create a new Project template file, as describe the structure of the resultingsourcedirectory,asshownonFigure4.2below: Figure5.2Definingnewprojecttemplatewiththeprojecttemplateeditor Once the desired template has been designed and saved in a ".projecttemplate" file, it can be eitherregisteredduringtheSiSaSStudiosession,usingtheSiSaSPopupmenu,orcopyintothe SiSaS Studio installation, so as to pertain for later sessions. The transformation plugin has a specific directory named "template" which is automatically browsed when the SiSaS Studio starts, and each template placed there will be loaded and hence accessible in the SiSaS popup menu. 5.3 CREATINGABUNDLEOFTHESISASSTUDIO CreatingabundleofEclipsethatcontainsanupdatedversionoftheSiSaSStudioisasimple process: 1. GototheupdatesiteoftheSiSaSStudioplugin(project org.sintef.no.sisas.transformations.update).Thenrebuildtheupdatesite,buildright clickingonPDEtool,andselecting"Buildsite". 2. Installabrandneweclipsedistributionandinstalltheneededpluginsinside,MoFScript, Papyrus,etc. ©2009–2011SINTEF 9 3. StarttheneweclipseandselectFile‐>InstallNewSoftware.Selectalocalrepository,and providethelocationoftheupdatesitedirectory(namelytheplacewhereyoucheckout theorg.sintef.no.sisas.transformation.update).ThiswillinstalltheSisasStudiointhe newEclipsedistribution. 4. ExitEclipseandcreateanarchivecontainingtheneweclipsedistribution(justzipthe eclipsedirectory).Yourbundleisready,enjoy 6 TROUBLESHOOTING ThissectionsummarizescommonproblemsthatmayoccurwhiledevelopingtheSiSaSStudio. 6.1.1 UNABLETOSTARTTHEWORKBENCH WhenrunningtheSiSaSStudioasanEclipseWorkbench,youmayget"Couldnotreserveenough spaceforobjectheap.CouldnotcreatetheJavavirtualmachine."Thismightbeduetoamismatch betweentheJVMusedbyEclipsewhenitcreatesanewworkbench,andtheoneprovidedby youroperatingsystem.Makesurethatthelatteroneisa32bitversion.Ifyouareusinga64bits system,youmayneedtoinstallanolderversionoftheJVM,optimizedfor32bitssystems. 7 REFERENCES 1. EricClayberg,DanRubel.EclipsePlug‐ins.4thedition,Addison‐Wesley,2009. 2. BruceEckel,ThinkinginJava.4thedition,PrenticeHall,2006. 3. KitoD.Mann.JavaServerFacesinAction.ManningPublications,2005. 4. JonOldevik.MOFScriptUserGuide.Unpublished.Version1.0,February2011.(available athttp://eclipse.org/gmt/mofscript/) 5. GøranK.Olsen.SiSaSStudio–UserManual.Volume1,2and3.Unpublished. 6. ObjectManagementGroup(OMG).ServiceorientedarchitectureModelingLanguage (SoaML)‐SpecificationfortheUMLProfileandMetamodelforServices(UPMS)SoaML. ptc/2009‐12‐09.2009.(seehttp://www.omg.org/spec/SoaML/) 7. ObjectManagementGroup(OMG).UnifiedModelingLanguage–Superstructure(v2.4.1). formal/2011‐08‐06.2011.(seehttp://www.uml.org/) 8. OpenModelica.(Seehttp://www.openmodelica.org/) 9. DebuPanda,RezaRahmanandDerekLane.EJB3inAction.ManningPublications,2007. 10. PapyrusUML.(Seehttp://www.eclipse.org/modeling/mdt/papyrus/) 11. ChrisRichardson.POJOinAction:DevelopingEnterpriseApplicationswithLightweight Frameworks.ManningPublications,2006 12. WladimirSchamai.ModelicaModelingLanguage(ModelicaML):AUMLProfilefor Modelica.(availableathttp://www.openmodelica.org/index.php/developer/tools/134) 13. Sonatype.Maven:TheDefinitiveGuide.O'ReillyMedia.September2008. 14. EricVanderVlist.XMLSchemas:TheW3C'sObject‐OrientedDescriptionsforXML.O'Reilly Media.June2002. ©2009–2011SINTEF 10