RAP/Patch Fragments

THIS IS EXPERIMENTAL! IT IS NOT OFFICIALLY SUPPORTED NEITHER BY RAP NOR BY EQUINOX

From time to time it is desirable to add new classes to the existing infrastructure of RAP or to extend existing classes by adding new method which are not yet (or never will) be implemented in RAP. To not touch the source of the bundles in your target platform we introduced the possibility to patch existing bundles with a fragment. For more informations about why this is a twilight zone take a look at FAQ_Can_fragments_be_used_to_patch_a_plug-in?.

Creating the fragment

First we need to create a new Fragment project in our workspace which will contribute the new/replacing classes. As host plugin define the bundle we want to patch. For this example we will use the RWT plugin (org.eclipse.rap.rwt):

Setup build instructions

All RAP bundles expect a file called patch.jar on their classpath to use for the patch scenario. Thus we need to let the fragment build such a jar file. Just fire up the manifest editor of your fragment, switch to the build tab and add a new library with the according source folder.

Make PDE happy

PDE doesn't know anything about our doing here. We just need to add a new (inofficial) header to the MANIFEST.MF file so PDE knows about what we are doing. The MANIFEST.MF of the fragment should look something like this:

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Rwt_patch Fragment
Bundle-SymbolicName: rwt_patch
Bundle-Version: 1.0.0
Fragment-Host: org.eclipse.rap.rwt;bundle-version="1.0.1"
Eclipse-PatchFragment: true

The last line is the important one to tell PDE that our project will patch the host bundle. This header is not part of the official specification. See [this bug] for more informations.

Put the source into the fragment

We now have a patch-fragment which is able to override existing classes in the original RWT bundle. As an example we will introduce a new SWT style bit in order to built our projects which heavily rely on this style bit. As we can only override the whole class we need to get a copy of the original org.eclipse.swt.SWT class, copy it to our fragment into the same package as the original one resides:

Now we just open that java file, add a new style bit (for example SWT.RIGHT_TO_LEFT) and save it. Now all references to this style bit which had errors before (as we didn't had that constant a minute ago) will now compile. Note that this will only solve the compile errors. If you need new functionality you're on your own to implement this.

Troubleshooting

Q: I don't see the exported packages

A: See https://bugs.eclipse.org/bugs/show_bug.cgi?id=195732

Q: I cannot contribute to the same package

A: https://bugs.eclipse.org/bugs/show_bug.cgi?id=173673 (this will be relevant when RAP builds are signed for release train)