Revision as of 07:39, 15 January 2008

< To: Tigerstripe_Tutorials

Annotations can be used to add additional information to a model element over and above that provided by default in Tigerstripe Workbench.

Annotations must be defined in the current profile before they can be used. This tutorial walks you through the definition of an Annotation named Persistence, its application to an Artifact, and how it can be used in a Plugin.

Before starting this tutorial, ensure that you are familiar with profile. For more information, refer to Tigerstripe_Profile_Tutorial.

Creating your Persistence Annotation

Complete the following procedure to create a sample annotation.

To create a Persistence Annotation:

1. Click the Annotations tab in your profile.
2. Name your annotation
   • For this example, name your annotation Persistence.
3. Enter the version number for your annotation and enter a short description.
4. Save your changes.

Defining the scope of your Persistence annotation.

Before you can use your Persistence annotation in your project, you first need to define its scope. The scope defines the type of model element to which the annotation can be applied. The scope can be defined as one of the follwoing elements:

• Any Method - This means that the annotation can be applied to any Method in any artifact in the model.
• Any Attribute - This means that the annotation can be applied to any Attribute in any artifact in the model.
• Any Label - This means that the annotation can be applied to any Attribute in any artifact in the model.
• Any Argument - This means that the annotation can be applied to any Argument of any Method in any artifact in the model.

In addition the annotation can be applied to Artifacts ofs pecific type.

IMPORTANT NOTE: The inclusion of an Artifact Type (eg Managed Entity) and another qualifier (eg Any Method) does not mean that an annotation can only be applied to methods of Managed Entities. What it does mean is that the annotation can be applied to any Method on any Artifact, AND it can also be applied to Managed Entity Artifacts (at the artifact level).

To define the scope for your Persistence annotation:

1. In the Annotations tab, select the Persistence annotation and locate the Scope section.
2. Select the scope you want to define with your annotation or leave the option unselected if you want to exclude that option from your annotation.
   • For this example, select ManagedEntity Artifact.
3. Save your profile.

Defining attributes for your Persistence annotation.

After you define the scope of your Persistence annotation, you may define one or more Annotation attributes. Annotation attributes are additional fields that appear on your annotation when applied to a model element within a Tigerstripe Project - the Annotation attributes can take a value that is chosen by the user. Note that annotations do not require Annotation attributes - you can use annotations without any Annotation attributes, simply by applying them to model elements and making their presence (rather than value) of significance.

You can include the following Annotation attributes types:

• String - Allows you to create a text field in which the user must enter information.
• Option - Allows you to create a checkbox which the user may select true or false values.
• List - Allows you to create a list of options from which the user must select.

Complete the following procedure to define Annotation attributes for your Persistence annotation.

To define attributes:

1. In the Annotations tab, select the Persistence annotation and locate the Attributes section.
2. Click Add. The Annotation Attribute Edit' dialog box opens.
3. Enter a name for your annotation attribute.
   • For this example, create an attribute named isPersistent.
4. Enter a short description for your annotation attribute and select Checkable Attribute.
   • Note: In this example, isPersistent will be an attribute for which the user must enable or disable.
5. Click OK to save your annotation attribute definition.
6. Save your profile.

To complete this example, create two more attributes:

• tableName - This attribute is a String Type Attribute with the default value of tableName.
• storageType - This attribute is a Selection List Attribute with the following selections:

• • anEntry0
  • anEntry1 - Set this option as the default selection by clicking Set default.
  • anEntry2

When you are finished, your Annotation Definitions in your project profile should include the following:

• Annotation named Persistence.
  • Scope of Managed Entity.
  • Three annotation attributes: isPersistent, tableName, storageType.

You must now Deploy the profile. For more information about deploying a profile, refer to the Tigerstripe_Profile_Tutorial.

Adding annotations to an entity.

Complete the following procedure to add the Persistence annotation to an entity in your Tigerstripe Project.

To add a simple annotation:

1. In the Overview tab for your entity, locate the Annotations section. You may need to click on the title Annotations to open the list.
2. Select Add. The Stereotype Selection dialog box displays.
3. Select an annotation from the list of annotations and click OK.
   • In this example, select the Persistence annotation.

To edit an annotation:

1. Double-click the annotation in the Annotations section of your entity. Alternatively, select the annotation and click Edit. The Annotation Details dialog box opens.
2. Enter the annotation name in the tableName text box.
3. Select isPersistent. In this example, this option is selected by default as defined in the Entity Annotations tutorial.
4. Make a storage selection from the storageType list box. As defined earlier,anEntity1 is the default selection.
5. Click OK to save your changes and return to the entity editor.
6. Save your entity.

Using Annotations from a plugin