Tigerstripe Plugin Miscellany

< 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
$artifacts	Collection<IArtifact>	All artifacts within this project.
$entities	Collection<IManagedEntityArtifact>	All Managed Entity artifacts within this project.
$datatypes	Collection<IDatatypeArtifact>	All Datatype artifacts within this project.
$events	Collection<IEventArtifact>	All Event artifacts within this project.
$enumerations	Collection<IEnumArtifact>	All Enumeration artifacts within this project.
$exceptions	Collection<IExceptionArtifact>	All Exception artifacts within this project.
$queries	Collection<IQueryArtifact>	All Query artifacts within this project.
$updateProcedures	Collection<IUpdateProcedureArtifact>	All Update Procedure artifacts within this project.
$associations	Collection<IAssociationArtifact>	All Association artifacts within this project.
$associationClasses	Collection<IAssociationClassArtifact>	All Association Class artifacts within this project.
$sessions	Collection<ISessionArtifact>	All Session Facade artifacts within this project.
$allArtifacts	Collection<IAbstractArtifact>	All artifacts within this project, plus those in Referenced Projects and Dependent Modules.
$allEntities	Collection<IManagedEntityArtifact>	All Managed Entity artifacts within this project, plus those in Referenced Projects and Dependent Modules.
$allDatatypes	Collection<IDatatypeArtifact>	All Datatype artifacts within this project, plus those in Referenced Projects and Dependent Modules.
$allEvents	Collection<IEventArtifact>	All Event artifacts within this project, plus those in Referenced Projects and Dependent Modules.
$allEnumerations	Collection<IEnumArtifact>	All Enumeration artifacts within this project, plus those in Referenced Projects and Dependent Modules.
$allExceptions	Collection<IExceptionArtifact>	All Exception artifacts within this project, plus those in Referenced Projects and Dependent Modules.
$allQueries	Collection<IQueryArtifact>	All Query artifacts within this project, plus those in Referenced Projects and Dependent Modules.
$allUpdateProcedures	Collection<IUpdateProcedureArtifact>	All Update Procedure artifacts within this project, plus those in Referenced Projects and Dependent Modules.
$allAssociations	Collection<IAssociationArtifact>	All Association artifacts within this project, plus those in Referenced Projects and Dependent Modules.
$allAssociationClasses	Collection<IAssociationClassArtifact>	All Association Class artifacts within this project, plus those in Referenced Projects and Dependent Modules.
$allSessions	Collection<ISessionArtifact>	All Session Facade artifacts within this project, plus those in Referenced Projects and Dependent Modules.
$moduleArtifacts	Collection<IAbstractArtifact>	All artifacts within the current Model/Module.	Only available in Model Based rules
$moduleEntities	Collection<IManagedEntityArtifact>	All Managed Entity artifacts within the current Model/Module.	Only available in Model Based rules
$moduleDatatypes	Collection<IDatatypeArtifact>	All Datatype artifacts within the current Model/Module.	Only available in Model Based rules
$moduleEvents	Collection<IEventArtifact>	All Event artifacts within the current Model/Module.	Only available in Model Based rules
$moduleEnumerations	Collection<IEnumArtifact>	All Enumeration artifacts within the current Model/Module.	Only available in Model Based rules
$moduleExceptions	Collection<IExceptionArtifact>	All Exception artifacts within the current Model/Module.	Only available in Model Based rules
$moduleQueries	Collection<IQueryArtifact>	All Query artifacts within the current Model/Module.	Only available in Model Based rules
$moduleUpdateProcedures	Collection<IUpdateProcedureArtifact>	All Update Procedure artifacts within the current Model/Module.	Only available in Model Based rules
$moduleAssociations	Collection<IAssociationArtifact>	All Association artifacts within the current Model/Module.	Only available in Model Based rules
$moduleAssociationClasses	Collection<IAssociationClassArtifact>	All Association Class artifacts within the current Model/Module.	Only available in Model Based rules
$moduleSessions	Collection<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.