Plugin Requirements

The following components are required to use Gaijin:

• Eclipse 3.0 - The plugin is designed for 3.0 and will not run on 2.x versions. Download Eclipse 3.0 here.
• GEF 3.0 - The Graphical Editor Framework version 3.0 is required. Download GEF 3.0 here.

Note: The versions of Eclipse and GEF must be matched. If you are using Eclipse 3.0.1, download GEF 3.0.1.

Upgrading from Previous Versions

The 0.9.3 version contains schema changes for both the project and process data. It is not backward compatible with previous versions. Files from previous versions can be unistalled manually as follows:

• Shut down Eclipse.
• Open the "features" directory under the Eclipse base path and delete any folder that starts with "org.eptools.gaijin".
• Open the "plugins" directory under the Eclipse base path and delete any folder that starts with "org.eptools.gaijin".
• Restart Eclipse with the "-clean" option.

After the previous release is removed, unzip the 0.9.3 archive into the Eclipse base path and restart Eclipse.

Version 0.9.3

Bugs Fixed:

• Can not control web descriptor version (always 2.3)
• No simple way to integrate Gaijin with Eclipse Web Tools projects.

Enhancements:

• Major overhaul/upgrade to use Spring Web Flow framework
• Many flow editor enhancements including Spring Web Flow state templates, transition labels, and start/end state indicators
• Rewrite of code generation to build code required for Web Flows. Now generates SWF builder, event interfaces, attribute support class, and all configuration files

Known Issues:

• Spring IDE plugins need to be upgraded to the 1.1.1 release.

Gaijin Studio extends the Eclipse IDE to facilitate building applications based on the Spring Web Flow framework. Gaijin provides an environment for creating and configuring web flows to build a web application. It includes a web flow editor which allows an application to be modeled visually and stored as XML metadata. Template-based code generators use the metadata to generate the web flow builder, configuration, and supporting classes. This reduces the amount of time needed to develop an application and allows detailed documentation to be generated from the metadata.

Project Creation Wizard

• Creates Eclipse project structure for a Spring Web Flow project.
• Establishes classpath container for libraries expected on the application server classpath.
• Copies application libraries into project and adds them to the Eclipse project classpath.
• Generates web descriptor including entries for Spring components needed to allow the Web Flow application to function.
• Optionally, creates an empty applicationContext.xml file and maps the file into a Spring IDE configuration set.
• Generates a simple Ant build script for building WAR based on project settings.

Other Features

• Web flow editor allows for drag-and-drop creation of a flow diagram using the various flow states provided by the Spring Web Flow framework.
• An integrated Eclipse builder uses metadata from the flow diagram to generate the flow builder, configuration files, and other supporting classes.
• Gaijin supports grouping of related web flows into web flow groups. Each web flow group has its own dispatcher and configuration files. A default properties file is created for each group and mapped automatically as the message source for the group. All groups share the beans provided by the root context as well as having a separate context configuration for components used only within that group.
• Gaijin Studio is fully integrated with the Spring IDE plugins which are included in the standard distribution. Spring IDE configuration sets are used to specify the group of configuration files that makes up the root context. The Spring IDE plugins also provide syntax highlighting of the config XML files and a graphical view of context bean relationships.

Open the Wizard

Open the Eclipse new project wizard by choosing File > New > Project.  In the tree of wizard types, open the Gaijin Studio folder and choose Web Flow Project (see figure 1).  The first page in the wizard is the standard Eclipse project creation page.  Fill in the project name (see figure 2). Clicking Next in the wizard will proceed to the next page. You may click Finish at any point after the general settings page if you want to use the default options for the rest of the pages.

Figure 1: Choose "Web Flow Project" Wizard

Figure 2: Enter Project Name

 

General Settings Page

The next page is where the general project settings required by Gaijin are entered (see figure 3).

Documentation

• Project Name - A short display name for the project.
• Project Description - A short description of what the project does.

Project Folder Locations

• Source Code - The path of the folder that will hold project source code. Gaijin projects can have multiple source code folders, but the one assigned here is where Java source code will be generated.
• Application - The path of the folder that will hold the Gaijin application hierarchy. The files in this folder are created and maintained using the editors included in Gaijin. They should not be edited directly by the user.
• Web Root - The path of the root folder for the web application. The contents of this folder become the contents of the WAR file.

Package Prefixes

• Generated Code - The package prefix appended to source code generated by Gaijin. Code in this package may be re-generated or deleted by Gaijin without notice.

Figure 3: General Settings

 

Spring Settings Page

The next page is where the Spring framework settings are entered (see figure 4).

Default Spring Configuration Setup

• Create applicationContext.xml - Check this entry if you want an empty applicationContext.xml file created in the WEB-INF folder.
• Create config set and map as default - Check this entry to create a Spring IDE configuration set using the new applicationContext.xml file. The config set will be named ROOT and becomes the root config set for the project. When Gaijin generates the web.xml, this config set will determine the list of files that compose the root context for Spring.

Root Context Initialization

• Use ContextLoaderListener - Intialize Spring with a listener. This should be used in Servlet 2.4 containers or those that load listeners in the order specified in the 2.4 spec.
• Use ContextLoaderServlet - Initialize Spring with a load-on-startup servlet. This should be used in Servlet 2.3 containers.

Dispatcher Servlet Settings

• Dispatcher URL suffix - The suffix used for web flow URLs.

Figure 4: Spring Settings

Libraries Page

The libraries page determines how the classpath will be set up for the project and which libraries will be deployed in the WAR.  Gaijin includes an extensible library managment subsystem that makes it easy to specify how supporting libraries are deployed. Any plugin provider may add libraries to the list managed by Gaijin using the org.eptools.gaijin.core.libraries extension point. Library information includes the name of the library, a short description of what it does, library version and source code location. The Gaijin Studio plugins provide all of the libraries needed to deploy a working application.

By double-clicking on a library entry in the list, different deployment options may be chosen (see figure 5). The choices are outlined below:

• Server - The library is added to the project classpath in a special container provided by Gaijin. The container simulates the expected server classpath when the project is deployed. Libraries in this category are not deployed in the WAR. 
• Application  - The library is copied to the WEB-INF/lib folder under web root and is added to the project classpath. It is also deployed as part of the WAR. 
• None  - The library is not added to the project classpath and is not distributed in the WAR. This option exists for cases where a library is not needed or is provided by another classpath container. 

Figure 5: Library Settings

After clicking Finish you may see the prompt in Figure 6. Click Yes to open the Gaijin Studio perspective. If you would rather use another perspective such as the one for Web Tools, you can manually open the Web Flow Explorer view by choosing Window > Show View > Other... > Gaijin > Web Flow Explorer.

Figure 6: Gaijin Perspective

The project is now ready to use and will look something like the figure below:

Figure 7: Web Flow Project

Create a J2EE Web Project

You will need to have Eclipse Web Tools and all supporting plugins installed before continuing .

Create an Eclipse Web Tools "Dynamic Web Project" via the standard web tools wizard.

Figure 1: Create a "Dynamic Web Project"

After the project is created, right-click on it and choose Add Gaijin Capabilities....

Figure 2: Create a "Dynamic Web Project"

Follow the steps in the standard Gaijin project wizard as covered here. Once the wizard has been completed, your Web Tools project should look similar to figure 3.

Figure 3: Web Flow Capabilities Added

You can now use the features of both Gaijin Studio and Web Tools for your project..

Web Flow Explorer View

If you are using the Gaijin perspective, there should be a tab for Web Flow Explorer. If not, you can manually open the Web Flow Explorer view by choosing Window > Show View > Other... > Gaijin > Web Flow Explorer.

Web Flow Explorer is the view that allows you to create the hierarchy of web flow groups and web flows. At the base of the hierarchy is the default web flow group. You can create web flows in the default group or create subgroups to further organize your flows. Right-clicking on the default group pops up a context menu for the project. Choosing New > Web Flow will create a new web flow in the default group as shown below:

Figure 1: Create a Web Flow

The wizard for creating a web flow allows you to assign a unqiue id as well as a name and description to the flow. The id of a flow is required to be unique (the GUI does not allow duplicates) since the id is used to name the builder class and other resources. The attributes tab allows you to specify flow-scoped attribute definitions for the flow. A facade object is created around the attributes to simplify accessing flow-scoped data and to allow flow attributes to be documented.

Figure 2: Web Flow Wizard

Clicking OK creates the web flow and opens the editor.

Figure 3: New Web Flow

Open the Package Explorer view (or Project Explorer view for Web Tools) and you should see the resources that were created automatically for the new flow. The generated web descriptor should look something like this. Note that the contextConfigLocation for the default group dispatcher servlet combines two config files; one generated (GeneratedBeanContext.xml), and one that may be modified by hand (SupportingBeanContext.xml).

Figure 4: Web Flow Wizard

After adding some states and transitions to the flow diagram, take a look at the generated Java code. The generated builder for the diagram below looks like this. The builder is automatically referenced by a factory bean in the generated bean context file and mapped to a URL based on its name in the generated controller. An events interface file is also created so that actions do not have to hard-code event ids in their implementations. If a transition between states is deleted, an error will be reflected in any class that references the generated event constant for the transition.

Figure 5: Web Flow Wizard

Adding a State

State templates are shown in the palette on the left side of the flow editor. Dragging a template from the palette into the work area of the editor creates an instance of that type of state in the flow.

Figure 1: Add a View State

Double-clicking the state or right-clicking and choosing properties will open the state properties dialog. The General tab allows a unique id to be assigned to the state. A name and description are also captured for use in generating documentation of the flow.

Figure 2: State Properties Dialog

The second tab in the dialog depends on the type of state being edited. In this case it is a view state, so the only piece of information needed is the name of the view. Note that a ViewResolver should be added to the SupportingBeanContext.xml for the group so that the name may be converted into an application resource. The other alternative is to fully specify the resource name in the dialog (i.e. WEB-INF/context/searchCriteria.jsp).

Figure 3: View State Properties

Action states allow any code that implements the Action interface to be executed. Often actions perform business API calls or load data into the application model. A MultiAction is an action that provides more than one function in a single class.

Note: - When arranging many states in the diagram it is often easier to turn on the grid (View > Grid ) to help with sizing and alignment. Also, selecting multiple states in the editor enables alignment and size matching actions in the right-click context menu.

Figure 4: Add Multi Action State

The properties dialog for an action state allows the action class to be specified in a couple of ways. A fully-qualified classname may be directly created by the flow builder if desired. In this case, all action configuration is done within the Java code of the action class. Alternatively, the action class may be a reference to a bean from the web flow group context (or root context). This allows the action to be wired automatically by Spring using dependency injection. To use this approach, action classes should be added to the SupportingBeanContext.xml for the containing web flow group. In the case of a MultiAction state, the dialog also allows the desired action method to be specified.

Figure 5: Multi Action State Properties

States may be connected using transitions to indicate paths of flow. Choose the State Transition tool in the palatte, then click-and-drag from the source state to the target state. A transition with a default id will be added. Right-clicking on a transition (or double-clicking it) will open the transition properties dialog.

Figure 6: State Transitions

Each outgoing transition from a state has a unique id. A name and description may also be assigned for documentation purposes. Outgoing transition ids for a state should match the possible events that state might generate. For a view state, this means that any form submit or link events should be covered. For an action state, this means that any events returned by the action implementation should be covered. Spring Web Flow will throw a runtime error if no transition is found for an event specified in a state.

Figure 6: State Transition Dialog

An action state is added to execute the query. It redirects back to the criteria view on error and a results subflow on success (for illustration only -- results would normally be a simple view). An end state is added for handling the return from the subflow. The resulting flow is shown below:

Figure 7: Resulting Flow

To choose the subflow to execute for results, open the state properties for the subflow state. In the subflow properties, an attribute mapper may be specified as well as the subflow to execute. The attribute mapper may be directly instantiated by the flow builder or loaded by reference via the service locator. It maps attributes in the parent flow to inputs for the subflow and output from the subflow back to attributes in the parent flow. Note that only flows in the same web flow group may be called as subflows. Calls to other web flow groups should end the current flow and use a hard redirect to the other group. When the subflow is executed, the state id of the end state is returned as the transition event in the parent flow. In this case, the end state id is finish which causes the corresponding transition in the parent flow to be taken.

Figure 8: Subflow Properties

 

Each time a flow is saved, the underlying XML metadata is persisted and a number of resources are generated. The last portion of the webflow creation walkthrough shows the output from the flow created here.