JPOSEEInEclipse

How to set up a jPOS-EE based project in eclipse (Ganymede, Galileo)

I use jPOS very often and I really like IDE features like auto completion and easy and GUI based refactoring, so I set up jPOS-EE in eclipse lots of times, after many trial and error attempts, I ended up in a configuration that is nice enough for me, and I would like to share with others, to receive suggestions and also to be helpful to the jPOS-EE community.

I am going to write this document while I give the described steps. I'll be using Ganymede but most of these steps if not all of them also apply to Eclipse Europa. This steps are also tested in Galileo

At first it will be somehow incomplete, just will have the project definition steps, but I'll update it as soon as I make actions to debug or to attach sources to jars, etc

Getting the sources

You can get the sources as described in http://jpos.org/jposee/jPOS-EE.pdf .

I will assume that you already have the sources in your system and you have read the mentioned document. This is because this set up is interesting for me in different scenarios, for example, having a jPOS-EE svn working directory, using svn:externals to get some modules in another project, or just an export of the sources used in another project. The only thing relevant here is the suggested jPOS-EE directory structure.

Step by step guide to setup the project.

In the next steps <jpos-ee-home> will denote the root of the suggested jPOS-EE.

1. Compile the project
   1. Before you attempt to create a project in eclipse you better run ant, at a terminal, placed in <jpos-ee-home>. This will create intermediate files and folders. This step is not needed if you don't use the eecore package, but it doesn't hurt anyway.
2. Create the project
   1. Create a new Java Project by going to menu File > New > Java Project, or the way you like it.
   2. The New Java Project window appears,
      1. choose a project name, like jpos-ee, I will refer this name as <eclipse-project-name> from here.
      2. choose create project from existing source and browse to <jpos-ee-home>.
      3. Select the other options as you wish and click next.
      4. Eclipse will try to guess your source folders, and by default it will try to set bin as the output folder, you want to response no if it asks to remove the bin folder because some useful jPOS-EE scripts are there.
   3. The java settings window appears
      1. On the source tab:
         1. You have a listing of all the source folders eclipse detected. If you compiled the project in the step 1, you will see a build/modules/<module>/<path-to-src> item for each module with sources. Remove them all from the build path, but don't remove build/src.

            Tip: to remove the source folders from the build paths, select all of them and click on “Remove from Java build path”.

         2. On build/src source path, you have to “Configure inclusion and exclusion filters” so that the sources do not get duplicated with the original ones, you have to ignore all those that are in the original modules, here you only have to include only those created by the jPOS-EE build process. For example if you have the eecore3 module enabled:
            1. Select the build/src source path.
            2. Click on “Configure inclusion and exclusion filters”.
            3. In the “inclusion and Exclusion Patterns” window that get raised, click on add.
            4. Click browse and browse to org/jpos/ee/Constant.java and click ok
            5. You can add more filters including patterns.
         3. Remove the build/test source path and all of the opt/* source paths as in step 2.3.1
         4. In the default output folder put <eclipse-project-name>/build/classes.
      2. On the Libraries tab: You have to leave all the jars provided by the modules, as there are many copies of the libraries produced by the jPOS-EE build process you better remove all the libraries (except for the JRE System Library of course) and then add the needed ones.
         1. Select all jar libraries and click remove.
         2. Click add jars.
         3. In the appearing window “JAR Selection” select all the jars under <eclipse-project-name>/modules.
      3. Click finish.
3. Once the project is created the only thing left so that eclipse can compile the project as if you were on the command line running ant, is to let eclipse know it has to call ant.
   1. Open the project properties window.
   2. In the properties window select the builders page.
   3. Create the new ant builder
      1. Click on new.
      2. Select ant builder
      3. Write a name for the new builder.
      4. In the main tab set the build file to “${workspace_loc:/<eclipse-project-name>/build.xml}” or click browse workspace to select the build.xml at the root of the jPOS-EE tree.
      5. On the refresh tab:
         1. Click refresh resources upon completion option.
         2. Select the “Specific resources” option.
         3. Click on Specify resources and select <eclipse-project-name>/build,
      6. On the Targets tab:
         1. set the target for During a “Clean” to clean.
            1. Click on the set targets button corresponding to During a “Clean”.
            2. De select the compile target and select the clean target.
         2. set the target for Auto Build, Manual Build and After a Clean to modules, this is so that the sources doesn't get compiled twice, one by eclipsee and the other by ant, also when the sources are compiled by ant, they are compiled under build/src, so if you make the common mistake of clicking on the error in the console you are going to open a copy of the source and your changes lost on the next build.
      7. On the Build Options tab you may set the relevant resources that fire the ant compilation.
         1. Enable the Specify working set of relevant resources,
         2. Click on Specify resources.
         3. Select <eclipse-project-name>/modules
         4. De select <eclipse-project-name>/modules/ignore.list and <eclipse-project-name>/modules/include.list
         5. Select build.xml, build.properties and build.xml at the root of the project
   4. Now that the new builder is created, it is better that it gets executed before the Java Builder, so select the new builder and click on up.

Now the project is ready to be compiled from eclipse and the compile errors showed by eclipse will be generally correct.

In later updates I will explain in detail how to set up eclipse to debug jPOS-EE, but by now I let the global picture, you have to set the working directory to <eclipse-project-name>/build, and run the main class org.jpos.q2.Q2.

Adding a new module

1. Copy the module tree under the modules sub directory of the project by any means.
2. If the module has a lib directory add all the jars in there to the build path, for example by selecting them all, rightclicking and selectin "Build Path"> "Add to Build Path" in the context menu.
3. If the module has an src directory add it to the source path, for example by selecting it and selecting "Build Path"> "Use as Source Folder" in the context menu.
4. Add the module to the relevant resources of the ant builder.
   1. Open the properties window for the project
   2. Select the builders page
   3. Open the Build Option tab
   4. Click on the specify resources button
   5. On the resource working set window select the module subdirectory

And that's all.

Running and Debugging inside Eclipse

1. Right click the project
2. In the context menu go to "Debug As" > "Debug Configurations ..."
3. In the emerging "Debug Configurations" window select the Java Application item in the tree at the left of the window and click on the "New launch Configuration" button, the one with the paper sheet and the plus simbol in yellow
4. Write a name for the debug configuration, "jpos-ee-application" for example.
5. Enter org.jpos.q2.Q2 in the Main class text field, or select the class with the search button.
6. Select the Arguments tab:
   1. In the working directory frame select other
   2. Enter ${workspace_loc:<eclipse-project-name>/build} or select it pressing the workspace button
7. Click the Debug button and you will be debugging the application