Example: Building a Plugin

I've been reading Practical Eclipse Rich Client Platform Projects by Vladimir Silva. I've read the first two chapters and skimmed the rest (there are 10 chapters). The first chapter is called “Foundations of Eclipse RCP,” but it doesn't discuss RCP. There is an introduction to creating a plugin with eclipse, which is certainly something you need to understand before building an RCP application.

The book has a copyright of 2009 (this year barely) but uses Eclipse 3.4. I'm using 3.6M6, and eclipse has changed a bunch, specifically in the way one installs/uninstalls plugins. With 3.5 we started to use the p2 updated sites. Copying a bunch of plugins into your plugins directory is no longer the way.

It's disappointing that a book with a 2009 date is so out of date. I do want to stick with Eclipse 3.6 and figure out how to do these installations and navigate the new UI because 3.6 is where it's at.

Each chapter ends with a hands-on exercise preceded by a discussion of the tools needed for the exercise. Sometimes the tools discussion reads like a group of unrelated facts with code snippet examples. The examples often seem out of context ... yes, there's this xml or this java code, but how does it fit into a working application. The hands-on exercise is supposed to provide that context, but in my opinion seldom succeeds.

Now what I said may sound that I am disappointed in the book, but I'm not. As I've said, I've only read the first two chapters and skimmed the rest. I will read the rest. I want to know how to make a standalone RCP application, but my skimming seems to show how only to run that RCP application from within eclipse. Maybe not, we'll see.

I'm using a Mac Book Pro with Snow Leopard.

The Hands-On from Chapter 1

I struggled with this, but I think my issues were mostly due to me and not the book. I downloaded the source code. Just looking at it was not enough for me. I had to import the project into my workspace. Once I did that, I could build my own identical project.

I'm thankful that this first project is not trivial. It actually does show stuff that I think will turn out to be useful later in the book. Here's a quote that describes what the first exercise is.

... you will write a plug-in to embed a tiny Jetty web server that uses Equinox to define a simple servlet class that returns the headers of the HTTP request.

Sticking Points

Here are some sticking points I had. I'm not faulting the book on these points. When you read the book carefully, these problems are answered. 

• The project doesn't come with a run configuration. Does it, and I don't know how to see it? I made my own.

When I tried to run this example, I got a permission denied error. I think this is because Jetty wants to start on port 80, but where that is specified I don't know. The way to fix this (and the book has a note on this, but says the note is specific to Linux and does not mention the Mac) is to add the following VM argument to the run configuration: -Dorg.eclipse.equinox.http.jetty.http.port=8080

I did not want to run as root (a bad thing). On the Mac, I don't know how to have eclipse run as root when I run by clicking my icon. I have to become root in a command line and start up eclipse from the command line.

• I kept running the example as I changed things and got a “port already in use” error. I needed to click on that red Terminate button in the console window before trying again. Yes, this is something I should have known.
  
  
• I didn't understand why I didn't see an osgi prompt in my console window (the prompt is osgi in lowercase). The way to fix not seeing the prompt is to add the Program argument -Console to the run configuration. This is actually mentioned in the book, but it says that Console starts the OSGi console. I was foolish enough to think that the Program argument -consolelog or the default VM argument -Dosgi.noShutdown=true did this. The book says that this VM argument is useful for examining the OSGi framework ... don't you need the osgi prompt for that?
  
  
• I didn't see the output. Wow, guess what ... you have to start up an external browser and point it to http://localhost:8080/servlet. That servlet is the alias which appears under Extension Element Details, and it isn't the default.
  
  
• I wasn't including enough bundles in the run configuration's target platform. I unselected all the bundles under Target platform and then selected only those I had included in the Required Dependencies under the Dependencies tab in the Manifest editor. The correct way to do this is to deselect everything under Target platform, ensure that only the correct workspace is selected and then click the Add Required Bundles button.
  
  It is beneficial to select the Only show selected bundles checkbox. There are (in my configuration) 375 possible bundles. They don't fit on the screen, and you have to scroll to see what is selected. This method shows that 23 bundles are selected, a lot more than those four that I put into the manifest.

How the Application Looks When It Runs

Here's how the application looks when run. I did an ss at the osgi prompt to display its registered bundles. At this prompt you can start and stop bundles. To stop ch01a_1.0.0, issue stop 27. To start it, issue start 27.

Here's the output from http://localhost:8080/servlet1. Yes, I changed my alias from servlet.

Here's how it looks from within eclipse.

 

How to Configure the Project 

1. File -> New Project and choose Plug-in Project. I called it ch01a (my imported project from the source download was ch01). Even in Eclipse 3.6M4, you select the Eclipse version 3.5; 3.6 is not in the dropdown because 3.6M4 is still a milestone release.
2. Click Next. I removed the .qualifier from thePlug-in version, just because it wasn't in the book's figure.
3. Ensure that “This plug-in will make contributions to the UI” is unchecked.
4. Click Next. The Manifest editor opens up.
5. Click on the Dependencies tab and add the plugins: javax.servlet, org.eclipse.equinox.http.jetty, org.eclipse.equinox.http.registry, org.eclipse.equinox.http.registry, and org.eclipse.equinox.http.servlet. Note that the selection window that comes up is blank, but bundles appear when you type in the “Select a Plug-in” box.
6. Click on the Extensions tab. Add the extension point org.eclipse.equinox.http.registry.servlets. A class name and alias appears on the right under Extension Element Details. Change the alias.
7. Click on class. In the window that appears, type in javax.servlet.http.HttpServlet for the superclass.

 

The Source Code

I'm not going to show the code. It's not my code. It's available in the source code download from http://www.apress.com. Although the book recommends Apache Log4j, the example uses the Commons Logging service that comes with eclipse.

Good stuff to learn by reading it. There are two java files: Activator.java and Servlet1.java (the book has Servlet.java).

Other References

I found the link http://www.eclipse.org/equinox-portal/tutorials/server-side/ which is helpful. It has a similar but simpler example.

How do Java projects made with Eclipse work outside of Eclipse?

I usually work within Eclipse, but sometimes I get questions like can you run an application built with Eclipse from the command line? And you can. It's pretty straightforward, and I don't know if I'm doing it in the best way. But here is what I did. I have two examples.

First Example: Hello World

The first is just a Hello World. I'm using Eclipse 3.6M4 on the Mac. I made a Java project with File-> New -> Java Project. I called the project com.ted.hello. I made an empty package in the project and then added a class called Hello. Run it as a Java Application from within Eclipse, and it looks like the following. It prints out “hello java” to the console.

 

My workspace is /Users/ted/EclipseProjects/work36M4RCPA. Don't ask why the workspace is called that. I was just trying out some RCP applications earlier and used an existing workspace.

To run this Hello Java program from the command line, go into the directory /Users/ted/EclipseProjects/work36M4RCPA/com.ted.hello/bin. The structure under bin looks like

newtricks:bin ted$ find .
.
./com
./com/ted
./com/ted/hello
./com/ted/hello/Hello.class
newtricks:bin ted$

Run the application as

newtricks:bin ted$ java com.ted.hello.Hello
hello java
newtricks:bin ted$

Second Example: Using Log4j

Yes, I wanted to use Apache Log4j. This lets me address the classpath issue ... like finding the log4j.properties file and the log4j jar. Here's how it looks when run from within Eclipse.

I'm using the 1.2.15 version of log4j, which is the stable version that most people use. You download it in a zip that contains the log4j-1.2.15.jar. The later versions are alpha and beta, and you have to get them from apache's svn repository and build it yourself.

Add log4j-1.2.15.jar to the project's Java Build Path. Right click the project, choose Properties, choose Java Build Path, select the Libraries tab, click the Add External JARs button, and browse to the jar's location. I also had to tell the project how to find log4j.properties. I did this by adding a resource filter. Right click the project, choose Properties, choose Resource Filters, and click the Add button. Select the radio buttons Include and Files. Then, type log4j.properties in the Pattern: textbox.

To run this Logging program from the command line, go into the directory /Users/ted/EclipseProjects/work36M4RCPA/com.ted.log/bin. The structure under bin looks like

newtricks:bin ted$ find .
.
./com
./com/ted
./com/ted/log
./com/ted/log/Logging.class
./log4j.properties
newtricks:bin ted$

I have to set my CLASSPATH variable to point to the log4j.jar and my current directory (which is where the log4j.properties is). Mac has the bash shell so here is the command for that (I originally forgot to export).

newtricks:bin ted$ CLASSPATH=/Users/ted/Downloads/Log4j/apache-log4j-1.2.15/log4j-1.2.15.jar:.
newtricks:bin ted$ export CLASSPATH

newtricks:bin ted$ env |grep CLASS
CLASSPATH=/Users/ted/Downloads/Log4j/apache-log4j-1.2.15/log4j-1.2.15.jar:.

newtricks:bin ted$ pwd
/Users/ted/EclipseProjects/work36M4RCPA/com.ted.log/bin

newtricks:bin ted$ java com.ted.log.Logging
0 [main] INFO com.ted.log.Logging - hello log
write hello
1 [main] INFO com.ted.log.Logging - goodbye log

Summary

So running the Java application form the command line is as you would suspect pretty straightforward. You just have to be in the right directory, use the navigation from your package, and in the case of the second example, set the classpath correctly.

Well, I got this Mac, and I kind of really like it. It's a MacBook Pro with 4 GB of memory.

What did I find that I was unhappy with? It came with Java 1.5, but I was able to get Java 1.6 but not the update I wanted. Mac seems to lag somewhat behind the Java updates.

Now, of course, I'm running Eclipse. What else? When I install ECF the ECF web page tells me to use http://download.eclipse.org/rt/ecf/2.0/3.4/updateSite/site.xml Well, I have to take off the site.xml to get it accepted as an update site.

Here's a pdf that describes how we did jar signing for the last Eclipse/ECF release. This may not be optimal but it worked for us, and we are looking at ways to improve.

AutoBuild002.pdf (299.54 KB)

The Skype provider for Eclipse/ECF Ganymede does not work. It seems a build issue and not a coding issue. We need separate features for Eclipse/ECF on Linux and Eclipse/ECF on Windows. I made an Eclipse/ECF 3.4 Skype on Linux update site. It is available at http://ecf1.osuosl.org/update/2.0Linux/site.xml.

To use Skype with Eclipse Ganymede, first install ECF. Then, go to Help->Software Updates->Available Software->Add Site and put in the above URL for the location.

The following PDF describes how to build this Linux-specific update site.

BuildingSkypeUpdateSite.pdf (1.01 MB)

Here's that BeeeP banner

BeeePbanner.zip (12.24 KB)

Here is the Joomla template used on the IEEE prototype. Our IEEE blog doesn't let us upload zips.

ieeeTemplate.zip (52.01 KB)

 -ted

Do you use Eclipse? This is a neat event .... I went to it last year. Rapid-fire presentations (10 to 15 minutes each) about local Eclipse projects. It's a great way to find out what's happening locally in the Eclipse community. And a great way to check out volunteer opportunities. See you there!

Eclipse Foundation / Instantiations
Eclipse DemoCamps 2008 – Ganymede Edition/Portland
June 24, 2008
7pm – 9pm

McMenamins Kennedy School, Parsons Room

Complimentary; attendance is limited

To register, complete one of the following:

• Add your name as presenter or attendee to this wiki http://wiki.eclipse.org/Eclipse_DemoCamps_2008_-_Ganymede_Edition/Portland
• Contact Tina Kvavle at Instantiations.

Content will evolve as presenters sign up, but visit http://wiki.eclipse.org/Eclipse_DemoCamps_2008_-_Ganymede_Edition/Portland/Demo_Descriptions to see what is being offered so far.

I found myself needing to do this after not having done it for several years. So I had to refresh my memory and here is a PDF that contains my notes. In fact, what I really wanted to do was have an ant file that automatically tagged what I just built with the date (an ant file that runs under CruiseControl). And that's working (I think), but the PDF contains my preliminary notes.

cvsDocs.pdf (352.81 KB)