Jump to: navigation, search

Difference between revisions of "Tigerstripe Plugin Miscellany"

(New page: {{backlink|Tigerstripe_Tutorials}} This section includes some handy reference documents that are useful when putting together plugins. =Default Velocity context contents= <h2>Collection...)
 
(Default Velocity context contents)
 
(22 intermediate revisions by 3 users not shown)
Line 5: Line 5:
 
=Default Velocity context contents=
 
=Default Velocity context contents=
  
<h2>Collections</h2>
+
'''Collections'''
<blockquote><p>There are a number of <b>Collections</b> in the context that allows access to sets of artifacts. These <b>Collections</b> are described in the following table and would typically be accessed as follows: <i>#foreach ($artifact in $artifacts)</i></p>
+
<p>There are a number of <b>Collections</b> in the context that allows access to sets of artifacts. These <b>Collections</b> are described in the following table and would typically be accessed as follows: <i>#foreach ($artifact in $artifacts)</i></p>
  
 
<table border=1 cellspacing=0 cellpadding=0 width=619>
 
<table border=1 cellspacing=0 cellpadding=0 width=619>
Line 13: Line 13:
 
   <td width=199 valign=top>Type</td>
 
   <td width=199 valign=top>Type</td>
 
   <td width=620 valign=top>Contents</td>
 
   <td width=620 valign=top>Contents</td>
 +
<td width=620 valign=top>Note</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
   <td><b>$artifacts</b></td><td>Collection&lt;IArtifact&gt;</td><td> All artifacts within this project.</td>  
+
   <td><b>$artifacts</b></td><td>Collection&lt;IArtifact&gt;</td><td> All artifacts within this project.</td><td></td>  
 
</tr>
 
</tr>
 
<tr>
 
<tr>
   <td><b>$entities</b></td><td>Collection&lt;IManagedEntityArtifact&gt;</td><td> All Managed Entity artifacts within this project.</td>  
+
   <td><b>$entities</b></td><td>Collection&lt;IManagedEntityArtifact&gt;</td><td> All Managed Entity artifacts within this project.</td><td></td>  
 
</tr>
 
</tr>
 
<tr>
 
<tr>
   <td><b>$datatypes</b></td><td>Collection&lt;IDatatypeArtifact&gt;</td><td> All Datatype artifacts within this project.</td>  
+
   <td><b>$datatypes</b></td><td>Collection&lt;IDatatypeArtifact&gt;</td><td> All Datatype artifacts within this project.</td><td></td>  
 
</tr>
 
</tr>
 
<tr>
 
<tr>
   <td><b>$events</b></td><td>Collection&lt;IEventArtifact&gt;</td><td> All Event artifacts within this project.</td>  
+
   <td><b>$events</b></td><td>Collection&lt;IEventArtifact&gt;</td><td> All Event artifacts within this project.</td><td></td>  
 
</tr>
 
</tr>
 
<tr>
 
<tr>
   <td><b>$enums</b></td><td>Collection&lt;IEnumArtifact&gt;</td><td> All Enumeration artifacts within this project.</td>  
+
   <td><b>$enumerations</b></td><td>Collection&lt;IEnumArtifact&gt;</td><td> All Enumeration artifacts within this project.</td><td></td>  
 
</tr>
 
</tr>
 
<tr>
 
<tr>
   <td><b>$exceptions</b></td><td>Collection&lt;IExceptionArtifact&gt;</td><td> All Exception artifacts within this project.</td>  
+
   <td><b>$exceptions</b></td><td>Collection&lt;IExceptionArtifact&gt;</td><td> All Exception artifacts within this project.</td><td></td>  
 
</tr>
 
</tr>
 
<tr>
 
<tr>
   <td><b>$queries</b></td><td>Collection&lt;IQueryArtifact&gt;</td><td> All Query artifacts within this project.</td>  
+
   <td><b>$queries</b></td><td>Collection&lt;IQueryArtifact&gt;</td><td> All Query artifacts within this project.</td><td></td>  
 
</tr>
 
</tr>
 
<tr>
 
<tr>
   <td><b>$updateProcedures</b></td><td>Collection&lt;IUpdateProcedureArtifact&gt;</td><td> All Update Procedure artifacts within this project.</td>  
+
   <td><b>$updateProcedures</b></td><td>Collection&lt;IUpdateProcedureArtifact&gt;</td><td> All Update Procedure artifacts within this project.</td><td></td>  
 
</tr>
 
</tr>
 
<tr>
 
<tr>
   <td><b>$associations</b></td><td>Collection&lt;IAssociationArtifact&gt;</td><td> All Association artifacts within this project.</td>  
+
   <td><b>$associations</b></td><td>Collection&lt;IAssociationArtifact&gt;</td><td> All Association artifacts within this project.</td><td></td>  
 
</tr>
 
</tr>
 
<tr>
 
<tr>
   <td><b>$associationClasses</b></td><td>Collection&lt;IAssociationClassArtifact&gt;</td><td> All Association Class artifacts within this project.</td>  
+
   <td><b>$associationClasses</b></td><td>Collection&lt;IAssociationClassArtifact&gt;</td><td> All Association Class artifacts within this project.</td><td></td>  
 
</tr>
 
</tr>
 
<tr>
 
<tr>
   <td><b>$sessions</b></td><td>Collection&lt;ISessionArtifact&gt;</td><td> All Session Facade artifacts within this project.</td>  
+
   <td><b>$sessions</b></td><td>Collection&lt;ISessionArtifact&gt;</td><td> All Session Facade artifacts within this project.</td><td></td>  
 
</tr>
 
</tr>
 
<tr>
 
<tr>
   <td><b>$allArtifacts</b></td><td>Collection&lt;IAbstractArtifact&gt;</td><td> All artifacts within this project, plus those in Referenced Projects and Dependent Modules.</td>  
+
   <td><b>$allArtifacts</b></td><td>Collection&lt;IAbstractArtifact&gt;</td><td> All artifacts within this project, plus those in Referenced Projects and Dependent Modules.</td><td></td>  
 
</tr>
 
</tr>
 
<tr>
 
<tr>
   <td><b>$allEntities</b></td><td>Collection&lt;IManagedEntityArtifact&gt;</td><td> All Managed Entity artifacts within this project, plus those in Referenced Projects and Dependent Modules.</td>  
+
   <td><b>$allEntities</b></td><td>Collection&lt;IManagedEntityArtifact&gt;</td><td> All Managed Entity artifacts within this project, plus those in Referenced Projects and Dependent Modules.</td><td></td>  
 
</tr>
 
</tr>
 
<tr>
 
<tr>
   <td><b>$allDatatypes</b></td><td>Collection&lt;IDatatypeArtifact&gt;</td><td> All Datatype artifacts within this project, plus those in Referenced Projects and Dependent Modules.</td>  
+
   <td><b>$allDatatypes</b></td><td>Collection&lt;IDatatypeArtifact&gt;</td><td> All Datatype artifacts within this project, plus those in Referenced Projects and Dependent Modules.</td><td></td>  
 
</tr>
 
</tr>
 
<tr>
 
<tr>
   <td><b>$allEvents</b></td><td>Collection&lt;IEventArtifact&gt;</td><td> All Event artifacts within this project, plus those in Referenced Projects and Dependent Modules.</td>  
+
   <td><b>$allEvents</b></td><td>Collection&lt;IEventArtifact&gt;</td><td> All Event artifacts within this project, plus those in Referenced Projects and Dependent Modules.</td><td></td>  
 
</tr>
 
</tr>
 
<tr>
 
<tr>
   <td><b>$allEnums</b></td><td>Collection&lt;IEnumArtifact&gt;</td><td> All Enumeration artifacts within this project, plus those in Referenced Projects and Dependent Modules.</td>  
+
   <td><b>$allEnumerations</b></td><td>Collection&lt;IEnumArtifact&gt;</td><td> All Enumeration artifacts within this project, plus those in Referenced Projects and Dependent Modules.</td><td></td>  
 
</tr>
 
</tr>
 
<tr>
 
<tr>
   <td><b>$allExceptions</b></td><td>Collection&lt;IExceptionArtifact&gt;</td><td> All Exception artifacts within this project, plus those in Referenced Projects and Dependent Modules.</td>  
+
   <td><b>$allExceptions</b></td><td>Collection&lt;IExceptionArtifact&gt;</td><td> All Exception artifacts within this project, plus those in Referenced Projects and Dependent Modules.</td><td></td>  
 
</tr>
 
</tr>
 
<tr>
 
<tr>
   <td><b>$allQueries</b></td><td>Collection&lt;IQueryArtifact&gt;</td><td> All Query artifacts within this project, plus those in Referenced Projects and Dependent Modules.</td>  
+
   <td><b>$allQueries</b></td><td>Collection&lt;IQueryArtifact&gt;</td><td> All Query artifacts within this project, plus those in Referenced Projects and Dependent Modules.</td><td></td>  
 
</tr>
 
</tr>
 
<tr>
 
<tr>
   <td><b>$allUpdateProcedures</b></td><td>Collection&lt;IUpdateProcedureArtifact&gt;</td><td> All Update Procedure artifacts within this project, plus those in Referenced Projects and Dependent Modules.</td>  
+
   <td><b>$allUpdateProcedures</b></td><td>Collection&lt;IUpdateProcedureArtifact&gt;</td><td> All Update Procedure artifacts within this project, plus those in Referenced Projects and Dependent Modules.</td><td></td>  
 
</tr>
 
</tr>
 
<tr>
 
<tr>
   <td><b>$allAssociations</b></td><td>Collection&lt;IAssociationArtifact&gt;</td><td> All Association artifacts within this project, plus those in Referenced Projects and Dependent Modules.</td>  
+
   <td><b>$allAssociations</b></td><td>Collection&lt;IAssociationArtifact&gt;</td><td> All Association artifacts within this project, plus those in Referenced Projects and Dependent Modules.</td><td></td>  
 
</tr>
 
</tr>
 
<tr>
 
<tr>
   <td><b>$allAssociationClasses</b></td><td>Collection&lt;IAssociationClassArtifact&gt;</td><td> All Association Class artifacts within this project, plus those in Referenced Projects and Dependent Modules.</td>  
+
   <td><b>$allAssociationClasses</b></td><td>Collection&lt;IAssociationClassArtifact&gt;</td><td> All Association Class artifacts within this project, plus those in Referenced Projects and Dependent Modules.</td><td></td>  
 
</tr>
 
</tr>
 
<tr>
 
<tr>
   <td><b>$allSessions</b></td><td>Collection&lt;ISessionArtifact&gt;</td><td> All Session Facade artifacts within this project, plus those in Referenced Projects and Dependent Modules.</td>  
+
   <td><b>$allSessions</b></td><td>Collection&lt;ISessionArtifact&gt;</td><td> All Session Facade artifacts within this project, plus those in Referenced Projects and Dependent Modules.</td><td></td>
 +
</tr>
 +
<tr>
 +
  <td><b>$moduleArtifacts</b></td><td>Collection&lt;IAbstractArtifact&gt;</td><td> All artifacts within the current Model/Module.</td><td>Only available in Model Based rules</td>
 +
</tr><tr>
 +
  <td><b>$moduleEntities</b></td><td>Collection&lt;IManagedEntityArtifact&gt;</td><td> All Managed Entity artifacts within the current Model/Module.</td><td>Only available in Model Based rules</td>
 +
</tr>
 +
<tr>
 +
  <td><b>$moduleDatatypes</b></td><td>Collection&lt;IDatatypeArtifact&gt;</td><td> All Datatype artifacts within the current Model/Module.</td><td>Only available in Model Based rules</td>
 +
</tr>
 +
<tr>
 +
  <td><b>$moduleEvents</b></td><td>Collection&lt;IEventArtifact&gt;</td><td> All Event artifacts within the current Model/Module.</td><td>Only available in Model Based rules</td>
 +
</tr>
 +
<tr>
 +
  <td><b>$moduleEnumerations</b></td><td>Collection&lt;IEnumArtifact&gt;</td><td> All Enumeration artifacts within the current Model/Module.</td><td>Only available in Model Based rules</td>
 +
</tr>
 +
<tr>
 +
  <td><b>$moduleExceptions</b></td><td>Collection&lt;IExceptionArtifact&gt;</td><td> All Exception artifacts within the current Model/Module.</td><td>Only available in Model Based rules</td>
 +
</tr>
 +
<tr>
 +
  <td><b>$moduleQueries</b></td><td>Collection&lt;IQueryArtifact&gt;</td><td> All Query artifacts within the current Model/Module.</td><td>Only available in Model Based rules</td>
 +
</tr>
 +
<tr>
 +
  <td><b>$moduleUpdateProcedures</b></td><td>Collection&lt;IUpdateProcedureArtifact&gt;</td><td> All Update Procedure artifacts within the current Model/Module.</td><td>Only available in Model Based rules</td>
 +
</tr>
 +
<tr>
 +
  <td><b>$moduleAssociations</b></td><td>Collection&lt;IAssociationArtifact&gt;</td><td> All Association artifacts within the current Model/Module.</td><td>Only available in Model Based rules</td>
 +
</tr>
 +
<tr>
 +
  <td><b>$moduleAssociationClasses</b></td><td>Collection&lt;IAssociationClassArtifact&gt;</td><td> All Association Class artifacts within the current Model/Module.</td><td>Only available in Model Based rules</td>
 +
</tr>
 +
<tr>
 +
  <td><b>$moduleSessions</b></td><td>Collection&lt;ISessionArtifact&gt;</td><td> All Session Facade artifacts within the current Model/Module.</td><td>Only available in Model Based rules</td>  
 
</tr>
 
</tr>
 
</table>
 
</table>
Line 84: Line 117:
 
<p><b>Note</b> : The contents of the collections above may be reduced by the application of Contract facets.</p>
 
<p><b>Note</b> : The contents of the collections above may be reduced by the application of Contract facets.</p>
  
 +
'''Other contents'''
  
<a name="artifacts"></a><p><b>$artifact</b> (IAbstractArtifact)</p>
+
<p><b>$artifact</b> (IAbstractArtifact)</p>
 
   
 
   
 
<p>In an <b>Artifact Rule</b>, this is set to the current artifact. That is on each iteration of the rule over a different artifact in the <b>Tigerstripe</b> project, this will have a different value. If a specific artifact type was selected in the rule (the <i>AnyArtifact</i> option has not been selected), the actual artifact will be of that type ( eg <i>IManagedEntityArtifact</i>) and the object can be cast to the precise type for access to the specifics of that artifact type.</p>
 
<p>In an <b>Artifact Rule</b>, this is set to the current artifact. That is on each iteration of the rule over a different artifact in the <b>Tigerstripe</b> project, this will have a different value. If a specific artifact type was selected in the rule (the <i>AnyArtifact</i> option has not been selected), the actual artifact will be of that type ( eg <i>IManagedEntityArtifact</i>) and the object can be cast to the precise type for access to the specifics of that artifact type.</p>
  
 +
<p><b>$module</b> (ITigerstripeModelProject)</p>
 +
 +
<p>In an <b>Model based Rule</b>, this is set to the current model/module. That is on each iteration of the rule over a different model referenced by a <b>Tigerstripe</b> project, this will have a different value.
  
 
<p><b>$pluginConfig</b> (IPluginConfig)</p>
 
<p><b>$pluginConfig</b> (IPluginConfig)</p>
Line 145: Line 182:
 
<p><b>$pluginDir</b> (String)</p>
 
<p><b>$pluginDir</b> (String)</p>
  
<p>The path to the root of the plugin when it is deployed. This is useful for gaining access to files that have been included with the deployed plugin. See <b><a href="includedFiles.html">Including Files in the deployed Plugin</a></b> for more details.</p></blockquote>
+
<p>The path to the root of the plugin when it is deployed. This is useful for gaining access to files that have been included with the deployed plugin.</p>
 +
 
 +
<p><b>$diagramGenerator</b> (IDiagramGenerator)</p>
 +
 
 +
<p> A handle to a tool to query diagrams available, and to generate image files.</p>
 +
 
 +
=Using an Expander=
 +
 
 +
An <b>Expander</b> is a utility included in the Default Velocity context that you use to <i>explode</i> references. Uses for an <b>Expander</b> are as follows:
 +
 
 +
 
 +
*<b>Specifying Output files</b>: In many situations, your plug-in needs model attributes to know where to place your output file based on the current <b>Artifact</b>. The default <b>Expander</b> facilitates this behaviour.
 +
*<b>Abbreviated syntax</b>: Within a template, you have access to plug-in <b>Global Properties</b>, <b>Model Attributes</b>, and <b>Project Properties</b>.
 +
 
 +
Expander Variable Syntax
 +
<blockquote><ul>
 +
  <li><b><i>${project.Version}</i> , <i>${project.ModelId}</i> and <i>${project.Name}</i></b>: This variable will replace your <b>ModelId</b> <b>Version</b> and <b>Name</b> properties of your current project. <b>Note</b> It is recommended to use ModelId in preference to Name.</li>
 +
  <li><b><i>${artifact.Name}, ${artifact.Package} and ${artifact.Path}</i></b>: This variable displays a <i>name</i>, <i>package</i>, and a <i>path-like</i> String for your package (eg <i>com/mycompany/myPackage</i>) of the current <b>Artifact</b>. This variable is only useful for <b>Artifact</b> based rules.</li>
 +
  <li><b><i>${ppProp.propertyName}</i></b>: This variable displays the <i>value</i> of the <b>Global Property</b> named <i>propertyName</i> in your plug-in.</li>
 +
  <li><b><i>${model.attributeName}</i></b>: This variable displays the <i>value</i> of the attribute named <i>attributeName</i> in your model. <b>Note:</b> The <b>Model</b> should be replaced with the name of the model set in the rule specification.</li>
 +
</ul></blockquote>
 +
 
 +
Expander Usage
 +
<p>When defining a rule, use the direct syntax. The whole filename string is automatically passed to the default <b>Expander</b>. For example, for an output file the defintion might look like the following:
 +
*<i>${artifact.Path}/${artifact.Name}.java</i>
 +
Within your template, use <i>$exp.expandVar(expanderVariable)</i>, where <i>expanderVariable</i> complies with the syntax above. For example, <i>$exp.expandVar("${ppProp.xmlDirectory}")</i>.
 +
 
 +
=Runtime settings=
 +
 
 +
There are a number of runtime settings associated with a plugin. These settings are important when the plugin runs - ie after it is deployed. All of these setting are accessed via the "Runtime" tab of the plugin project descriptor.
 +
 
 +
*Logging
 +
 
 +
You can enable logging for a plugin, by checking the "Enable logging for this plugin". The log file that is created will be in the project output directory ("target/tigerstripe.gen" by default), and will have the name as entered in the "Log file" text box. When first deployed the log level will take the value that is set in the plugin descriptor, but users can override this in their individual projects to a higher or lower level as required. It therefore makes sense to keep the default level "high" and only turn the logging up when debugging.
 +
 
 +
Log entries can be made from templates or from java code in your plugin;
 +
 
 +
In a template use the following syntax :
 +
 
 +
    $pluginLog.logTrace("A trace message")
 +
 
 +
In java code you can use:
 +
 
 +
    PluginLog.logDebug(mylogString);
 +
    PluginLog.LogError(mylogString,exception); - This version will include the stack trace for a throwable.
 +
 
 +
Log entries can be Trace, Debug, Info, Warning or Error. Call the apporopriate method as required.
 +
 
 +
*ClasspathEntries
 +
A runtime dependency is an existing JAR file needed by your plug-in at execution. A runtime may need to be added to a plug-in for use by :
 +
Model Class: A model class may have imports from several external JAR files.
 +
Artifact Filter: A filter class may have imports from several external JAR files.
 +
Velocity Context Definitions: When specifying a <b>Velocity Context Definition</b> in a <b>Rule</b>, the class may be in a JAR file that needs to be available at runtime. This allows you to access third party JARs from the template. There are many third party utilities that you may find useful, such as those from <b>apache</b>.
 +
 
 +
Complete the following procedure to add a JAR file to your plug-in project.
 +
In the Classpath Entries scetion, click on "Add" and naviagte to the required JAR. The JAR file <b>must</b> be in your plug-in project. Note that if you have added a jar to the classpath, you do not need to also mark it as an "Included File" (see next section).
 +
 
 +
*Included files
 +
 
 +
Sometimes your plugin execution may depend upon a file at runtime (eg a schema that is used to validate a configuration file). In this case you need to include the file in the runtime build so that it is available at runtime.
 +
Simply check the required file (it must be in your plugin project) in the tree view, and it will be included in the plugin "build" when the plugin is deployed. You cannot change the relative location of a file - ie it will have  the same path as in your plugin project.

Latest revision as of 05:18, 23 April 2011

< To: Tigerstripe_Tutorials

This section includes some handy reference documents that are useful when putting together plugins.

Default Velocity context contents

Collections

There are a number of Collections in the context that allows access to sets of artifacts. These Collections are described in the following table and would typically be accessed as follows: #foreach ($artifact in $artifacts)

Collection Name Type Contents Note
$artifactsCollection<IArtifact> All artifacts within this project.
$entitiesCollection<IManagedEntityArtifact> All Managed Entity artifacts within this project.
$datatypesCollection<IDatatypeArtifact> All Datatype artifacts within this project.
$eventsCollection<IEventArtifact> All Event artifacts within this project.
$enumerationsCollection<IEnumArtifact> All Enumeration artifacts within this project.
$exceptionsCollection<IExceptionArtifact> All Exception artifacts within this project.
$queriesCollection<IQueryArtifact> All Query artifacts within this project.
$updateProceduresCollection<IUpdateProcedureArtifact> All Update Procedure artifacts within this project.
$associationsCollection<IAssociationArtifact> All Association artifacts within this project.
$associationClassesCollection<IAssociationClassArtifact> All Association Class artifacts within this project.
$sessionsCollection<ISessionArtifact> All Session Facade artifacts within this project.
$allArtifactsCollection<IAbstractArtifact> All artifacts within this project, plus those in Referenced Projects and Dependent Modules.
$allEntitiesCollection<IManagedEntityArtifact> All Managed Entity artifacts within this project, plus those in Referenced Projects and Dependent Modules.
$allDatatypesCollection<IDatatypeArtifact> All Datatype artifacts within this project, plus those in Referenced Projects and Dependent Modules.
$allEventsCollection<IEventArtifact> All Event artifacts within this project, plus those in Referenced Projects and Dependent Modules.
$allEnumerationsCollection<IEnumArtifact> All Enumeration artifacts within this project, plus those in Referenced Projects and Dependent Modules.
$allExceptionsCollection<IExceptionArtifact> All Exception artifacts within this project, plus those in Referenced Projects and Dependent Modules.
$allQueriesCollection<IQueryArtifact> All Query artifacts within this project, plus those in Referenced Projects and Dependent Modules.
$allUpdateProceduresCollection<IUpdateProcedureArtifact> All Update Procedure artifacts within this project, plus those in Referenced Projects and Dependent Modules.
$allAssociationsCollection<IAssociationArtifact> All Association artifacts within this project, plus those in Referenced Projects and Dependent Modules.
$allAssociationClassesCollection<IAssociationClassArtifact> All Association Class artifacts within this project, plus those in Referenced Projects and Dependent Modules.
$allSessionsCollection<ISessionArtifact> All Session Facade artifacts within this project, plus those in Referenced Projects and Dependent Modules.
$moduleArtifactsCollection<IAbstractArtifact> All artifacts within the current Model/Module.Only available in Model Based rules
$moduleEntitiesCollection<IManagedEntityArtifact> All Managed Entity artifacts within the current Model/Module.Only available in Model Based rules
$moduleDatatypesCollection<IDatatypeArtifact> All Datatype artifacts within the current Model/Module.Only available in Model Based rules
$moduleEventsCollection<IEventArtifact> All Event artifacts within the current Model/Module.Only available in Model Based rules
$moduleEnumerationsCollection<IEnumArtifact> All Enumeration artifacts within the current Model/Module.Only available in Model Based rules
$moduleExceptionsCollection<IExceptionArtifact> All Exception artifacts within the current Model/Module.Only available in Model Based rules
$moduleQueriesCollection<IQueryArtifact> All Query artifacts within the current Model/Module.Only available in Model Based rules
$moduleUpdateProceduresCollection<IUpdateProcedureArtifact> All Update Procedure artifacts within the current Model/Module.Only available in Model Based rules
$moduleAssociationsCollection<IAssociationArtifact> All Association artifacts within the current Model/Module.Only available in Model Based rules
$moduleAssociationClassesCollection<IAssociationClassArtifact> All Association Class artifacts within the current Model/Module.Only available in Model Based rules
$moduleSessionsCollection<ISessionArtifact> All Session Facade artifacts within the current Model/Module.Only available in Model Based rules

Note : The contents of the collections above may be reduced by the application of Contract facets.

Other contents

$artifact (IAbstractArtifact)

In an Artifact Rule, this is set to the current artifact. That is on each iteration of the rule over a different artifact in the Tigerstripe project, this will have a different value. If a specific artifact type was selected in the rule (the AnyArtifact option has not been selected), the actual artifact will be of that type ( eg IManagedEntityArtifact) and the object can be cast to the precise type for access to the specifics of that artifact type.

$module (ITigerstripeModelProject)

In an Model based Rule, this is set to the current model/module. That is on each iteration of the rule over a different model referenced by a Tigerstripe project, this will have a different value. <p>$pluginConfig (IPluginConfig)

The plug-in reference gives access to the values of the plug-in Global Properties. For example, $pluginRef.Properties.getProperty(“propname”)

$tsProjectHandle (ITigerstripeModelProject)


Contains information about the Tigerstripe project such as the version, name, and Copyright notice of your project. This information is held in ProjectDetails object, for example $tsProjectHandle.getIextProjectDetails().getProperty("copyrightNotice","")

$runtime (TigerstripeRuntime)

The runtime object contains information about the Tigerstripe installation so you can check the version of Workbench. For example, $runtime.getProperty("tigerstripe.feature.version")

$sessionManager (IArtifactManagerSession)

The artifact manager session is used to gain access to artifacts in the project, or in project dependencies. For example, if you have a String that should be an FQN of another artifact, you can access that artifact using $sessionManager.getIArtifactByFullyQualifiedName($fqnString)

$util (VelocityContextUtil)

A utility class that contains a few simple String handling utilities.

stripExternalQuotes(String arg0)removes leading and trailing quotation (”) characters.
unCapitalize(String arg0)Turns the first character to lower-case.
capitalize(String arg0)Turns the first character to upper-case.
getLastSegment(String arg0)Returns the part of the String after the last “.” character.
toLowerCase(String arg0)Returns entire Strings in lower-case.
toUpperCase(String arg0)Returns entire Strings in upper-case.

Example use : $util.capitalize($attribute.Name)

$exp (IExpander)

A utility that can be used to simplify access to some model, plug-in, or project variables. The currentArtifact or currentModel must be set prior to use for artifact or model attributes, but the pluginRef is pre-set.

Example use : $exp.expandVar($model.TargetNamespace)

$templateName (String)

The local pathname of the template that is currently being used. For example, templates/wsdm/type.vm.

$pluginDir (String)

The path to the root of the plugin when it is deployed. This is useful for gaining access to files that have been included with the deployed plugin.

$diagramGenerator (IDiagramGenerator)

A handle to a tool to query diagrams available, and to generate image files.

Using an Expander

An Expander is a utility included in the Default Velocity context that you use to explode references. Uses for an Expander are as follows:


  • Specifying Output files: In many situations, your plug-in needs model attributes to know where to place your output file based on the current Artifact. The default Expander facilitates this behaviour.
  • Abbreviated syntax: Within a template, you have access to plug-in Global Properties, Model Attributes, and Project Properties.

Expander Variable Syntax

  • ${project.Version} , ${project.ModelId} and ${project.Name}: This variable will replace your ModelId Version and Name properties of your current project. Note It is recommended to use ModelId in preference to Name.
  • ${artifact.Name}, ${artifact.Package} and ${artifact.Path}: This variable displays a name, package, and a path-like String for your package (eg com/mycompany/myPackage) of the current Artifact. This variable is only useful for Artifact based rules.
  • ${ppProp.propertyName}: This variable displays the value of the Global Property named propertyName in your plug-in.
  • ${model.attributeName}: This variable displays the value of the attribute named attributeName in your model. Note: The Model should be replaced with the name of the model set in the rule specification.

Expander Usage

When defining a rule, use the direct syntax. The whole filename string is automatically passed to the default Expander. For example, for an output file the defintion might look like the following:

  • ${artifact.Path}/${artifact.Name}.java
Within your template, use $exp.expandVar(expanderVariable), where expanderVariable complies with the syntax above. For example, $exp.expandVar("${ppProp.xmlDirectory}").

Runtime settings

There are a number of runtime settings associated with a plugin. These settings are important when the plugin runs - ie after it is deployed. All of these setting are accessed via the "Runtime" tab of the plugin project descriptor.

  • Logging

You can enable logging for a plugin, by checking the "Enable logging for this plugin". The log file that is created will be in the project output directory ("target/tigerstripe.gen" by default), and will have the name as entered in the "Log file" text box. When first deployed the log level will take the value that is set in the plugin descriptor, but users can override this in their individual projects to a higher or lower level as required. It therefore makes sense to keep the default level "high" and only turn the logging up when debugging.

Log entries can be made from templates or from java code in your plugin;

In a template use the following syntax :

   $pluginLog.logTrace("A trace message")

In java code you can use:

   PluginLog.logDebug(mylogString);
   PluginLog.LogError(mylogString,exception); - This version will include the stack trace for a throwable.

Log entries can be Trace, Debug, Info, Warning or Error. Call the apporopriate method as required.

  • ClasspathEntries

A runtime dependency is an existing JAR file needed by your plug-in at execution. A runtime may need to be added to a plug-in for use by : Model Class: A model class may have imports from several external JAR files. Artifact Filter: A filter class may have imports from several external JAR files. Velocity Context Definitions: When specifying a Velocity Context Definition in a Rule, the class may be in a JAR file that needs to be available at runtime. This allows you to access third party JARs from the template. There are many third party utilities that you may find useful, such as those from apache.

Complete the following procedure to add a JAR file to your plug-in project. In the Classpath Entries scetion, click on "Add" and naviagte to the required JAR. The JAR file must be in your plug-in project. Note that if you have added a jar to the classpath, you do not need to also mark it as an "Included File" (see next section).

  • Included files

Sometimes your plugin execution may depend upon a file at runtime (eg a schema that is used to validate a configuration file). In this case you need to include the file in the runtime build so that it is available at runtime.

Simply check the required file (it must be in your plugin project) in the tree view, and it will be included in the plugin "build" when the plugin is deployed. You cannot change the relative location of a file - ie it will have the same path as in your plugin project.