Builtin Models

• Since creating a builtin doesn’t make sense without having a model, just create an actifsource project name ch.actifsource.tutorial.builtin with some resources.

• YourClass is a NamedResource

• Right click on the project ch.actifsource.tutorial.builtin in the navigator to open the context menu.
• Go into the submenu Configure and click on Convert to Plug-in Projects…

• Check the checkbox in front of ch.actifsource.tutorial.builtin
• Click Finish
• This will convert the project however there will be some error and warning needed to be fixed.

• Right click on the Actifsource classpath container
• Go into the submenu Build Path and select Remove from Build Path

• Double click on the MANIFEST.MF to open the manifest editor

• Go to the build.properties tab
• Click on the yellow warning sign left to the source.. line
• Select Add src-gen/ to the source.. build entry, if it is not already there.
• This will add the src-gen folder to the source build when exporting a plugin including source code. This is not a requirement to export the actifsource model as builtin however we want to get rid of this warning
• There may be more warning depending on your eclipse configuration, you may fix them the same way if you like.

• Activate the Dependencies tab
• Click on Add...
• Enter ch.actifsource.core in the textbox to start filtering
• Select ch.actifsource.core
• Click on Add

• If you do the conversion on an existing project, you may need to add additional dependencies. You might see this by looking into the generated files, the actifsource project dependencies and the java build path.

• When exporting a model as plugin, you have to make sure that you have a plugin dependency to all required projects. This means all required projects need to be converted into plugins.

• Before defining exports you need to have access to the required extension point declarations. This is done by adding a dependency to ch.actifsource.environment.

• Go back to the Dependencies tab in the manifest editor
• Click on Add…
• Enter ch.actifsource.en to start filtering
• Select ch.actifsource.environment
• Click on Add

• Activate the Extension tab
• Click on Add…
• Select ch.actifsource.core.RegisterModel
• Click on Finish

• You don’t need to specify an ID and Name for the extension, we leave it empty.
• Open the context menu by right click on the extension
• Go into the Submenu New and select ResourceFolder

• Select the empty (ResourceFolder) entry

• Enter the project relative path asrc to the resource folder

• You may define different resource folders as defined in your actifsource project configuration. This is useful if you want to write templates inside your plugin to generated code and don’t want to deliver the template and related resources. Just put the templates in a separate resourcefolder which is not registered in the extension.

• Switch to Build tab
• Check the asrc Folder in the binary build
• This is needed to include the asrc in the binary release, if you fail to do so the plugin won’t contain any resources.

• A builtin provides a way to define dependencies to actifsource model defined in a plugin inside a non-plugin projects. This step is not required if you want to use your model only in plugin projects.

• Go to the Overview tab
• Make sure you, that the plugin ID is ch.actifsource.tutorial.builtin

• Switch back to Extension tab
• Click on Add…
• Select ch.actifsourc.environment.RegisterBuiltin
• Click on Finish

• Select the predefined (Builtin) entry
• Define a name EXAMPLE_BUILTIN
• The other options are not used in this example:
  • defaultBuiltin If true, the builtin will be added by default whenever a new actifsource project is created and must be explicitly removed.
  • isExtendable If true, other plugins are allowed to define a builtin with the same name. This will result in merging the dependencies together. You may find this useful, if you provide extensions to your builtin, which you want to have automatically applied as soon as a plugin is installed.

• Select the predefined (Plugin) entry
• Enter the pluginId of your plugin ch.actifsource.tutorial.builtin
• This is not required to be the plugin defining extension point, this might be useful if you don’t want to have a plugin dependency to ch.actifsource.environment in the plugin providing the resourcefolder.

• In order to deliver a plugin you need to create an eclipse feature containing the plugin and a updatesite where the feature is published

• Open the menu File
• Go into the submenu New
• Select Project…

• Select Feature Project
• Go to the next page.

• Enter the project name ch.actifsource.builtin.feature for the feature
• As you can see, the default feature ID is set to the project name.
• Press next to step further

• Select the plugin ch.actifsource.tutorial.builtin
• Exit the wizard using Finish

• Eclipse will ask you if it should open the associated Plug-in Development perspective
• Answer this question by click on No

• After finishing the wizard of feature editor will open automatically.
• Switch to the Dependencies tab
• Press Add Feature…
• Select ch.actifsource
• Hit OK
• This will add actifsource enterprise as dependency, disallowing to installing the feature without having actifsource installed. As a result eclipse will automatically select actifsource enterprise for installation if the location of actifsource is known and contacting other updatesites is enabled (see later)
• In order to make the feature visible on the updatesite, you need to create a category otherwise eclipse will hide the feature in the categorized view of the installation wizard.

• Open the File menu
• Select New
• Click on Other…

• Select Category Definition
• Press the Next button

• Select your feature ch.actifsource.tutorial.builtin.feature
• This is only the location of the file, this doesn’t associate the feature with the category.
• Leave the filename unchanged and press Finish

• Press New Category
• Enter the id actifsource.tutorial.category
• Enter the name Tutorial Category

• Select the category
• Press Add Feature…
• Select the your feature ch.actifsource.tutorial.builtin.feature
• Press the Add button
• At this point we are ready to export the feature to an updatesite

• Right click on the feature.xml
• Select Export…

• Select Deployable features
• Click on Next

• Select Options
• Click on Browse…

• Select category.xml
• Close with OK

• If you don’t want to increase the micro version each time you export, it is recommended to set a qualifier. Failing to change the version or qualifier will cause eclipse to not overwrite an existing on the update site.
• Check the Qualifier replacement checkbox
• Enter the current date and time in reverse order
• Be careful if the major, minor and micro version of two versions are the same, a text comparison between the qualifiers is done. This means write the date the other way around will cause eclipse to select the wrong latest version.

• Go back to the Destination tab
• Enter the location of the updatesite, we use $HOME\updateSite
• Depending on your installation you may have to choose a different directory, where you have write access.
• Press Finish

• For this step you need to have installation rights on the running eclipse. To get around this, you may download a new eclipse from www.eclipse.org and test it on a writable location.

• Go Help
• Select Install New Software….

Install the example feature

• Enter the location of the updatesite, we used file:/c:/tmp/updateSite
• Eclipse requires the use of the file-URL. In order to distribute the updateSite on the web, just upload the content of the directory to your webserver.
• Check Contect all update sites during install to find required software
• This option uses the required feature defined in the feature where we added the ch.actifsource.
• Press Next

• This dialog will show addition features if eclipse found missing feature required for installation. However you will see an error message if any feature is missing that wasn’t found. This happens when eclipse doesn’t know an updatesite containing the feature. Another reason for installation failures are conflicts between installed versions, you may need to uninstall conflicting plugins first or try to update all at once using the Check For Update dialog
• Press Next

• Read the license(s)
• Accept the license
• Press Finish
• Eclipse will start downloading the required features and plugins from the updatesites

• Before starting the installation of a feature, eclipse will check if the feature and the plugins are signed. This option can be activate in the export wizard, however this goes beyond this tutorial. Simply accept all certificates by clicking on the Trust Selected button
• Since we know from the verification dialog, that only our feature is going to be installed, safely click OK

• Press Yes to restart

• Now we can use the builtin. You have two options, creating a plugin dependency or adding the builtin in the actifsource preferences

• Select File
• Go to New
• Click on Project…

• Enter a project name for the usage, we use ch.actifsource.tutorial.builtin.usage
• Switch to the Next page

• Activate the Built-in Dependencies tab
• Click on Add Builtin…
• Select EXAMPLE_BUILTIN
• Hit OK
• Finish the wizard and you are ready to go
• As mentioned when defining the builtin this step can be omitted if you have defined builtin with the defaultBuiltin-attribute set to true.