View source for RAP/Patch Fragments

<b>This is experimental! Not officially supported by RAP or Equinox.</b>

Note: See also "[http://wiki.eclipse.org/Steps_to_use_Fragments_to_patch_a_plug-in Steps to use Fragments to patch a plug-in]".

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%3F|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):

[[Image:Fragment-project.jpg]]

===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.

[[Image:Fragment-build.jpg]]

===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:

<pre>
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
</pre>

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 [[https://bugs.eclipse.org/bugs/show_bug.cgi?id=126687 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:

[[Image:Fragment-structure.jpg]]

Now we just open that java file, add a new style bit (for example <code>SWT.RIGHT_TO_LEFT</code>) 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 bug 195732]


Q: I cannot contribute to the same package

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

[[Category:RAP]]