= Acceleo Launcher Documentation =

== Properties Files ==
Properties files are standard Java ".properties" files that can be loaded by an Acceleo generator to customize a generation. In order to use a properties file in your generator, you have to reference it in the method "getProperties()" of your Java launcher and then to use the loaded properties in your generator.

In the method "getProperties()", you have to return a collection of the path of the properties files that you want to use. There are four ways to referenced a properties files:

[[Image:../images/acceleo_launcher/propertiesFiles.png|center]]

* You can just return the name of the properties files, example: "default_0.properties". With this, Acceleo will look for any file named default_0.properties in the generator and load the properties from the first file found with this name.

* You can also enter the path of a specific properties file located in your generator, example: "/org/eclipse/acceleo/module/sample/properties/default_1.properties". With this path, Acceleo will look for a properties files with the name "default_1.properties" in the folder "/org/eclipse/acceleo/module/sample/properties/" in your generator.

* You can also referenced a properties files located in another Eclipse plugin by using the url of the properties files in the other plugin. In order to do that, you need to construct the path with the following convention: "platform:/plugin/<plugin name>/<path in the plugin>". Example: "platform:/plugin/org.eclipse.module.sample2/org/eclipse/acceleo/module/sample2/default_3.properties". The other plugin needs to be deployed in Eclipse or it needs to be a dependency of the first generator.

* Finally, you can also use an absolute path in the filesystem as a reference to a properties file. Example: "C:\Users\sbegaudeau\Desktop\default_4.properties". You can also use the utility method org.eclipse.acceleo.engine.utils.AcceleoEngineUtils#getPropertiesFilesNearModel to compute the absolute path of the properties files in the same folder as the model. With this method, we can have the path of the file default_5.properties.

In order to use a properties files located in an Eclipse plugin (all Acceleo generators are Eclipse plugins) you have to make sure that the file is included in the build of your generator, by either placing it in a source folder or by adding it to your build in the build.properties file located at the root of your generator.

Now that you know how to load a properties file, you need to use it in your generator. In order to do that, you can use one of the four following operations:

[[Image:../images/acceleo_launcher/propertiesFilesUse.png|center]]

* "getProperty('myProperty')" will return the value of the property with the key "myProperty". Several properties files can have properties that share the same key, only the first one found will be returned with this method.

* "getProperty('default_1.properties', 'myProperty')" will return the value of the property with the key "myProperty" from the file "default_1.properties").

* "getProperty('myProperty', Sequence{'my name'})" will return the value of the property with the key "myProperty" parameterized with the value in the sequence.

* "getProperty('default_3.properties', 'myProperty', Sequence{'my name'})" will return the value of the property with the key "myProperty" parameterized with the value in the sequence from the file "default_3.properties".

You can see the result of the generation in the following screenshot.

[[Image:../images/acceleo_launcher/propertiesFilesResult.png|center]]


== Package Registration ==
Acceleo is a code generator that uses EMF model(s) as an input. EMF models are an organized structure of concepts but those concepts needs to be defined in a metamodel. As an example, an UML model manipulates the concepts defined in the UML metamodel (class, property, operation, visibility, etc.). Acceleo modules are defined by using those same concepts as you can see it in the following picture.

When you are launching your generator, Acceleo needs to have the metamodel to understand the model that you are loading. For that, you need to register the root package of the concepts that you are using in the metamodel. By default, Acceleo will register the metamodel defined in the modules but in some complex cases, you may have to customize the package registered.

If you are using the Acceleo Plugin Runner in the launch configuration (right click on a main module then select Run As an Acceleo Application), Acceleo will use EMF and Eclipse to find the package from your metamodel needed by your model. This behavior will work in most cases and it is the recommended behavior to use. Once you are using the Java Application Runner, Acceleo will behave as if we are outside of Eclipse and you will have to register your metamodels manually. To register a metamodel, you need to provide two informations: the uri of the metamodel and the instance of its package.

[[Image:../images/acceleo_launcher/registerPackage.png|center]]


== Resource Factory Registration ==
We have seen in the previous paragraphs how the models used by Acceleo are manipulating concepts defined in a metamodel. For example, an UML model manipulates the concepts defined in the UML metamodel (class, property, operation, visibility, etc.). We have also seen that Acceleo needs to load the metamodel to understand the concepts in the input models and in the generator. We also have to load the model to use it for the generation. The model may be located in a file with any kind of extension serialized in any form (textual DSL, XML, binary, etc.) and Acceleo cannot know how to load the file unless it is using the basic ".ecore" extension for standard EMF based models or unless you are using an extension that another Eclipse plugin has already registered in EMF but Acceleo will not prevent you from loading a file with a custom extension but you will need to register for that a resource factory.

You can see in the following picture, the piece of code necessary to manually register a resource factory to be able to open ".uml" models.

[[Image:../images/acceleo_launcher/registerResourceFactory.png|center]]


