JarPlug: Say Goodbye to File Explorer!

White Paper

Related Resources:
jar-plug home-page at sourceforge.net simontuffs.com home-page licensing information contact us SourceForge.net home-page
Copyright P. Simon Tuffs, 2004. All Rights Reserved.Version 0.5.0

JarPlug: Say Goodbye to File Explorer!

by P. Simon Tuffs, Software Architect and Consultant ( www.simontuffs.com )

If you've spent any time doing Java programming with Eclipse it must have occurred to you that support for viewing and editing Jar files is a little limited. Having used Eclipse for over eighteen months, and since I hadn't yet built an Eclipse plugin, I decided to dive right in and build a viewer/editor that would let me stop using File Explorer or WinZip(1) for manipulating the Jar files in my projects. Hopefully forever.

Five days later here it is: JarPlug, the Java ARchive PLUGin for Eclipse (sorry... :). And what days: going up the learning curve of Eclipse plugin internals and trying to figure out a workflow paradigm for editing Jar files that made sense inside the Eclipse IDE. More on that later.


Use the Eclipse 3.0 Update Manager, pointed at http://www.simontuffs.com/jar-plug You'll notice there are two features in JarPlug now: JarPlug itself, and a new capability called JarLaunch. JarLaunch provides the ability to run or debug an executable Jar file from the explorer context menu (right-click).

Once installed you may have to restart Eclipse, but you should see a new JarPlug tabbed-pane next to the Outline view in all your perspectives. If not, go "Window|Show View|Other|Java|JarPlug" and it should show up. It might show up somewhere else, in which case just drag it to where it should go (see following screenshots for ideas).

Let's take a look

Here's a typical application in Eclipse: the J2EE tutorial as hosted by JBoss.

Fig.1: Duke's Bank

Fig.1: Duke's Bank under JBoss in Eclipse

Notice that I've expanded one of the JAR files commons-beanutils.jar in the package explorer, and selected the LICENSE.TXT into the editing window. It's here that the first limitation of the built-in Eclipse Jar support become apparent: you can't edit the file you selected. In this case that's probably a good thing, but sometimes this just gets in the way.

More problematic is the next situation: a Jar file which is not on the classpath of the project is selected in the package explorer:

Fig.2: Jar file off the classpath

Fig.2: A Jar File off the Classpath

This time there is no view into the internal structure of the file in the package explorer, and the results of double-clicking on the test.jar file are entertaining, but not useful. Now let's activate the JarPlug view:

Fig.3: The JarPlug View

Fig.3: The JarPlug View

The structure of the Jar is now revealed: 117 entries (not including directories), displayed in a tree-view format. So what can we do now? Let's edit one of the XML files at the top level. Double-click on the build.xml file in the JarPlug view and something very interesting happens. Or a number of things.

Fig.4: Extracting and Editing

Fig.4: Extracting and Editing

  1. JarPlug automatically extracts the file into the workspace. It puts it under a directory tree named $jarplug.work and further under a folder named test.jar.$work. Why? Because in Eclipse pretty much everything depends on resources having a real physical presence in the filesystem (see FAQ 285 in the Eclipse 3.0 FAQ Reference)
  2. JarPlug opens the package explorer tree and selects the extracted file.
  3. JarPlug automatically opens an editor for the extracted file.

You can now edit this file (of course, it is the copy in the file-system which is being edited, not the version in the Jar-File). We'll get to that shortly.

Deleting things

I often find myself needing to delete things from the Jar files that I have built, those things that crept in there because I was sloppy with my Jar Packager (jardesc) setup. Let's suppose that we don't want any of the top-level resources that are present in the test.jar file, build.xml through WSClient.class. Simply select the nodes you want to delete in the JarPlug view, right-click, Delete, and they're gone. Well sort-of.

Fig.5: Deleting

Fig.5: Deleting

The selected nodes are actually placed into a pending-delete state; when the archive is finally updated they will be gone from it. So far, nothing has changed in the original archive. Nor will it: one of the principles behind the design of JarPlug is the principle of least surprise: you will be aware of what you are doing when you are doing it, or will be told about it. Onward... Why does the deletion mark next to build.xml appear grayed out? Because it has been marked for delete, but there is a copy of this file under the $jarplug.work directory tree, and this copy takes precendence (as you might think it should). Least surprise.

Putting it all back together again

So now we have a JAR file, we've extracted and possibly edited one member, marked a number of them for deletion, but we haven't committed anything to a new archive yet. The final step is to push the Update Archive button on the view toolbar (also on the context menu), and some more interesting things happen.

Fig.6: Updating

Fig6. Updating

After the file has been updated, the Eclipse IDE looks like this:

Fig.7: Updated

Fig7. Updated

Notice that a new file has been created, with the same name as the original file, but in a different location under the $jarplug.work/... folder. It would be too surprising in many ways to overwrite the original file: if you wish to do that, you have to move the new file into the location of the original file.

As you would expect, this new file is missing the things we deleted, but it does contain the build.xml file which we edited, and which was marked for pending delete (but shown as being in a conflicted state)

Why such caution? Suppose you were editing one of the files on the project classpath. What would happen if you suddenly replaced it behind the scenes with an updated Jar? Probably not nice things, and most likely surprising things.

The conservative workflow of JarPlug should prove to be acceptable for most applications, it wouldn't be hard to put in a properties page to commit updates over the original files, and since Eclipse automatically keeps track of deleted resources for you, recovery would always be possible.

Off We Go!

Assuming that the Jar-file you've built is executable, i.e. that it has a META-INF/MANIFEST.MF file that contains a Main-Class property, wouldn't it be nice to run or debug that Jar file inside Eclipse? Well now you can, courtesy of JarLaunch. JarLaunch is a second plugin with the JarPlug featureset, and it looks like this:

Fig.8: JarLaunch

Fig8. JarLaunch

A simple right-click against the Jar file you want to run, and it launches, with or without a debugger attached. The first time you launch a Jar for debug this way, the debugger will probably not be able to find the source code if you've set a breakpoint. You can remedy this in the usual manner, and this new source-path will be persisted for the next launch. Indeed, all JarLaunch does is fire up the normal Eclipse launcher, and you can fire up the normal Eclipse launch configuration manager using Configure Run or Configure Debug

What else?

Here are some other things to be aware of in JarPlug:


JarPlug is released as early-access open-source: there are many improvements that could be made, the source-code contains 29 TODO items and there are plenty of other things beyond that. So if you find it useful, have the needs and the skills, please get involved in the development project at http://www.sourceforge.net/projects/jar-plug

Or, if you're a major corporation with lots-o-money and can spare a bit, I'd be happy to make it jump though your hoops.

The most urgent task is a code refactoring and cleanup, as would be expected of a five-day rapid prototyping exercise using the test-driven-design approach it's not as pretty as it could be. Indeed, the complexity collapse which usually occurs in early-stage software development like this hasn't happened, and there are far to many special cases for my comfort level. These issues will be resolved given time. Meanwhile, I hope you find this a useful tool, and I look forward to getting your feedback.


Bugs? What Bugs? Probably a few. Maybe lots. Go find them, I'll fix them if I have the time, but remember: the source-code is available on Sourceforge through the CVS archive of the project and its ready to go as an Eclipse 3.0 Plugin Project, Feature, and Site. Enjoy!
(1)WinZip is a registered trademark of WinZip Computing Inc.

If you like JarPlug then you might want to check out some of the other Open-Source projects developed by simontuffs.com:
Deliver Your Java Application in One-JAR XML Instance Generator Java Network Benchmark simontuffs.com