Enabling command-line applications for your Eclipse projects
May 5, 2008 7:00 AM
Filed Under: Eclipse and Open Source
Hi all...
Recently in DTP we came across an opportunity to provide admin-level support for some import/export type functionality within Connectivity. And it was discussed that this would be best done as a command-line application, since administrators may not have access to or wish to use the full blown Eclipse UI to handle this task.
So we started doing some digging and discovered that there's this very cool framework within the Eclipse platform to handle just this kind of thing. A bit of Googling turned up this presentation from EclipseCon 2006:
Though the Eclipse platform has changed a bit since Jeffrey wrote his article, it got me going the right direction. So I thought we'd update it for Eclipse 3.3.2.
Here's the steps we did to create this sample project...
1) Create a new plug-in project.
2) Make sure to un-check the "This plug-in will make contributions to the UI" checkbox.
3) Uncheck any available plug-in templates.
And voila, you have a new plug-in.
4) Go to the Extensions tab of the Plug-in/Manifest Editor. Add a new Extension. Select the "org.eclipse.core.runtime.applications" extension point. Click Finish when you're done.
You have a new "application" node beneath your org.eclipse.core.runtime.application extension.
5) Select the actual extension point node in the tree and note the ID of the application. This is important (I learned this the hard way). You want to provide something unique here that's not too long. It gets prefaced by the ID of your plug-in when you try to run it later.
It defaults to "idX". Call it whatever you want. In this case, we'll call it "CoolApp". The full ID is then my.cool.application.CoolApp when we go to run this later.
6) Go back to the "application" node, right-click and click New->Run. This adds the node that specifies the class you're going to run in command-line mode when you invoke your plug-in application.
7) Click the class* link to create the application class. Our application class will implement the org.eclipse.equinox.app.IApplication interface. Give it a name ("CoolApplication" in our case) and click Finish.
So you end up with the beginnings of your application class:
8) In our case, we're just testing out this functionality, so we don't have to get too fancy. In the Start method, you get an IApplicationContext object, which gives you a whole lot of information about the command line parms that were passed in.
So we're going to add some code to check out those command line parms and just write them out intelligbly.
public Object start(IApplicationContext context) throws Exception {
// get the arguments
Map args = context.getArguments();
if (args.isEmpty()) {
// if there were no arguments, simply write "hello cool world"
System.out.println("hello cool world...");
} else {
// otherwise iterate through the arguments and print them as
// "key = value" pairs after "hello cool world"
Iterator iter = args.keySet().iterator();
while (iter.hasNext()) {
Object key = iter.next();
String output = new String();
if (key instanceof String) {
output = output + (String) key + "=";
}
Object value = args.get(key);
if (value instanceof String) {
output = output + (String) value;
}
System.out.println("hello cool world, " + output);
}
}
// And now we can attempt to get some input and respond from stdio
BufferedReader stdin = new BufferedReader
(new InputStreamReader(System.in));
String message; // Creates a variable called message for input
System.out.print ("Enter the message : ");
System.out.flush(); // empties buffer, before text is input
message = stdin.readLine();
System.out.print("You ");
System.out.println("entered : " + message);
// make sure to return an OK message
return EXIT_OK;
}
So now we save our class, make sure everything compiles and builds.
9) Then we export it as a deployable plug-in.
Pick the directory where you want the jarred plug-in to be written to. In my case, I want it to be installed directly in my Eclipse plug-ins directory (the "plugins" directory is added after the directory you specify as the destination). If you put the exported plugin somewhere else, you'll have to copy it into your Eclipse/plugins directory manually. Click Finish and it will put the plug-in where you specified.
10) Now head out to a console window. Assuming you have your Java environment set up correctly, all you should have to do to run the application is go to your Eclipse directory and type:
eclipsec -nosplash -application my.cool.application.CoolApp
And that's all there is to it! I know we're going to look into using this sort of application in the future to provide some command-line import/export functionality when we get a chance.
Hope this helped you out. The Eclipse Platform has lots of cool bits that most of us User Interface people never see!
Until next time... Keep on programming!
--Fitz
Comments
lucas email - my-naked-truth.blogspot.com
Very cool stuff indeed !
I was thinking about using this mechanism along with a apche CLI (comand line) processor in order to selectively reuse some core APIs defined into plugins in a "batch" (hmmm ... application) mode thanks to command line options/arguments.
This approach would allow to reuse plenty of code designed into clean "runtime/core" layers of existing frameworks.
For instance EMF already does some "batch" generation in the same vein, it actually inspirates me a lot !
thanks for having shared that !
Brian Fitzpatrick email - blogs.sybase.com/blogger_rss/brian_fitzpatrick_.xml
Glad to help! That sounds like a good re-use of code. I hadn't seen any good references on how to do this sort of thing before and decided someone else might benefit from knowing how to do it. Hope it works for you!
Chris Aniszczyk email - mea-bloga.blogspot.com
Thanks for the free PDE advertising :)
Alex Blewitt email - alblue.blogspot.com
Why are you creating one with a BundleActivator? It's not like you need one for this example, and if you don't need one, it's probably better not to have one. Still, the article helps, good work.
You might also like to read http://www.eclipsezone.com/eclipse/forums/t99762.html and similar entries in the series.
Alex
Brian Fitzpatrick email - blogs.sybase.com/blogger_rss/brian_fitzpatrick_.xml
Chris - you're welcome!
Alex - Good question about the activator. You're absolutely right that we don't really need it in this case. Getting rid of it would slim this example down even further. Great article in your forums on the same thing... Wonder why that didn't turn up in my Googling?!
