Tigerstripe Simple Model Tutorial

< To: Tigerstripe_Tutorials

Designing a simple Service Contract with Tigerstripe Workbench

• Create a New Tigerstripe Project to contain the model.
• Document the new Project by editing the Project Descriptor.
• Create a Service End-point Model representing the integration point.

A Tigerstripe Project contains the details of a Service Contract Model. More specifically, it contains the following:

• A set of Artifacts that define an Information Model and the Behavior Model used in a Service Contract.
• A Project Descriptor (tigerstripe.xml), used to store additional properties about the project. Such properties can include the project version, description, but can also include properties that are used when generating code.
• A set of diagrams providing a graphical representation of the Service Contract.

This tutorial will guide you through creating a simple model and the generation of some simple output. (Creation of diagrams is covered in a subesquent tutorial).

To run this tutorial you will need to have installed Tigerstripe Workbench. See the installation tutorial here.

Create a New Tigerstripe Project

Start up Tigerstripe Workbench.

1. From the File menu, select New and click Project. The New Project: Select a wizard dialog box opens.
2. Select Tigerstripe Project and click Next. The New Tigerstripe Project dialog box displays.
3. Alternatively, you can click the icon on the toolbar.
   
4. Enter a name for your project.
   • For this tutorial, the project name is SimpleProject.
5. Click Finish to create your new project.

Note: Click Help and select Help Contents for more information about other options available.

Document the new Project

Your newly created project should be empty and the descriptor (tigerstripe.xml) for the project automatically opens.

The following items should be visible from the Tigerstripe Perspective:

• The Tigerstripe Explorer which displays the contents of displays of all Tigerstripe projects in the workspace.
• A multi-tab form. Contains details of your newly created project.
• A Problems view. Any problems in the configuration of your project will be highlighted here.

After you create a new project, you need to add some information about your project. This information is used when generating documentation for your project.

To edit project details:

1. Enter the project version information in the Version text box.
2. Enter a project description in the Description text box.
3. Click Save.

Create a Service End-point Model

In Tigerstripe Workbench, a Service Contract is modeled through a set of Artifacts stored in the project. A palette of service artifacts is available to you to model your Service Contract.

There are two main categories of Artifact:

• Information Model Artifacts. Allows you to capture details about the information model relevant to your Service Contract.
• Behavior Model Artifacts. Allows you to specify how information is made available through the Service Contract. This information can range from unsolicited notifications to query mechanisms.

In addition, an Integration Point or Session Facade Artifact models an end-point (For example, a Web Service). The next step of this tutorial is to create a simple end-point and generate a corresponding Web Service Definition (.wsdl).

To create an end-point and a Web Service Definition:

1. Click the Integration Point icon . The New Session Artifact dialog box displays.
   • (If the Icon is greyed out, then make sure your project is in scope, by clicking on the project in the Tigerstripe Explorer).
2. Enter the details about your new artifact (the name should start with an upper case letter by convention) and click Finish. The details of the newly created Integration Point or Session Facade Artifact display.

Note: Spaces and special characters are not allowed in an artifact name.

In the Tigerstripe Explorer, expand the src folder and you will see the newly created artifact in the model as shown below:

You now need to add a Method to your Session Facade Artifact. A Method represents an operation available on a Service. An example of a method would be if you wanted to build a Service related to order handling, and you wanted to offer an operation on the Service to process orders.

To add a Method:

1. Open your artifact perspective.
2. Expand the Methods section and click Add.
3. Enter a Name for your method.
   • For this tutorial, name your method processOrder.
4. Add a Method argument by clicking Add next to the Method Argument list.
   • For this tutorial, name your method argument orderNumber.
5. Click Save to save your changes.

In the Tigerstripe Explorer you can expand the Session Facade Artifact to show the defined methods.

Generate the service definition

So far, you have created a basic model for a Service Contract and you have identified one single integration point with a single operation. In this step, you will generate a Web Service definition.

In Tigerstripe Workbench, project generation is handled through Tigerstripe Plugins. A plugin defines the rules by which artifacts are rendered in the output, in terms of format (eg HTML, XML, Java) filename, and detailed file content.

Writing plugins is the subject of another tutorial here. For this tutorial we will use a demo plugin that will generate some simple WSDL and java files. NOTE - the output from this plugin is for demostration/tutorial purposes only and is not valid for use in a real-world scenario!

Download it. Deploy it.

To generate a Web Service definition:

1. Double click the Project Descriptor (tigerstripe.xml) in the Tigerstripe Explorer. This opens your Descriptor editor.
2. Navigate to the Plugin Settings tab, and click on the section heading for the plugin you have just deployed. This will open up a section where you can manipulate the properties of the plugin.
3. Check the Enable checkbox so that it will be triggered once you Generate your project. (You can have many plugins enabled at the same time.)
   
4. Click Save to save your changes.
5. Click the Generate icon on the toolbar. The Generate Tigerstripe Project dialog box displays.
6. Click Finish. The other options on this dialog will be mostly greyed out for now and their use will be covered in future tutorials.

Tigerstripe Workbench will then (provided you have followed the instructions above) generate some output files, and will refresh the Tigerstripe Explorer with the new files. Upon completion of the generate action, the workbench will pop up the Generate result dialog which shows details of the generation action. Review this information and click on OK.

Review the generated code

In the previous step, you generated a service definition. After completing that step, a new directory appeared in the Tigerstripe Explorer, called target/tigerstripe.gen. This directory is the default directory where all generated code and files are placed after running the Tigerstripe generation engine.

In the target/tigerstripe.gen directory will notice the following:

• a .wsdl file that provides a Web Service representation of the modeled Service Contract. In particular, the file contains the definition of the processOrder definition defined.
• a set of Java files that contain the interface for an Enterprise Java Bean (EJB) representing the integration point for your Service Contract. This EJB contains one operation that corresponds to the processOrder operation that you defined in the model.

Simply stated, you generated a technology specific implementation for two different technologies and maintained a semantic equivalence between them.

Note: To further refine your generated code, please refer to the corresponding tutorial here that discusses the Tigerstripe Plugins definitions.

Enhance your model

In this tutorial, you created a very simplistic view of a Service Contract with:

• a single integration point
• a single operation

Tigerstripe Workbench allows you to enhance your information model and behaviour related to a service through model artifacts called Managed Entity Artifacts. A Managed Entity is a unique item that exists either logically or physically in the context of a Service. That is, the Managed Entity represents an item that is stored with a unique key in a database. Managed Entity Artifacts are the means by which these Managed Entities are described in the Tigerstripe model and are identified by the Entity icon .

In this procedure, you will define an entity that models orders as they are handled and stored in an Order processing system. You will further define a relationship between your Integration Point (or Service Facade) and your Order entity to define how orders are processed through your service.

To create an Order entity:

1. Click the New Entity Artifact icon in the toolbar. The New Entity Artifact dialog box appears.
   File:Tigerstripe new entity wizard.gif
2. Enter a name for your new entity artifact.
   • For this tutorial, name your entity artifact Order.
3. Add an attribute for your entity artifact in the Attributes text box. Attributes describe the details of an entity.
4. Click Save. The newly created entity appears in your project.
5. After you create your entity artifact, you need to create a new Integration Point (or Session Facade)
   • Name your Integration Point OrderFacade.
6. Navigate to the Details tab and define the specific details about your Integration Point.
   • For this tutorial, add the Order entity you created as a Managed Entity. As a result, the Order entity will be managed through your service and consumers of your Service Facade can act upon orders; such as creating orders or deleting orders.
7. Click Save to save your changes.
8. Click the Generate icon and review your generated code. You will notice a new .wsdl file for your new Service Facade and this file contains the operations to create, read, updated, and delete order.

Making the Order entity as a Managed Entity of the OrderFacade Service Facade, the Tigerstripe plug-ins created create, read, update, and delete operations on the resulting web service. This is by default.

To further control the operations for managed entities:

1. Navigate to the Order entity.
2. Add a process method on the Details tab of the Entity Artifact. On the Details tab, you can control whether create, read, update, and delete operations are enabled or not, and whether additional operations should be generated on your Service Facade.
   File:Tigerstripe managed entity view on session.gif
3. Click Save to save your changes.
4. Click the Generate icon and review your generated code.

Congratulations! You've completed your first Tigerstripe Workbench tutorial!