isabella232 / tomee-patch-plugin

Apache TomEE Patch Plugin

In the configuration of the plugin you can have a directive like the following:

<plugin>
  <groupId>org.apache.tomee.patch</groupId>
  <artifactId>tomee-patch-plugin</artifactId>
  <version>0.4-SNAPSHOT</version>
  <configuration>
    <select>tomee-plume-webapp-transformed-.*\.war</select>
    <patchSources>
      <source>${project.basedir}/../../transform/src/patch/java/</source>
      <source>${project.basedir}/src/patch/java/</source>
    </patchSources>
    <replace>
      <jars>
        <jakarta.faces-3.0.0.jar>org.glassfish:jakarta.faces:jar:3.0.0</jakarta.faces-3.0.0.jar>
        <eclipselink-3.0.0.jar>org.eclipse.persistence:eclipselink:jar:3.0.0</eclipselink-3.0.0.jar>
      </jars>
      <resources>
        <openejb-version.properties>${project.build.outputDirectory}/openejb-version.properties</openejb-version.properties>
      </resources>
    </replace>
  </configuration>
  <executions>
    <execution>
      <goals>
        <goal>run</goal>
      </goals>
      <phase>package</phase>
    </execution>
  </executions>
</plugin>

Select what archives to patch

The <select> setting is what tells the plugin which binaries to modify. Its value is a regular expression.

<configuration>
  <select>tomee-plume-webapp-transformed-.*\.war</select>
</configuration>

In the above setting we’re saying we want to patch the output of the Eclipse Transformer. The input to the transformer is the regular tomee-plume-webapp-9.0.0-M123-SNAPSHOT.war file and the output is a new tomee-plume-webapp-transformed-9.0.0-M123-SNAPSHOT.war file. It’s the "transformed" file we want to further patch.

Source Java Files

The <patchSources> list allows us to specify locations where *.java files live. The following configuration is enabled by default and does not need to be specified:

<configuration>
  <patchSources>
    <source>${project.basedir}/src/patch/java/</source>
  </patchSources>
</configuration>

Multiple locations can be specified, for example:

<configuration>
  <patchSources>
    <source>${project.basedir}/src/patch/java/</source>
    <source>${project.basedir}/../../transform/src/patch/java/</source>
  </patchSources>
</configuration>

Being able to have multiple locations for patch files keeps us from having to duplicate patch files as we build multiple war files in multiple modules. The above configuration says grab the *.java files from the transform module and the *.java files from this module.

We will copy these into the target/ directory and compile them using any *.jar files we find in the war file to create the classpath. These compiled classes are then used to overwrite any classes by that name in any part of the war or its libraries. This is how we handle corner cases that are too complicated to deal with using bytecode tools — we can just specify an alternate source file.

Excluding Specific Java Source Files

In the situation where you want to exclude certain java packages from the patching process, you can exclude them via <sourceExcludes> as follows:

<configuration>
  <sourceExcludes>
    <exclude>org/apache/cxf</exclude>
  </sourceExcludes>
</configuration>

The above will skip all sources found under the org/apache/cxf package directory. This can be nice when trying a library upgrade to see if something that previously needed a patch is now fixed.

Adding Dependencies for compiled patches

If the sources have dependencies on jars not found in the zip itself, those can be added to the configuration as follows.

<configuration>
  <dependencies>
    <dependency>org.apache.aries.blueprint:blueprint-parser:jar:1.6.0</dependency>
    <dependency>org.apache.aries.blueprint:org.apache.aries.blueprint.api:jar:1.0.1</dependency>
    <dependency>org.apache.aries.blueprint:org.apache.aries.blueprint.core:jar:1.10.2</dependency>
    <dependency>org.apache.tomcat:tomcat-servlet-api:jar:10.0.4</dependency>
    <dependency>org.osgi:org.osgi.core:jar:6.0.0</dependency>
    <dependency>org.osgi:osgi.cmpn:jar:6.0.0</dependency>
    <dependency>org.ow2.asm:asm:jar:9.1</dependency>
    <dependency>org.springframework:spring-aop:jar:5.3.6</dependency>
    <dependency>org.springframework:spring-beans:jar:5.3.6</dependency>
    <dependency>org.springframework:spring-context:jar:5.3.6</dependency>
    <dependency>org.springframework:spring-core:jar:5.3.6</dependency>
    <dependency>org.springframework:spring-webmvc:jar:5.3.6</dependency>
  </dependencies>
</configuration>

Note that transitive dependecies are not supported, so each jar directly needed to compile must be specified individually.

Repacing Jar files in the Archive

The <replace><jars> list allows us to tell the plugin, "when you see a jakarta.faces-3.0.0.jar in the war file, replace it with the org.glassfish:jakarta.faces:jar:3.0.0 artifact from our local maven repo."

<configuration>
  <replace>
    <jars>
      <hibernate-validator-7.0.0.Final.jar>org.hibernate.validator:hibernate-validator:jar:7.0.0.Final</hibernate-validator-7.0.0.Final.jar>
      <jakarta.faces-3.0.0.jar>org.glassfish:jakarta.faces:jar:3.0.0</jakarta.faces-3.0.0.jar>
      <eclipselink-3.0.0.jar>org.eclipse.persistence:eclipselink:jar:3.0.0</eclipselink-3.0.0.jar>
    </jars>
  </replace>
</configuration>

We can use this to effectively restore any jars we do not want the Eclipse Transformer to modify. This will be any jar file that already fully supports the Jakarta namespace, like the latest Eclipselink, Mojarra or MyFaces. Of course in theory the Transformer shouldn’t have a negative impact on jars that already support the new namespace, but why risk it when it’s easy to gain 100% confidence the jar we ship is byte for byte the same one produced by the respective project.

This setting could potentially also be used to do library upgrades via the patch plugin.

Warning

At the moment this will maintain the original file name as found in the jar. If you replace an old green-1.2.3.jar with a newer green-2.0.1.jar, the file name will still be green-1.2.3.jar but the contents will be green-2.0.1.jar. A PR to fix this is welcome.

replace/resources

The <replace><jars> list allows us to tell the plugin, "when you see an openejb-version.properties file anywhere in the war file or its libraries, replace it with the specially modified version from target/classes/." In the module we’re generating a new openejb-version.properties so we can change the version TomEE reports from "8.0.7-SNAPSHOT" to "9.0.0-M7-SNAPSHOT"