Creating and Editing Rules

Rules determine the actual behaviour of a plug-in. There are two types of Rules:

• Global Rules: These rules are executed once per generation of a project.
• Artifact Rules: These rules will be executed once per matching Artifact.

You can add or remove Global and Artifact rules through the Rules section of the Plugin Project Descriptor. Complete the following procedure to add or remove rules.

To Add or Remove plug-in Rules

1. Click Add or Remove in the Plugin Project Descriptor. You set the rule properties through the same editor.

Note: Changes to rules will only take effect when you re-deploy the plug-in. For more information about deploying your plug-in, refer to Deploy and Test a plugin.

Common Rule properties

Both Global and Artifact rules share the following common defintions:

• Enabled: This is useful during plug-in development. It allows you to enable and disable rules without deleting their definitions. Only rules that are enabled will be deployed.
• Name: The name for the rule. The rule name is only used within the plug-in project and is never seen by the plug-in user.
• Description: The description is only visible within the plug-in project.
• Template: The template that is used for each execution of the rule. Templates must reside the templates directory of the plug-in project. Refer to, Creating/Editing Velocity templates for more information on how to specify template contents.

  Note: More than one rule can use the same template.

• Suppress Empty Files: If set to true, then all empty files (files of size 0) are removed at the end of the rule run.
• Overwrite Files: If set to true, then any existing files with the same name as the output file are overwritten. Setting this definition to false will prevent any files created by this rule from overwriting existing files.
• Include artifacts from dependencies and referenced projects.: When set to true, the rule will run over artifacts in the local project PLUS those that are in referenced projects or dependencies. This can greatly increase the volume of output so should be treated with caution.
• Output File Name: The filename of the file created as a result of execution of this rule. The filename specified will be interpreted as a relative path with it's root at the target directory that is specified in the Tigerstripe Project.

  Note: Be careful to specify a unique name for each rule or artifact combination such as: ${artifact.Name}.out. For more information on the use of the ${xxx} patterns, refer to Using an expander.

• Velocity Context Definitions: The Velocity context defines what is available to templates at execution. This includes details of the model and some other useful Tigerstripe objects. Refer to Default Velocity context contents for more information. It is possible to add further entries to the context to simplify the template design; For example, by writing some java code to do some complex and frequently used string manipulation task. Velocity context defintions have two attributes:
  • Name: The name to be used from within the template (when prepended with a $ - eg $util)
  • Class: The java class that contains the methods to be accessible from the template. These will normally be java src located in the src directory of your plug-in project, or could be classes within a runtime dependency.
• Velocity Macros: Velocity supports the use of macros (also called velocimacros). These are additional templates that you can use to similify templates by encapsulating commonly used template snippets. You are able to specify that macros are loaded in the Velocity context by specifying the file which contains the macro defintions. This file must be in the templates directory of your plug-in project.

Additional Properties for Artifact Based Rules

• Artifact Type: An artifact rule that is executed once for every Artifact in your project of the type defined. From the drop-down list, select a specific Artifact type, or choose the Any Artifact rule to ensure the rule will run for every Artifact in your project, irrespective of type. An Artifact type must be selected.
• Wrapper Class: You can optionally specify a Wrapper class. The Wrapper class can enrich or simplify the information being processed in the template. By using references to the Wrapper instead of the Artifact inside the template, the template has access to all methods of the Wrapper. A Wrapper is a Java class that must implement the IArtifactWrapper interface specified in the Tigerstripe external API. The Artifact being processed is passed to that class using the setIArtifact method which Tigerstripe automatically calls, passing the current Artifact. Some examples of method usage within a Wrapper are as follows:
  • Reformat data. For example, to translate a package name to a directory path name, such as translating org.eclipse.tigerstripe.models as org/eclipse/tigerstripe/models.
  • Look up data in other related Artifacts. For example, if the type of an attribute is an Enumeration, you can examine the Base Type of that Enumeration (that is, int or String).
  • Perform complex manipulations that would be difficult or complex in Velocity.
  • Refer to Using wrappers in templates for more information on creating and using Wrappers.
• Wrapper Class Name: References to the Wrapper class from the template are made using the name provided. The default value is wrapper.
• Artifact Filter: You can optionally specify a Filter class. The set of artifacts that are passed to the template during execution can be limited by defining a filter. The set of artifacts are determined by selecting artifacts of the Artifact Type and then by applying the filter. A filter is a Java class that must implement the IArtifactFilter interface specified in the Tigerstripe external API. Refer to, Using Filters in rules for more information on creating and using filters.