How to apply Java code changes to WSO2 server on the go?

Do you want to easily push changes to the running server without having to build the pack over again? Then this article is for you.

Photo by Goran Ivos on Unsplash

When you are actively building WSO2 Products, it will be a real hassle to do a simple java code change and rebuild the entire pack over again to see if the change you did actually works. Urgh it sucks! 😖

In this article I will show you how this can be easily overcome. It’s very simple.

I will take the code base of WSO2 API Manager for example here. Consider this file in the carbon-apimgt repository. Assume that you want to do a change in this file.

Question: When you have an already built WSO2 API Manager pack running in your machine, how can you apply the new fixes to this existing pack without building a new one?

  • Now you can see that the file here is located inside the parent package org.wso2.carbon.apimgt.impl. Assume you did a change in this file. And you can see that if you build this impl package alone, you will get a .jar file in its target folder. This newly built .jar has your changes in it.
  • In the WSO2 API Manager pack(server) that you are running in your machine right now, all these component .jar files are packaged inside the <API-M_HOME>/repository/components/plugins folder.
  • You will be able to see a .jar file with a similar name like this in the plugins directory.


  • This is the original .jar file of the impl package that you got when building the entire pack before. With this structure in place, there is an easier way to apply the new changes to the existing pack without building a new one. Can you see it now?
  • You guessed it right. But we are not going to replace this .jar with the new impl package .jar file. 🤓
  • You can see that there is another folder named patches in the <API-M_HOME>/repository/components directory. We are going to put the new impl jar into this as a patch.
  • Create a new folder named patch9999 inside the patches folder and put the new .jar into it.
  • Rename the jar by replacing the hyphens with underscore and dot respectively as follows.

org.wso2.carbon.apimgt.impl-6.8.127-SNAPSHOT.jar → org.wso2.carbon.apimgt.impl_6.8.127.SNAPSHOT.jar

  • Remember that the version of this jar should be the same as the original jar present in the plugins folder above. If the existing version is different from the newly built jar, you will have to rebuild the entire pack. No choice otherwise. 😐 The version can change if you fetched code from upstream after originally building the pack and later built the impl jar with your change. If an auto release has been triggered in the upstream git repository, the versions change automatically. Got it?
  • Now you must restart the server for the changes to take effect. When the server restarts, you will see the following log in the terminal to indicate that the patch changes are detected and applied.
INFO {org.wso2.carbon.server.extensions.PatchInstaller perform} — Patch changes detected
INFO {org.wso2.carbon.server.util.PatchUtils applyServicepacksAndPatches} — Backed up plugins to patch0000
INFO {org.wso2.carbon.server.util.PatchUtils checkMD5Checksum} — Patch verification started
INFO {org.wso2.carbon.server.util.PatchUtils checkMD5Checksum} — Patch verification successfully completed
  • What is this Backed up plugins to patch0000” log above? After restarting the server, you will see a new folder created alongside patch9999. That is patch0000 to which the original jar files present in the plugins directory are backed up before applying the new change. Now the impl package jar file found inside the plugins folder is the newly changed jar. So do not delete the patch0000 folder as it is a backup of the original and you need it if you want to go back to the original state.
  • So now let’s see the steps in summary below.

1. Navigate to the parent package of the java file where you did the change and build it by executing the mvn clean install -Dmaven.test.skip=true command skipping the tests.

2. Put the jar into patches9999 folder inside <API-M_HOME>/repository/components/patches directory after renaming the file replacing hyphens with underscore and dot respectively.

3. Restart the server.

Now you can make your development journey more effective with this approach. Isn’t it? 🙂

Bonus Tip : If you want to remove the change you just applied to the pack, simply remove the patch9999 folder and restart the server.

Thank you for reading the article!

If you find any outdated content or issues with this article, please feel free to create an issue at Developer Corner Git repository here. Let’s grow together and help others in their journey too!

If you like this article please give it a clap. 🙂


Software Engineer @ WSO2 | Software Engineering Graduate from the University of Colombo School of Computing

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store