The Kitchen in the Zoo - eclipse tag

Hacking Maven

Thu, 10 May 2012 20:07:00 GMT

We don't use M2Eclipse to integrate Maven and Eclipse, partly because we had some bad experiences a couple of years ago when we were still using Eclipse 3.4 and partly because some of our developers use IBMs RAD to develop, and it doesn't (or at least wasn't) compatible. Our process is to update our local sources from SVN and then to run Maven's eclipse:eclipse locally with the relevant workspace setting so that our .project and .classpath files are generated, based on the dependencies and other information in the POMs. It works well enough, but the plan is indeed to move to M2Eclipse at some stage soon.

We have parent POMs for each sub-system (each of which is made of several Eclipse projects). Some of us pull multiple sub-systems into our workspaces which is useful when you refactor interfaces between sub-systems, because Eclipse can refactor the code which calls the interfaces at the same time as you refactor the interfaces, saving lots of work. Maven generates .classpath files for Eclipse which reference everything in the workspace as a source projet rather than a JAR out of the local Maven repo. That is important because if Maven created JAR references and not project references, Eclipse's refactoring wouldn't adjust the code calling the refactored code.

10 days ago we switched from a build process based on continuum and archiva to jenkins and nexus. All of a sudden we lost some of the source references which were replaced with JAR references. If a project was referred to in a parent POM then it was referenced as a project in Eclipse, but if it was a sub-system built using a second parent POM, then Eclipse was referring to the project as a JAR from the local Maven repo. That was bad news for our refactoring! Here is an example of what used to happen:

    subsystem-a-project-1
    subsystem-a-project-2 references subsystem-a-project-1 as a project

    subsystem-b-project-1 references subsystem-a-project-1 as a project

Here is what was happening when we used Jenkins and Nexus:

    subsystem-a-project-1
    subsystem-a-project-2 references subsystem-a-project-1 as a project

    subsystem-b-project-1 references subsystem-a-project-1 as a JAR!!!

At the same time as moving to Jenkins and Nexus, we upgraded a few libraries and our organisational POM. We also moved our parent POMs from the root directory of the sub-system into a project for the parent (in preparation for using M2Eclipse which prefers having the parent POM in the workspace).

The question was, where do we start looking? Some people suggested it was because we'd moved the parent POM, others thought it was because we'd updated a version of a library on which eclipse:eclipse might have a dependency and others were of the opinion we had to return to Continuum and Archiva.

One of our sharp eyed developers noticed that we were getting the following output on the command line during the local Maven build:

    Artifact subsystem-a-project-1 already available as a workspace project, but with different version...

That was the single find which led to us solving the problem quickly. I downloaded the source of eclipse:eclipse from Maven central, under org/apache/maven/plugins/maven-eclipse-plugin. I created a dummy Java project in Eclipse. Next, I added the following environment variable to my command line from where I run Maven:

    set MAVEN_OPTS=-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=28000

That tells the JRE to open a debug port and wait until a debugger is connected before running the app. Running a Java program with those args makes it output "Listening for transport dt_socket at address: 28000". In Eclipse I went to the debug run configurations and added a remote connection at localhost on port 28000. It needs a project, so I added the dummy project I'd just created. I connected and Maven continued to run now that I was connected. The next step was to add the Maven Plugin source code which I'd downloaded from Maven Central. By right clicking on the debug view in the debug perspective (click on the tree), it is possible to add/update source attachments, and I added the sources JAR that I'd downloaded. The last bit was to find a suitable breakpoint. I extracted the sources from the downloaded ZIP and searched the files for the text which was being output by Maven which was hinting at the problem ("already available as a workspace project"). EclipsePlugin was the suspect class!

I added the eclipse:eclipse JAR to my dummy project so that I could open the class in Eclipse using ctrl+shift+t. Eclipse opened the class, but hadn't worked out that the source from the source attachment belongs to that class. There is a button in the editor to attach the source by locating the JAR downloaded from Maven Central and Eclipse then showed the source code and I was able to add a breakpoint. By this time Maven had finished, so I restarted it and this time I hit the breakpoint, and the problem became quite clear. For some reason, rather than the version being a simple SNAPSHOT version, it contained a timestamp. The eclipse:eclipse plugin was of the opinion that I didn't have the correct code in the workspace, and so rather than create a project reference, it created a JAR reference based on the JAR in the local Maven repo.

The internet is full of information about how Maven3 now uses unqiue timestamps for each build artefact deployed to the repo. There were some references saying you could disable it for Maven2 (which we still use), but when you move to Maven3 you can't disable it. I thought about submitting a bug report to Codehaus (who supplies the eclipe:eclipse plugin), but it occurred to me that we were still referencing version 2.8 in our organisational POM and I'd spotted a 2.9 version when I was at Maven Central. So I updated the organisational POM to use version 2.9 of eclipse:eclipse and gave that a shot.

Hooray! 23:17 and I'd fixed our problem. Shame I had a 06:30 start the next day for a meeting :-/

This isn't the first time that we've made the mistake of doing too much in a migration. We could have stuck with Continuum and Archiva when we updated our org-POM, and then step for step migrated to Nexus (still using Archiva) and then finally moved over to Nexus. Had we done that, we might not have had the problems we did; but the effort of a slow migration might also have been larger.

For me, the point to take away is that it easier to debug maven and go straight to the source of the problem, than it is to attempt to fix the problem by trail and error, as we were doing before I debugged Maven. Debugging Maven might sound like it's advanced or complicated, but it's damn fun - it's real hacking and the feeling of solving a puzzle in this way makes the effort worth it. I fully recommend it if for no other reason that you get exposed to reading other peoples (open source) code.

Copyright © 2012, Ant Kutschera

Social Bookmarks :

Eclipse Help / Infocenter - External Web Application Mode

Mon, 09 Jun 2008 20:25:00 GMT

Previously in this blog, the Eclipse Help / Infocenter was discussed and details on how to set up the help for an RCP application were given. But often you want to have your help for an application online as well as part of the product, for example if the customer does not have the latest version of the product installed. Indeed the IBM and Eclipse web sites have what they call an Infocenter - an online version of their help system. In reality, when the Eclipse Help System is running, it runs as an embedded web server within your application. So in theory, it should be possible to deploy that as a standard web application.

Quoting the Eclipse Help, "The help system can run in three modes: workbench (normal), infocenter, and standalone." Normal is when it is part of your application. Infocenter is when it runs as a seperate process acting as a web server. Standalone is when it is used outside of an RCP application.

In fact, from Eclipse 3.4 upwards, it can also be deployed as a standard Java EE web application. The following blog shows how to deploy that help to a standard Java EE web server, namely Tomcat 5.5.

Unfortunately, at the time of writing, there is no simple way to get this running. Neither is there any good tutorial showing how to overcome the pitfalls of the descriptions provided in the Eclipse 3.4 Help (search for WAR and you will get the details). Those details are repeated here, as starting steps (I hope this does not breach copyright, but the aim of this tutorial is to give a complete guide to getting help to work as a web application):

Deploying the infocenter as a Web Archive

Using Eclipse 3.4 or later it is possible to configure the help plugins to be deployed as a web archive (war file) which will act as a fully functioning infocenter. The instructions below assume a Tomcat server has been installed, but with minor modifications these steps should work for any full featured server.

In your Eclipse 3.4 installation locate the plugin org.eclipse.help.webapp..jar and copy it to a temporary directory, unzip the copy into that folder.
In the webapp plugin locate the web-archive directory and underneath that there will be two directories titled "help" and "org.eclipse.help.infocenter-feature".
Import the org.eclipse.help.infocenter-feature using File->Import->Existing Project.
.
. (Note A - see below)
.
Export org.eclipse.help.infocenter-feature as a deployable feature and set the destination to be web-archive/help/WEB-INF/eclipse in the area where org.eclipse.help.webapp.<version>.jar was unzipped.
Download org.eclipse.equinox.http.servletbridge_<version>.jar and org.eclipse.equinox.servletbridge_<version>.jar from the equinox download site. Select a version of Equinox that matches the version of Eclipse you are running to take you to the downloads page.
Extract servletbridge.jar from org.eclipse.equinox.servletbridge_<version>.jar.
Add the file servletbridge.jar to the help/WEB-INF/lib directory. You may need to create this directory.
Add the file org.eclipse.equinox.http.servletbridge_<version>.jar to the help/WEB-INF/eclipse/plugins directory
.
. (Note B - see below)
.

Note A: The documents state "Add some documentation plugins to the webapps/help/WEB-INF/eclipse/plugins directory. " This has provided some confusion among the postings that I found on the internet. Basically there are two choices. The first is to take your plugin which contains the help folder, and put it into the folder named above. It can be put there as a deflated / flat folder (that is, unjarred), or as the standard exported plugin jar which the export wizard creates for you. The second choice is to create you help contents within a second plugin, seperate to your application, and to place that exported plugin into the above named folder. The advantage of the second approach is that you do not have to deploy all the dependencies which your plugin has, which are not related to help. I however, went for the first option, simply because it then only need to do one export and each time I export my plugin in order to create a new release / upgrade to the application, I simply take that exported plugin and pop it onto my webserver.

Note B: Once you have completed Note A and all the other steps in the citation above, you can continue with the last steps of the documentation: " At this stage you can create a war file from the help directory or you can copy the directory and its contents to the webapps folder of your Tomcat installation. "

If your'e lucky, it all works and your online help looks great! If however, you are more like me, then you just get a blank help screen. OK, not too bad, the solution to this is that instead of the URL being http://yourdomain.com/help, it needs to have the index page appended: http://yourdomain.com/help/index.jsp.

In the web.xml of the help webapp, there was no welcome page descriptor. I added one, but that didn't help! I think it is because the web app parses the requested URL and then works with a virtual file system. But why Tomcat doesn't step in before hand if it sees no requested page, I do not understand. Anyway...

The next bit didn't fully work for me either. The infocenter loaded nicely, but the contents was empty. It only took a few hours of fiddeling, and here is what I discovered:

The web application loads the Eclipse workbench behind the scenes. This is based upon the Eclipse Equinox implementation of OSGi, which has a neat little command line where you can find out what services are deployed in the workbench.

Within the web.xml of the help webapp, there is a servlet start parameter which is commented out. Some postings that I found online even say that it MUST be commented out. Well not in this instance. Ensure the following is not commented out in your web descriptor:

  <servlet id="iehs">
    <servlet-name>equinoxbridgeservlet</servlet-name>
    <display-name>Equinox Bridge Servlet</display-name>
    <description>Equinox Bridge Servlet</description>
    <servlet-class>
      org.eclipse.equinox.servletbridge.BridgeServlet
    </servlet-class>
    .
    .
    .
    <!-- the following parameter enables 
            the OSGi command line!!
        -->
    <init-param>
      <param-name>commandline</param-name>
      <param-value>-console</param-value>
    </init-param>
    .
    .
    .
  </servlet>

Restart Tomcat, from a command line, without starting the process in the background (that is on say linux, do not add the & command after . catalina.sh run.

Once it has started and gives you the commandline message saying Server startup in x seconds, hit return. As if by magic, an OSGi prompt appears. On this prompt you can type help (or any unrecognised command) to get help. The ss command will list installed services with their state. Doing so gives the following output (click image for a larger picture), where BookStore_1.0.0 is my plugin containing the help contents.

My plugin (ID 6) is installed!! Great. But actually it needs to be active before it is of any use to me. So the next command I type is start 6, which should start my plugin, since it was listed with ID 6 (click image for a larger picture).

In the above picture, I have highlighted the problem. My plugin is dependent upon org.eclipse.tomcat and that is a missing resource. Well you might think that it is strange that the webapp is running in Tomcat and Tomcat is missing, but it is actually the Tomcat plugin that is missing in the Eclipse workbench environment, namely under the WEB-INF/eclipse/plugins directory. Add this plugin from your Eclipse plugins directory (or indeed your RCP application export plugins directory), as well as any other plugins upon which your plugin is dependent, restart Tomcat and everything should work.

If it still does not work, try stopping Tomcat, deleting the <tomcat-install-directory>/work directory, and restarting Tomcat. Tomcat has a working directory where it caches webapps and in this case it is not very good at cleaning up the Eclipse workbench environment (either during hot deploys or during restarts).

If that still does not work, iteratively use the OSGi command line to until your plugin has a state of <<LAZY>>. This state is fine, since it will get started when you call up the URL. In fact the lazy status may never change, but it is sufficient to indicate that your plugin is now loaded and ready to run in the help system.

Before deploying this webapp to a production environment, don't forget to comment out the OSGi command line parameter in the web.xml file.

Social Bookmarks :

Eclipse Help / Infocenter - Workbench Mode

Sun, 08 Jun 2008 09:13:00 GMT

Eclipse offers plugin authors the ability to add Eclipse Help to their plugins. Opening that help will give a nice window with searchable help, something like this (click on the image to see it in full size):

The following blog entry shows how to integrate help into an RCP application (or indeed a plugin or feature).

The first thing you need to do, is to extend your plugin.xml to tell your plugin that you want to have help. In the source view of your plugin.xml include the following extension points:

To go with these entries, you now need to add the help folder to your plugin project:

The html folder under the help folder contains simple HTML documents for each page of help that you want to write. The toc.xml file is the table of contents which defines what appears in the left pane of the help system when it is opened. The help_contexts.xml file contains mappings from "context names" to files which are relevant for that context. Contexts are used when opening context sensitive help, for example when pushing the F1 button.

An example of the toc.xml follows:

<toc label="BookStore"> <topic label="Introduction" href="help/html/general/overview.html"></topic> <topic label="Starting Up" href="help/html/general/startup.html"></topic> <topic label="The Process" href="help/html/general/process.html"></topic> <topic label="Screens"> <topic label="Customers" href="help/html/views/Customers.html"></topic> <topic label="Products" href="help/html/views/Products.html"></topic> </topic> <topic label="Frequently Asked Questions" href="help/html/general/faq.html"></topic> </toc>

An example of the help_contexts.xml follows:

<?xml version="1.0" encoding="UTF-8"?>  <contexts>  <context id="Glossary"> <description>Glossary</description> <topic label="Glossary" href="help/html/general/glossary.html"></topic> </context> <context id="CustomersView"> <description>Customer Relationship Management</description> <topic label="Customers Screen" href="help/html/views/Customers.html"></topic> <topic label="Customers Menu" href="help/html/menus/CustomerMenu.html"></topic> </context> </contexts>

Now before the help system will work, we need to do a few more things, namely:

Add dependencies
Add a help menu
Add context hooks

To add dependencies, you can open the .product file for your application (to export your plugin as an RCP application, you need to add a .product file). Open its configuration tab and click on the "Add Required Plug-ins" button. This should then add a list of all plugins upon which your plugin is dependent.

If this did not work, the following is a list of all the plugins which the BookStore plugin is dependent upon (if you open the .product file in the text editor, you can edit XML directly):

<plugins> <plugin id="BookStore"></plugin> <plugin id="com.ibm.icu"></plugin> <plugin id="javax.servlet"></plugin> <plugin id="javax.servlet.jsp"></plugin> <plugin id="org.apache.commons.el"></plugin> <plugin id="org.apache.commons.logging"></plugin> <plugin id="org.apache.jasper"></plugin> <plugin id="org.apache.lucene"></plugin> <plugin id="org.apache.lucene.analysis"></plugin> <plugin id="org.eclipse.core.commands"></plugin> <plugin id="org.eclipse.core.contenttype"></plugin> <plugin id="org.eclipse.core.databinding"></plugin> <plugin id="org.eclipse.core.expressions"></plugin> <plugin id="org.eclipse.core.jobs"></plugin> <plugin id="org.eclipse.core.runtime"></plugin> <plugin id="org.eclipse.core.runtime.compatibility.registry" fragment="true"></plugin> <plugin id="org.eclipse.equinox.app"></plugin> <plugin id="org.eclipse.equinox.common"></plugin> <plugin id="org.eclipse.equinox.http.jetty"></plugin> <plugin id="org.eclipse.equinox.http.registry"></plugin> <plugin id="org.eclipse.equinox.http.servlet"></plugin> <plugin id="org.eclipse.equinox.jsp.jasper"></plugin> <plugin id="org.eclipse.equinox.jsp.jasper.registry"></plugin> <plugin id="org.eclipse.equinox.preferences"></plugin> <plugin id="org.eclipse.equinox.registry"></plugin> <plugin id="org.eclipse.help"></plugin> <plugin id="org.eclipse.help.appserver"></plugin> <plugin id="org.eclipse.help.base"></plugin> <plugin id="org.eclipse.help.ui"></plugin> <plugin id="org.eclipse.help.webapp"></plugin> <plugin id="org.eclipse.jface"></plugin> <plugin id="org.eclipse.jface.databinding"></plugin> <plugin id="org.eclipse.osgi"></plugin> <plugin id="org.eclipse.osgi.services"></plugin> <plugin id="org.eclipse.swt"></plugin> <plugin id="org.eclipse.swt.win32.win32.x86" fragment="true"></plugin> <plugin id="org.eclipse.tomcat"></plugin> <plugin id="org.eclipse.ui"></plugin> <plugin id="org.eclipse.ui.forms"></plugin> <plugin id="org.eclipse.ui.workbench"></plugin> <plugin id="org.mortbay.jetty"></plugin> </plugins>

To add a help menu, edit your ApplicationActionBarAdvisor class. First add a help action as a class member variable:

   private IWorkbenchAction helpAction;

Next, in the makeActions method, add the following code to register the action:

        helpAction = ActionFactory.HELP_CONTENTS.create(window);
        register(helpAction);

Finally, in the fillMenuBar method, add the following bits of code:

        MenuManager helpMenu = new MenuManager(
                "&Help", 
                IWorkbenchActionConstants.M_HELP);
        .
        .
        .
        menuBar.add(helpMenu);
        .
        .
        .
        helpMenu.add(helpAction);

This will add a help menu to the main window of the application.

The last thing we need to do before the help system will work as an extra window within our application (Workbench Mode), is to add the context sensitive hooks. On any graphical component where the F1 key is pressed, the Eclipse workbench will look for a parent that has context sensitive help setup. If it finds such a parent, it will activate the help.

To enable context help for an item, add the following bit of code (here, for adding context specific help to a view):

        PlatformUI.getWorkbench().getHelpSystem().
                          setHelp(parent,"BookStore.CustomersView");

Note that the String has the prefix "BookStore.", but in the context XML above, the context IDs do not contain this prefix! The prefix is one of several things, I'm not really sure which! It could be the Application Name, the Plugin Name, or the TOC Label in the toc.xml file. It could even be the Topic which is somehow set for the help system. It's best to refer to the documentation for more details here.

Right, now that is all done, it is time to run your application and try out the F1 key and the new help menu.

Notice how the first page which the help shows is a standard Eclipse help page? Wouldn't it be great if it could be customised? Well, it can!

You simply need to add a line to your plugin_customization.ini file (this file can be added to applications in order to customize things like their default accelerator keys) like this:

    org.eclipse.help.base/help_home=/BookStore/help/html/home.html

In the above line, the new home page for the help needs to be located under help/html/home.html within your project. The name "/BookStore" which appears above, before the actual path to the file is this magical application or plugin name, discussed above.

All of the above work was done in Eclipse 3.3.0, although it should also work for Eclipse 3.2 as well as Eclipse 3.4 and later.

Social Bookmarks :