JRapid and Eclipse reference guide

22/10/2009. Simon Aberg Cobo

Introduction

The following features are available in JRapid's Plugin:
JRapid Source Editor: An editor for JRapid XML source files, supporting auto-completion and syntax highlighting.

JRapid Manager: A view for visualizing JRapid projects within Eclipse's scope. It provides an overview of the projects crucial information (synchronization state, files sent, etc) and the possibility to start/stop synchronization, perform a full resynchronization, generate in the cloud, etc.

JRapid Conflicts: A view for visualizing projects conflicts, supporting compare views and conflict resolution methods (commit local file, override local changes).

Property Page: JRapid projects integrate into Eclipse with Property Page, allowing the user to change projects preferences such as server, exclusion patterns, etc.

Toolbar Actions: A set of toolbar actions with functionality very similar to those of the Project Manager.

Popup Actions: A set of popup specific actions (triggered from the package explorer or from the editor's scope)

Built-in Console Messages: All messages are printed in Eclipse's built-in console

Creating a JRapid Project

Please refer to http://www.jrapid.com/40--JRapid--and--Eclipse.html

Managing existing JRapid projects

Working with JRapid Plugin is very simple. Projects can be managed either from the JRapid Manager, or the Toolbar Action set. To open JRapid Manager go to Window->Show view->Other.. (Figure 2).

Press OK and a new view must open

JRapid's Eclipse Plugin goal is to provide the user a transparent way of working with files in the cloud. To achieve this, projects must be synchronized. Once a project is synchronized, local changes will be automatically committed to the cloud and, every time a generation is made, newly generated files in the cloud will be downloaded.

Note: Free projects are allowed to commit only JRapid source files located in root directory.

Projects can be synchronized from 4 different places:

1. 1. From JRapid Manager, by selecting a project and pressing the action button
2. 2. From JRapid Manager, by right clicking a project and pressing the action button
3. 3. From the Toolbar Action set, by selecting the project from the pull down list
4. 4. From the Package Explorer, by right clicking the project name and selection 'Synchronize project' from the JRapid sub menu

Once any of these actions is taken, the plugin will synchronize the project with the cloud by performing an initial update and commit. Every message informing files updated and committed, etc will be printed in Eclipse's built-in console

Note: When managing many projects, we can synchronize more than one project at a time by selecting various projects with the CTRL key, and then selecting the start synchronization option. Moreover, you can press the Start All projects action, which will simply start synchronization of all JRapid projects.

That was easy! Now any changes we make to our local files (as long as they are allowed) will be committed to the cloud.

Note: Sometimes, especially in development stages, synchronizing a project is not the most comfortable option. Maybe we are coding some JAVA file which you know it is not correct yet. Because of this, we have included an “only download” synchronization mode. This means that if generations are made from the WEB-IDE our local files will be updated, but local changes won't be committed. To choose this mode just select a project and press the appropriate action button from JRapid Manager.

While a project is synchronized we can perform other actions such as performing a full resynchronization or generating in the cloud.

If we want a certain synchronization to stop, we can do it from JRapid Manager or the Toolbar Action set, just the same way we started it.

Editing JRapid Source

JRapid source is the core of every JRapid application. By default, all projects have their source named 'Main.xml', located in root directory. These XML files must be written following a special schema. To help the developer, a Source editor is included providing the following features:

1. 1. Syntax highlighting
2. 2. XML structure validation
3. 3. JRapid auto completion (CTRL+SPACE)

Additionally, when a source file is generated in the cloud, the plugin will print in the console a message informing whether the file has validated with JRapid required structure. In Figure 5 for example, the entity after Person doesn't have a name.

When errors are more severe (for example, trying to generate an empty file), generation is aborted.

Resolving Conflicts

Although the idea is to work as transparently as possible, synchronization problems may occur. These conflicts will mostly appear when editing the same file locally and in the cloud (from the WEB-IDE). To solve them the plugin provides a JRapid Conflicts view (Figure 6).

Therefore, every existing conflict will appear in JRapid Conflict view. Resolving them is pretty straightforward. Similar to SVN conflicts, we will have our local file ('Main.xml') and our cloud file ('Main.xml.cloud'), which is a copy of the file present in the cloud at the moment we did our last update. We can then follow any of the following methodologies:

1. 1. Mark as resolved: If this option is selected, the local file will be committed to the server, overriding any changes done in it
2. 2. Override local changes: If this option is selected, the server content will be copied to our local copy

This actions can be executed by right clicking the file name from the conflict view, or by right clicking the server file (*.cloud) in the package explorer. After performing any of them, the server file (“Main.xml.cloud”) will be deleted.

Before taking an action to resolve the conflict, it is important to take a look at the differences between our file and the server's file. To do it, we can go to the conflicts view and double click the file.

As we see in Figure 7, it is generally a good idea to open the compare editor to view the differences and make changes to our local file. Then we can mark as resolved.

Re synchronizing

Sometimes it may seem necessary to perform a full re synchronization of a certain project. This means checking whether we have the exact same files locally than in the cloud. Having the exact same files implies checking that:

1. 1. There are files that exist in our local project but don't exist in the cloud
2. 2. There are files that exist in the cloud but don't exist in our local project
3. 3. Every file that exist both in our local project and in the cloud have the same hash file

If point 1 fails, we will be offered to delete our local files that don't exist in the cloud, commit them or just keep them. If point 2 fails, files are automatically downloaded. If point 3 fails, our local file is overridden.

Generating in the cloud

Generating is probably the most important functionality the plugin provides. Only JRapid XML source files located in the root directory can be generated. To do so, follow any of the following actions:

1. 1. Right click on the editor and choose generate from JRapid's menu
2. 2. While focused on the editor, type the following keyboard shortcut: CTRL+ALT+SHIFT+G
3. 3. Right click on the file in the package explorer

Once a file was generated for the first time, it will be listed in the generate toolbar pull down button. From there we can see the last 10 files that were generated for quicker access. Once the generation is started we will see its corresponding feedback in the console, just the same way it was done in the WEB-IDE.

A few more functionalities

Finally, a few more functionalities that make our life a little bit easier.

To check out our project in the WEB-IDE, just right click any file a certain project and select 'Open JRapid WEB-IDE'. The default internet navigator will be opened and directed to the project's URL.

JRapid provides templates to append to our source files (usually standard implementations of frequently used entities such as login, etc). To append a template to our source file, just right click it in the package explorer or on the editor and select the 'Add Template Option..'. The dialog in Figure 8 will open.

In it, we can filter templates by name or category. When we choose 'Finish', the code from the 'Preview' text box will be appended to our selected source file.

As previously said, maybe performing a full synchronization of a project may not seem as the most comfortable option in development stages. An interesting option was to synchronize the project in 'Only download' mode. An even more interesting option is to simply exclude files/folders from synchronization.

Whenever a file/folder is excluded from synchronization, those files/folders won't be committed or downloaded. Excluding files/folders from synchronization is very straightforward. Just right click on the desired object and choose 'Exclude from JRapid synchronization' from JRapid menu.

Note: To check which files/folders are excluded from synchronization for a certain project, just right click on it in the package explorer and select the 'Properties' option.

Once the dialog opens, go to JRapid's submenu. There you will see Figure 9 dialog. In the text box at the bottom exclusion patterns are listed. To remove a pattern from being excluded just erase it in the text box and click 'OK'.

Conclusion

In this article we described the most important extensions JRapid Plugin provides to the Eclipse platform. By correctly using them, we can work almost transparently with files located in the cloud. Now that we have learned these simple tricks, we can get our hands in business logic!