[tomee-patch-plugin] branch master updated: Create README.adoc

[db...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

dblevins pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/tomee-patch-plugin.git


The following commit(s) were added to refs/heads/master by this push:
     new a9b19c6  Create README.adoc
a9b19c6 is described below

commit a9b19c6fe0e39b71ab4a2066c91ca9106d5cfd01
Author: David Blevins <da...@gmail.com>
AuthorDate: Fri Mar 26 21:06:58 2021 -0700

    Create README.adoc
---
 README.adoc | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/README.adoc b/README.adoc
new file mode 100644
index 0000000..5633764
--- /dev/null
+++ b/README.adoc
@@ -0,0 +1,38 @@
+In the configuration of the plugin you can have a directive like the following:
+
+       <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>
+
+## select
+
+The `<select>` setting is what tells the plugin which binaries to modify.  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.
+
+## patchSources
+
+The `<patchSources>` list allows us to specify locations where *.java files live.  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.
+
+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.
+
+## replace/jars
+
+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."  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 [...]
+
+This setting could potentially also be used to do library upgrades via the patch plugin.
+
+## 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"