Skyway Builder - BuildingCustom Steps Guide

June 2, 2008

Skyway Software

Skyway Builder - Building Custom Steps Guide: June 2, 2008Skyway Software

PublishedCopyright © 2008 Skyway Software

Abstract

One of the major features of Skyway Builder is that it can be extended in a variety of ways. The purpose of thisdocument is to describe the process for building custom model steps that can be used in addition to the Skyway corestep. The latest version of this document, along with all other documents, can be found at the Skyway CommunityPortal. [http://www.skywayperspectives.org]

iv

Table of Contents1. Overview ....................................................................................................................... 12. Getting Started ............................................................................................................... 23. The Plug-in Development Wizard ...................................................................................... 34. The Plug-in Project Artifacts ............................................................................................ 85. Testing Plug-in Project ................................................................................................... 116. Modify Data Model ....................................................................................................... 137. Modify Properties Section ............................................................................................... 148. Completing the JET template ......................................................................................... 169. Deploying the Plug-in Project .......................................................................................... 1810. Resource Summary ...................................................................................................... 20

v

List of Tables6.1. Project Wizard Configuration ........................................................................................ 138.1. Tags ......................................................................................................................... 16

1

Chapter 1. OverviewA great new feature that is included in Skyway Visual Perspectives 6.0 is the capability to extend theplatform by building your own modeling artifacts. This new feature allows developers to literally addcompletely new modeling functionality to the modeling environment. The benefit of this feature is that itallows you to extend the development platform and take common tasks from across projects and developersand expose them as a new reusable modeling artifacts for all developers. This is also a great way to ensurestandards are being adhered to for coding tasks that might normally be handled by repetitive custom handcoding.

Some common use case examples of when you might consider creating a custom logic step include:

• When projects need to interact with legacy ERP systems. The calls to the legacy systems could berolled into a custom modeling artifact thus making the interaction with the legacy systems consistentand reusable.

• You may want to use a third party library for PDF generation. This functionality could be exposed asa new modeling step that all developers could take advantage of.

• You need to add the ability to your projects to call existing EJBs. These EJB calls could be handledby a custom step too.

This document is an overview of the key tasks involved with extending the Skyway modeling environmentthrough creating new custom modeling artifacts. For greater detail on the individual subjects covered inthis overview, go to the Extending Skyway section of the Skyway Wiki. In addition to the Skyway wiki,another great resource is the Skyway source code itself. Here you can see and learn from how the coreSkyway modeling artifacts have been built. For directions on how to download the Skyway source code,check out the download section of the Skyway community site.

2

Chapter 2. Getting StartedFor this example we’ll create a custom step that can be used to FTP any file from any FTP site to yourlocal machine. First we’ll need to consider our design so we understand what our model inputs and outputswill be.

To access a file on an ftp site and then save it we’ll need the following information:

• Host – the FTP site

• Username and Password

• The name of file we want to download

• The name and location we want to store the file locally.

Now that we have defined what data we need to have provided for the FTP step to function, we can usethis information to define our model object in Plug-in Development Environment wizards.

3

Chapter 3. The Plug-in DevelopmentWizard

The easiest way to start building custom modeling artifact is to use the wizards included in the Plug-inDevelopment Environment (PDE). The following directions will guide you through the high level tasksof using the PDE Step Registry wizard to build your FTP step.

1. Start by building a new step project. From the menu select File-->New-->Other... then choose Plug-in Project, (See Figure 1)

2. Give the project a name. In this FTP example we have used "org.skyway.foundation.mysteps". Makesure when naming your project that you follow standard java naming conventions. If you plan to havemultiple steps in this same project make sure that your project name reflects this because each new stepwill have a set files and folders underneath the project itself. See Figure 2.

3. Accept defaults for next page shown in Figure 3.

The Plug-in Development Wizard

4

4. On the next page select the type of plug-in as a "Skyway Custom Step."

5. The following page is where you provide the step name. Press the "Add" button and name the step FTP.

The Plug-in Development Wizard

5

6. Before you complete the next part of the wizard take a quick tour of what we can see here in the SkywayCustom Step Registry Wizard.

a. Select the “Skyway Only” radio button and you will see that you can view all of the Skyway existingsteps.

b. Expand the email step as shown Figure 6. You will see some of details we can set up for custom steps.

c. The Property Sheet section is where you can define the tabs that make up the user interface we willuse to enter the required information to a modeling step. In the case of the Send Email step thereare three property tabs; Header, Body and Attachments that are used to capture the inputs to theemail step. In Figure 7 below you can see how each of these tabs as are displayed in the modelingdesign environment.

d. Validations section is where validation rules can be defined for the custom steps. For instance ifthe “host” field of the FTP step is to be a required input to the FTP model step, we could create avalidation expression that looks something like this:

target.host != null

.

e. Expand the validation tab under Send Email step to see similar types of rules and expressions inplace for this step.

7. To create the FTP step’s model interface:

The Plug-in Development Wizard

6

a. Reselect the “Local Only“ radio button and then select the FTP step.

b. Select the Model Interface Define button as seen in figure 8.

8. Define the fields for the step model:

a. Select org.skyway.foundation.mysteps.ftp and press the “Add” button to add each of the input fieldsas shown in figure 9.

In this step you are defining the fields that will be available in the dynamic model object java class.This is a java interface that will contain the bean properties (the getters and setters) for our model.

9. Once you have defined the Model Interface you are ready to define where the new artifact will appearin the modeling palette. In Figure 10 you will see that we have added a new group called "Demo" andchanged the type to drawer.

The Plug-in Development Wizard

7

10.Underneath the New Demo group add the FTP step as a Child Tool as shown in figure 11.

11.Once you added the step to the Palette Registry press the Finish button and your step project will begenerated.

8

Chapter 4. The Plug-in Project ArtifactsNow we can take a quick tour of the project that was created. In the Package Explorer under the src folderyou will see that several artifacts have been generated for you; see Figure 12 below.

FTPStep.java: Is a dynamic bean with the getters and setters for each of the fields you defined in the PDEStep Registry wizard. Open up the FTPStep.java and you will see the getters and setters defined here.

Note that this is a dynamic model object because the model step extends the Step interface (see figure13.) Dynamic models make use of the Eclipse Modeling Framework’s (EMF) dynamic features. Becauseof this you will only see the getters and setters are defined. For more on this subject see the Step Modelsection of Custom Steps Wiki.

Skyway model step java files follow a standard naming convention of {stepName}Step.java. So it shouldbe easy to identify a step’s data model by locating this xStep.java file.

FTPPropertySection.java: The PropertySection.java files are where the User Interfaces for the propertysheets will be defined. In the case of the FTP step we have a single tab, so there will only be onePropertySection.java file. However if you recall in the case of the case of the Skyway Send Email step

The Plug-in Project Artifacts

9

there are three tabs; Header, Body and Attachments. For this step there are three PropertySection.java files:HearerPropertySection.java, BodyPropertySetion.java and AttachmentsPropertySection.java.

The PropertySection classes extend a Skyway custom step framework class:org.skyway.action.ui.sheet.StepPropertySection. This Skyway class extends the standard EMF propertysection class: org.eclipse.ui.views.properties.tabbed.propertySections. We could choose to extend fromeither class, but by extending from the Skyway framework class we can take advantage of the helpermethods which make it easier to bind the UI controls like buttons to the data in the project.

Expand the imports section of the java file and you will notice the use of SWT Layouts and SWT Widgets.Widgets are a rich cross platform set of UI controls that can be used to build a user interface. Any widgetthat can be hosted in an SWT Composite can be used when defining a property tab.

When using SWT, you will need to choose a layout type. In Figure 14 you will see a GridLayout withtwo columns that has been created for us. One enhancement we’ll make later is to add a third column forthe Skyway Choose buttons.

Because we’re using a grid layout with two columns, you can see in Figure 14 the first widget we defineis a LabelControl with a value of “Host”. The second widget is a TextControl which will provide a placeto enter a value and store it in a model step variable called “host”. Each field defined in our step modelwill have a section where we define these controls, so you will see controls created for host, username,password, etc.

For more information on SWT see the Eclipse Standard Widget Toolkit home.

ftp.jet: This text file located in the template folder is where the project’s java templates are defined. Togenerate java code from templates the Skyway framework makes extensive use of another EMF tool calledJET (Java Emitter Template) Jet is a subset of the JSP syntax, so if you are familiar with using JSP todefine html pages, then you should have no problems learning JET to define java. JET is part of the EclipseModel To Text (M2T) project. You can find more details on M2T and JET syntax at the M2T home.

When you open the ftp.jet text file, initially this file does not have a much to it. However, we will comeback to this file later to fill in the FTP logic for the FTP custom step.

Another resource for learning more about building JET templates in Skyway Visual Perspective isSkyway’s Open Source project available for download. In here you will find the JET templates for thecore Skyway steps. The Skyway steps can be found in the org.skyway.core.steps package.

The Plug-in Project Artifacts

10

plugin.xml: This is a manifest file that describes the contents of a plug-in to Eclipse at runtime. In this filewe will find version information, dependencies, extensions and extension points. Some additional Skywaymodeling specific details included in this file are:

• The icons to be used by the modeling artifact

• Specific tabs and property sections

• How artifacts are to be organized in the palette registry

When opening this file, the Plug-in Manifest Editor will display the file contents sections organized intopages located across the bottom. By selecting the plugin.xml page, you can see the entire xml file contents.

11

Chapter 5. Testing Plug-in ProjectBuilt into the Eclipse workbench is the ability to launch another instance of the eclipse workbench thatincludes the contents of the plug-in project. This provides a very useful way to preview and test the plug-in project without having to build a deployable version of a plug-in project.

To do this Right mouse click on the plug-in project’s top level project folder and choose Run As--> OpenRun Dialog... This will open an editor (figure 16) which will allow you to configure the runtime launchsettings for testing the plug in.

1. Start by right mouse clicking on the Eclipse Application -> New

2. Create a new Workspace Data Location by adding "/steps" to the end of the default workspacelocation. The sandbox location must be different than the host workbench we are launching the projectfrom.

3. It is also recommend that you Configure VM Arguments to use the following settings:

Testing Plug-in Project

12

-Xms40m -Xmx512m -XX:PermSize=30m -XX:MaxPermSize=256m

4. Two optional settings to consider setting is the option to "clear the workspace" and to "Ask forconfirmation before clearing". This setup will give you the option to clean up your sandbox betweentest runs.

5. Once the runtime environment is setup to test the project, Press the Run button.

6. In the sandbox try out the new plug-in by creating a new skyway project and test using the new modelstep in any model. Keep in mind you should only be able to see the step in the palette and use it on themodeling canvas, but it really can’t do anything yet.

7. Add a FTP step to the Modeling Canvas and save your changes. This will cause the JET template togenerate the java file for the model. In Figure 20 you will notice there is not a lot to our java templateyet, but this simple java method does provide confirmation that our basic templates is working.

13

Chapter 6. Modify Data ModelWhen we initially set up the FTP fields in our model interface we defined everything as a String data type.This choice is good when you expect to use your model steps with static text value set at design time. Inmost cases though, we will likely want the field values to be dynamically assigned at runtime through theuse of project and step variables. To do this we will need to change our data type from a String to one ofthe special Skyway types defined in the Skyway core model.

Table 6.1. Project Wizard Configuration

Type Description

VariablePath Is used to hold the value of a single Skywayvariable.

VariableText Like a variablepath, this type can hold the valueof a Skyway variable or it can hold a staticallyassigned value at design time.

For the purpose of the FTP model step we’ll use the VariableText type, this will allow for the use of bothstatic values and variables.

1. Open the model file, FTPstep.java.

2. Change the references in both the getter and setter from String to VariableText.

3. Add the @Containment(true) annotation before each getter method. This annotation is required forpersisting the data when using the VariableText or VariablePath types.

14

Chapter 7. Modify Properties SectionNext we’ll need at the ability to select a variable to our property sheet. To do this we’ll need an additionalcolumn in the data grid layout. This new column will hold a Skyway Choose button. Below is a screenshot of what this new layout will look like when we’ve completed.

• Open the FTPPropertySection.java file.

• Located near line 20, change the gridLayout.numColumns = 2 to a value of = 3.

• Because the model now uses VariableText types, well need a SWT UI widget control than can workwith this new type. The second column of each row of the grid is the where the field values can beentered. Currently these fields are set up to use a standard SWT Text Control. These references need tobe modified to use the Skyway VariableTextControl.

1. Add the following variable declaration to the top of the create method :

VariableTextControl variableTextControl;

2. Change all references in the second column

From:

control = createTextControl(parent, "password");...control.setLayoutData(gridData);

To:

variableTextControl = createVariableTextControl(parent,false,false, "password");...variableTextControl.setLayoutData(gridData);

• In the third column of the data grid is where a Skyway Choose button should appear. Add the followingline of code at the end of each row.

this.createVariableChooserButton(parent,variableTextControl);

See final version of code below.

Completed create Method

Modify Properties Section

15

public void create(Composite parent, TabbedPropertySheetPage tabbedPropertySheetPage) {VariableTextControl variableTextControl;GridLayout gridLayout;GridData gridData;Control control;

gridLayout = new GridLayout();gridLayout.numColumns = 3;parent.setLayout(gridLayout); //row 1, col 1control = createLabelControl(parent, "Host");//row 1, col 2variableTextControl = createVariableTextControl(parent,false,false, "host");gridData = new GridData();gridData.grabExcessHorizontalSpace = true;gridData.grabExcessVerticalSpace = false;gridData.horizontalAlignment = SWT.FILL;gridData.verticalAlignment = SWT.CENTER;variableTextControl.setLayoutData(gridData);//row 1, col 3this.createVariableChooserButton(parent,variableTextControl); //row 2, col 1control = createLabelControl(parent, "Username");//row 2, col 2variableTextControl = createVariableTextControl(parent,false,false, "username");gridData = new GridData();gridData.grabExcessHorizontalSpace = true;gridData.grabExcessVerticalSpace = false;gridData.horizontalAlignment = SWT.FILL;gridData.verticalAlignment = SWT.CENTER;variableTextControl.setLayoutData(gridData);//row 2, col 3this.createVariableChooserButton(parent,variableTextControl);

//row 3, col 1control = createLabelControl(parent, "Password");//row 3, col 2variableTextControl = createVariableTextControl(parent,false,false, "password");gridData = new GridData();gridData.grabExcessHorizontalSpace = true;gridData.grabExcessVerticalSpace = false;gridData.horizontalAlignment = SWT.FILL;gridData.verticalAlignment = SWT.CENTER;variableTextControl.setLayoutData(gridData);//row 3, col 3this.createVariableChooserButton(parent,variableTextControl); //row 4, col 1control = createLabelControl(parent, "RemoteFile");//row 4, col 2variableTextControl = createVariableTextControl(parent,false,false, "remoteFile");gridData = new GridData();gridData.grabExcessHorizontalSpace = true;gridData.grabExcessVerticalSpace = false;gridData.horizontalAlignment = SWT.FILL;gridData.verticalAlignment = SWT.CENTER;variableTextControl.setLayoutData(gridData);//row 4, col 3this.createVariableChooserButton(parent,variableTextControl); //row 5, col 1control = createLabelControl(parent, "LocalFile");//row 5, col 2variableTextControl = createVariableTextControl(parent,false,false,"localFile");gridData = new GridData();gridData.grabExcessHorizontalSpace = true;gridData.grabExcessVerticalSpace = false;gridData.horizontalAlignment = SWT.FILL;gridData.verticalAlignment = SWT.CENTER;variableTextControl.setLayoutData(gridData);//row 5, col 3this.createVariableChooserButton(parent,variableTextControl);} }

16

Chapter 8. Completing the JETtemplate

The final task left to complete is to update the JET template. In order to do this we’ll need to cover a fewbasic JET tags. In the table below you will see the two tags and an example of how to use each of them.

Table 8.1. Tags

Tag Description<java:import>...</java:import>

Will replaced enclosed content with the java nameand also ensure appropriate imports are generated.

Example: JET

<java:import>java.util.List</java:import> myList;

JAVA

List myList ;

<sw:variableText select=".."/>; Will emit the contents of stored in theVariableText variables

Example: JET

String ftpHost = <sw:variableText select="$step/host"/>;

JAVA

String ftpHost = java.text.MessageFormat.format("{0}", _getVariableContext().get("host"));

For more information on the Skyway Custom Tags, please see the Custom Step section of the SkywayWiki. More information on all of the JET tags can be found at the Model To Text home.

For the FTP step we’ll keep the logic simple and use the Apache Commons Net library. It’s generally agood idea to first make sure the code you want to use in your template actually works before you convertit to a template. Once you know you have the java code working it’s easy to convert the java code to a JETtemplate. Listed below is a snippet of how the code might look if we were hand coding this in a POJO.

URL url = new URL("ftp://" + ftpUser + ":" + ftpPassword + "@" + ftpHost + "/" + ftpRemoteFile + ";type=i");URLConnection urlc = url.openConnection();InputStream inStream = urlc.getInputStream();OutputStream outStream = new FileOutputStream(ftpLocalFile);int bytesRead;

byte[] buf = new byte[4096]; while ((bytesRead = inStream.read(buf, 0, 4096)) > 0) { outStream.write(buf, 0, bytesRead);} outStream.flush();

Next we’ll take this code and convert it to a JET template and use it in our ftp.jet file. A simple way todo this is to take your working java code and place it into the JET template file, then begin adding theappropriate JET tags.

1. Below is a completed version of what the JET template should look like. This code would begin at thebottom the ftp.jet file; after the

_getLogger() entry.

Completing the JET template

17

String ftpHost = <sw:variableText select="$step/host"/>;String ftpUser = <sw:variableText select="$step/user"/>;String ftpPassword = <sw:variableText select="$step/password"/>;String ftpRemoteFile = <sw:variableText select="$step/remoteFile"/>;String ftpLocalFile = <sw:variableText select="$step/localFile"/>;

<java:import>java.net.URL</java:import> url = new <java:import>java.net.URL</java:import>("ftp://" + ftpUser + ":"+ ftpPassword + "@"+ ftpHost + "/" + ftpRemoteFile + ";type=i");<java:import>java.net.URLConnection</java:import> urlc = url.openConnection();<java:import>java.io.InputStream</java:import> inStream = urlc.getInputStream();<java:import>java.io.OutputStream</java:import> outStream = new <java:import>java.io.FileOutputStream</java:import>( ftpLocalFile);

int bytesRead;

byte[] buf = new byte[4096];while ((bytesRead=inStream.read(buf, 0, 4096)) > 0) { outStream.write(buf, 0, bytesRead);}outStream.flush();

2. Save the JET template.

You will notice the use of java:import tags have been added around the java types and also thesw:variableText tags are added for referencing the step variables. You may also notice that the handwritten code and the JET template are in fact very similar.

3. Test the new changes made to the Plug-in by running the project as an Eclipse application.

a. Use the custom step in a model.

b. Notice that you can either select a variable or type in a static value.

c. Located the Generated code for you model step and examine the generated code.

18

Chapter 9. Deploying the Plug-inProject

Now that the model step is tested and working, it is ready to share as a plug-in. To ensure that all thecontents of the project are bundled into the deployed plug-in, we’ll need to review the build.properties file.This file should be located in the same location as the pluging.xml file.

• Open the build.properties file.

• Ensure that the icons and templates folder are included in the Binary Build section

• Click on the build.properties page and you should see the files content. Ensure that the jet2java referenceis included in the source section as well. Save any changes that are made to this file.

source.. = src/,\ jet2javaoutput.. = bin/bin.includes = plugin.xml,\ META-INF/,\ .,\ templates/,\ icons/

• Right click on the project and choose the Export option.

• Choose the Deployable plug-ins and fragments option.

Deploying the Plug-in Project

19

• Specify the location of where the plug-in jar file will be created and ensure the plug-in project is checkedand then press finish.

• Take the resulting plug-in jar file and copy the file to the Eclipse\plug-in directory where you haveSkyway Visual Perspectives installed.

• Launch Skyway Visual Perspectives and try using your new ftp plug-in in any of your models.

20

Chapter 10. Resource Summary• Skyway Wiki

• Skyway source code download details

• Eclipse Standard Widget Toolkit

• Model To Text home.