Difference between revisions of "Pattern Based Artifact Creation"

Latest revision as of 12:06, 3 October 2008

< To: Tigerstripe Extension Points

• Full name : org.eclipse.tigerstripe.workbench.base.creationPatterns

• Purpose : The creationPatterns extension is used to specify the items that appear in the list of "new Artifacts" that can be created from the dropdown list in the Tigerstripe toolbar, from the Tigerstripe Explorer and from class diagrams. All of the existing creation options are specified using this extension point.

In the extension, there are some properties of the tool athat will appear in teh ui - such as the Label, the icon, a description and so on. In addition the extension specifes the type of artifact to be created using the tool, and you may optionally specify additional details about the artifact that will be created - this could be used to apply some default Stereotypes, some specific Annotations, even to add "mandatory" fields to all Entities.

Finally the extension allows for some additional wizard validation logic to be used to prevent or warn users if the values they enter in a wizard do not conform to expectations.

When used with the customNaming, customAuditRule, customArtifactMetadata and labelDecoartor extension points the look and feel of Tigerstripe can be changed significantly to be steered towards a specifc user domain.

(Note the creationPatterns can also be used to specify Project creation patterns).

• Usage : The actual extension defines two elements. The first (patternDefintion) is for the definition of a new pattern, and the second (disabledPattern) allows patterns to be disabled. This latter point is useful if you want to disable a builtin pattern, thus forcing users to always use one of your patterns.

A disabledPattern just requires the id of the pattern to be disabled. The builtin patterns are named org.eclipse.tigerstripe.workbench.base.xxxx where xxx is ManagedEntity, Association, Project etc. (Note upper case first letter).

A patternDefintion element requires a patternFile attribute and has an optional validator_class attribute.

The patternFile is really the key to the pattern - it is an XML file that must conform to the schema http://org.eclipse.tigerstripe/xml/tigerstripeCreationPattern/v1-0 - this can be found in the org.eclipse.tigerstripe.workbench.base plugin in the resources/schemas folder. Key components of the patternFile are :

• patternName - This is the Id by which you can disable any pattern.
• uiLabel - This is the text that will be used in the diagranm palette or toolbar tooltip.
• patternType - This must be one of project, relation or node. A project pattern is hopefully self explanatory. Relation patterns should be used for creating Associations, AssociationClasse and Dependencies only. Relation patterns do not appear in the diagram palette, but can be used when dragging and dropping connections in a diagram. Conversely, node patterns do appear in the palette.
• iconPath - This should point to the icon to be used in the toolbar/palette fro this pattern.
• disabledIconPath - Not used at present.
• index - This is used to control the order in which items appear in the various locations (palette, toolbar etc). The builtin artifact patterns have index numbers from 1000 to 2000 at intervals of 100. Lower numbers will appear at the top of the list. Any patter without an index will be added to the end of the list as it is discovered ( this could result in an unpredictable order if you have creationPatterns defined in more than one plugin).
• description - This text will appear in the wizard as a hint to a user.
• artifact/project - this is a definition of the artifact to be created. It reuses the tigerstripeExportFormat http://org.eclipse.tigerstripe/xml/tigerstripeExport/v2-0 (NB at version 2.0). This can be found in the same location as the pattern schema above.

NOTE: When using the creationPatterns in conjunction with a customNaming rule, any item in the artifact (eg fields, association ends etc) that have an empty name attribute will use the customNaming rule. If a name is provided in the pattern then that will be used.

A validator_class if specified must point to a class that implements IPatternBasedWizardValidator. For a node Pattern, the validator class validate(..) method will be called using the pattern, name, package and superClass form the wizard. In the case of a Relation Pattern, the ends are sent as well. (A Validator makes no real sense for project Patterns). The validator should return an array of IStatus with any problems. You can use this approach to enforce naming rules (but remember a user can always change the names later, so a customAudit rule is still recommended here).

• Example :

This is an example of the plugin.xml entry for a creationPattern

  <extension
        point="org.eclipse.tigerstripe.workbench.base.creationPatterns">
     <patternDefinition
           patternFile="resources/patterns/PreliminaryEntity.xml"
           validator_class="org.eclispe.tigerstripe.entityValidator">
     </patternDefinition>
  .....

The top of pattern xml File might look like this

 <pattern:creationPattern patternName="com.test.PreliminaryAssoc"
          uiLabel="Preliminary Association"
          patternType="relation"
          iconPath="resources/patterns/icons/entity_te_p.gif"
          disabledIconPath="resources/patterns/icons/entity_te_p.gif"
          xmlns:pattern="http://org.eclipse.tigerstripe/xml/tigerstripeCreationPattern/v1-0"
          xmlns:ts="http://org.eclipse.tigerstripe/xml/tigerstripeExport/v2-0">
   <pattern:description>Create a new Preliminary Association</pattern:description>
   <ts:artifact name="com.cisco.wobble"
                artifactType="org.eclipse.tigerstripe.workbench.model.deprecated_.IAssociationArtifact"
                isAbstract="true"
   ....

The validate method for use in a Relation Pattern could look like this:

       /**
        * name should be pattern XxxxToYyyyConnection where the end names are A=Xxxx and Z=Yyyy 
        */
       public IStatus[] validate(IRelationPattern pattern, String artifactName,
               String artifactPackage, String extendedArtifactFQN, String endFQN,
               String endFQN2) {
          StatusInfo status = new StatusInfo();
          String aEndName = endFQN.substring(endFQN.lastIndexOf(".")+1);
          String zEndName = endFQN2.substring(endFQN2.lastIndexOf(".")+1);
          String goodName = aEndName+"To"+zEndName+"Connection";
          if (! artifactName.equals(goodName)){
               status.setWarning("Name should be pattern XxxxToYyyyConnection where the end names are A=Xxxx and Z=Yyyy");
               IStatus[] allStatuses = new IStatus[1];
               allStatuses[0] = status;
               return allStatuses;
          }
          return null;
       }

NOTE that the StatusInfo class is in the org.eclipse.jdt.ui plugin.