The OpenEdge Hive

This section describes how to load ProRefactor source into an Eclipse workspace, so that you can use it and reference it from your own projects.

Experience programming in Java with Eclipse's IDE is not necessary, but since these instructions gloss over a few details, it would be helpful if you were familiar with Eclipse basics such as creating a Java project.

Prepare Your Eclipse Workspace

1. In Window > Preferences > Java > Compiler, set the compliance level to 5.0. While in Java preferences, also go to Installed JREs, and edit your default JRE. Add -ea -Xss2M to the default VM args. This enables assertions, and sets the stack size to be large enough for recursively descending large syntax trees.
2. Switch to the Java perspective.

You now have two choices for importing ProRefactor source. If you want to use the latest released version of ProRefactor as a library or framework, then follow the steps under Option One, below. If you want access to the version control repository for the very latest source code as it happens, then follow the steps under Option Two, below.

Option One: Import ProRefactor Plug-in Source

This option assumes that you have installed ProRefactor into Eclipse.

1. Choose File > Import... > External Plug-ins
   and Fragments.
2. Choose The target platform,
   Select from all plug-ins, and
   Projects with source folders. Click
   Next.
3. Select the org.prorefactor.* plug-ins, and
   click Finish.

Option Two: Checkout ProRefactor from Subversion

For this option, it is not necessary to have installed ProRefactor into Eclipse. See the ProRefactor Project page to gain access to the development project and repository. The project web page has instructions for anonymous access to the repository.

There are three top level directories in the ProRefactor repository: branches, tags, and trunk. You only want the trunk directory, not the entire project repository.

From the Eclipse menu, choose File > Import... > Existing Project into Workspace. Browse to select trunk as the root directory, and then Eclipse will allow you to import all of the projects at once.

Assigning java.library.path

In order for proparse.dll and proparse_jni.dll to be found, they must be in the Java library path. Those two DLLs are found in the org.prorefactor.core project directory. Select that project, and choose Properties > Info and copy the project location (full path). In Window > Preferences > Java > Installed JREs, edit your default JRE. Add: -Djava.library.path=/your/path to the default VM args, where /your/path is your org.prorefactor.core project directory.

Unit Tests and Run-time Workbench

Now you can run the unit tests. You can navigate to the following source file, and run it as a JUnit test:

• org.prorefactor.core.unittest.AllProRefactorTests.java

To launch the Run-time Workbench, choose Run > Run As > Eclipse Application. From the Run-time Workbench, you should be able to select the ProRefactor perspective, create test projects, and launch the ProRefactor menu actions. This is where you would test any changes or additions that you make to ProRefactor or your own plug-ins.

Building the Tree Parsers

There are a few tree parsers which come within their own packages in ProRefactor, each serving its own purpose. You can use any of these as examples for your own tree parser, but a copy of the treeparserbase package should normally be your starting point. The treeparser01 package gives plenty of examples of how to add action code to the tree parser.

Antlr is a parser-generator which reads a .g grammar file in order to generate the Java source code for the tree parser.

We use Ant to do the build, but Ant has to be able to find Antlr. Choose Window > Preferences > Ant > Runtime > Classpath. Select Global Entries. Click Add Jars..., and select org.prorefactor.lib/antlr/antlr.jar file. Click Add Variable... and enter ${workspace_loc:/org.prorefactor.core/bin/}. This is required because there is additional post-processing which must be done after Antlr has generated the source for the tree parser. You can close this Preferences window now.

In the package which contains the tree parser, select the build.xml file. Right-click, and choose Run > Ant Build... to get the properties dialog.

Choose the Refresh tab, and enable the automatic refresh of the containing folder. Now when you choose Run > Ant Build, the refresh and re-compile will be done automatically.

Leave the JRE set to launch a separate JRE. Running from the same JRE as the workspace does not set up the class path correctly for our needs.

Your Own Plugin

This section describes how to create your own plugin, in order to add your own tools to the Eclipse workbench. It briefly describes in general terms how to contribute menus and actions to an Eclipse workbench, and it also gives a few initial pointers for creating menu actions which use Proparse and the ProRefactor class libraries.

This section assumes that you have followed the steps in the previous sections in this chapter.

1. Choose File > New > Project > Plug-in Development > Plug-in Project.
2. Enter your project name (ex: com.xyz.example), and if desired, specify the directory to create it in. Click Next. The defaults on the next page should be OK. Note that the Plug-in ID must be unique. Click Next.
3. Choose Create a plug-in project using a code generation wizard, and choose Hello, World. Click Next.
4. The defaults on the Content page should be OK, but you can change these settings if desired and then click Next.
5. The defaults on the Action Set page should be OK, but you can change these settings if desired and then click Finish.
6. Your new plugin should already be capable of being run and tested. Choose Run... > Run Time Workbench. Your Sample Menu that your new plugin contributes should appear in the Resource Perspective. However, there appears to be a bug when we run this test: The new Sample Menu only appears in the ProRefactor perspective. There is probably a bug in ProRefactor's plugin manifest. (3 Jan 2004) Your new plugin contributes the Sample Menu, as well as a new button on the button bar. Close your Runtime Workbench, and we'll add a new menu item.
7. Open your plugin.xml, and click on the Dependencies page. Add the ProRefactor.org plug-ins as dependencies for your plug-in project. You also have to add those plugins to your project's build path. To do that, simply right-click on that Dependencies page, and choose the menu item Compute Build Path.
8. In the Package Explorer, navigate to org.prorefactor.prorefactor.actions, then copy ParseAction.java, and paste it into your project's actions package.
9. Double-click on your copy of ParseAction to open it into the Java editor. There are compile problems due to missing imports. Choose Source > Organize Imports to automatically add the necessary import statements. Save your changes, and press Ctrl-b to force a fresh build of ParseAction.
10. Open your plugin.xml, and click on the Extensions page. Under Sample Action Set right-click on Sample Action and click Copy. Back on Sample Action Set right-click and click Paste. You should now have two identical Sample Action items.
11. Double-click on the second Sample Action item, so that the Properties page appears. Change the class name to ParseAction. Change the id. Change the label to Simple &Parse. Delete the toolbarPath and the tooltip.
12. Save your changes to your plugin.xml file, and then launch the Run Time Workbench again. You will have to load or create a small project with a valid .p program file in order to test your new menu item. All it does is parse the selected resource (or resources).

What Next?

Have a look at the ParseAction class that you took a copy of. It makes use of an instance of org.prorefactor.prorefactor.actions.ActionManager, which does all of the work of examining what resources are selected, load the parser, parse the selected resources, and show results in the Console. For each resource that it parses, it does a callback to processFile(), passing the integer node handle for the top node of the AST. In the case of ParseAction, no further action is taken for the given AST, but if you look at other class files such as org.prorefactor.prorefactor.actions.QualifyFieldsAction, you will see examples of doing some processing against the selected compile units. The same as we copied ParseAction, you can copy these other examples of launching parsing and refactoring actions.