You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tomee.apache.org by db...@apache.org on 2020/09/04 01:03:53 UTC
[tomee] 03/04: Javadoc and minor fixes TOMEE-2706 New TomEE
Embedded Bootstrap
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.git
commit e029f8b23d4c0a9ad412670e86a2c53550f12799
Author: David Blevins <da...@gmail.com>
AuthorDate: Tue Sep 1 12:41:01 2020 -0700
Javadoc and minor fixes
TOMEE-2706 New TomEE Embedded Bootstrap
---
boms/tomee-microprofile/pom.xml | 2 +-
boms/tomee-plume/pom.xml | 2 +-
boms/tomee-plus/pom.xml | 2 +-
boms/tomee-webprofile/pom.xml | 2 +-
.../org/apache/tomee/bootstrap/GenerateBoms.java | 188 ++++++++++++++++++++-
.../src/test/resources/pom-template.xml | 10 ++
6 files changed, 196 insertions(+), 10 deletions(-)
diff --git a/boms/tomee-microprofile/pom.xml b/boms/tomee-microprofile/pom.xml
index 550b910..59d75ae 100644
--- a/boms/tomee-microprofile/pom.xml
+++ b/boms/tomee-microprofile/pom.xml
@@ -1302,7 +1302,7 @@
</dependency>
<dependency>
<groupId>org.apache.tomee</groupId>
- <artifactId>openejb-javaagent.jar</artifactId>
+ <artifactId>openejb-javaagent</artifactId>
<version>${project.version}</version>
<exclusions>
<exclusion>
diff --git a/boms/tomee-plume/pom.xml b/boms/tomee-plume/pom.xml
index f70e698..8d90935 100644
--- a/boms/tomee-plume/pom.xml
+++ b/boms/tomee-plume/pom.xml
@@ -1379,7 +1379,7 @@
</dependency>
<dependency>
<groupId>org.apache.tomee</groupId>
- <artifactId>openejb-javaagent.jar</artifactId>
+ <artifactId>openejb-javaagent</artifactId>
<version>${project.version}</version>
<exclusions>
<exclusion>
diff --git a/boms/tomee-plus/pom.xml b/boms/tomee-plus/pom.xml
index cdfa812..810d4ac 100644
--- a/boms/tomee-plus/pom.xml
+++ b/boms/tomee-plus/pom.xml
@@ -1423,7 +1423,7 @@
</dependency>
<dependency>
<groupId>org.apache.tomee</groupId>
- <artifactId>openejb-javaagent.jar</artifactId>
+ <artifactId>openejb-javaagent</artifactId>
<version>${project.version}</version>
<exclusions>
<exclusion>
diff --git a/boms/tomee-webprofile/pom.xml b/boms/tomee-webprofile/pom.xml
index abc6eed..d791ccc 100644
--- a/boms/tomee-webprofile/pom.xml
+++ b/boms/tomee-webprofile/pom.xml
@@ -972,7 +972,7 @@
</dependency>
<dependency>
<groupId>org.apache.tomee</groupId>
- <artifactId>openejb-javaagent.jar</artifactId>
+ <artifactId>openejb-javaagent</artifactId>
<version>${project.version}</version>
<exclusions>
<exclusion>
diff --git a/tomee/tomee-bootstrap/src/test/java/org/apache/tomee/bootstrap/GenerateBoms.java b/tomee/tomee-bootstrap/src/test/java/org/apache/tomee/bootstrap/GenerateBoms.java
index 8cd6216..dd45aec 100644
--- a/tomee/tomee-bootstrap/src/test/java/org/apache/tomee/bootstrap/GenerateBoms.java
+++ b/tomee/tomee-bootstrap/src/test/java/org/apache/tomee/bootstrap/GenerateBoms.java
@@ -27,8 +27,10 @@ import org.apache.openejb.util.Join;
import org.apache.openejb.util.Strings;
import org.junit.Test;
+import java.io.ByteArrayOutputStream;
import java.io.File;
import java.io.IOException;
+import java.io.PrintStream;
import java.io.UncheckedIOException;
import java.net.URL;
import java.util.ArrayList;
@@ -40,6 +42,22 @@ import java.util.function.Function;
import java.util.stream.Collectors;
import java.util.stream.Stream;
+/**
+ * The BOM files in the boms/tomee-microprofile/ and directories are
+ * generated by this class.
+ *
+ * The goal of each BOM is to be completely identical to the respective
+ * standalone server zip. Each library from the zip is translated back
+ * to its respective maven coordinate and placed in the pom with all
+ * transitive dependencies removed. Thus the pom is a 1-to-1 mapping
+ * of the server zip itself with zero variance possible due to any
+ * transitive Maven dependencies.
+ *
+ * Currently, the generation process is manual and should ideally be
+ * done prior to release.
+ *
+ * @see GenerateBoms#main(String[]) to execute this generator
+ */
public class GenerateBoms {
private final File project;
@@ -48,6 +66,14 @@ public class GenerateBoms {
private final Repository repository;
public GenerateBoms() {
+ /*
+ * Resolve all project paths relative to this built class
+ * that lives in `tomee/tomee-bootstrap/target/test-classes/`
+ *
+ * We walk backwards from that directory till we find the
+ * project root and then we can build all relative paths
+ * from there.
+ */
final File testClasses = JarLocation.jarLocation(GenerateBoms.class);
final File target = testClasses.getParentFile();
final File tomeeBootstrap = target.getParentFile();
@@ -71,20 +97,61 @@ public class GenerateBoms {
Files.dir(dists);
}
+ /**
+ * Use this main method from your IDE to regenerate the TomEE BOM files.
+ */
public static void main(String[] args) throws Exception {
new GenerateBoms().run();
}
- public void run() throws Exception {
+ /**
+ * Navigate to `tomee/apache-tomee/target/` and collect any apache-tomee*.zip files.
+ * Translate each into a Distribution instance that contains the complete list of
+ *
+ * @see GenerateBoms#asDistribution(File)
+ */
+ public void run() {
+ if (!dists.exists()) {
+ throw new IllegalStateException("Directory does not exist: " + dists.getAbsolutePath() + "\n" +
+ "Ensure the project has been built and the server zips exist prior to executing" +
+ " this generator.");
+ }
final List<Distribution> distributions = Stream.of(dists.listFiles())
.filter(file -> file.getName().endsWith(".zip"))
.filter(file -> file.getName().startsWith("apache-tomee-"))
.map(this::asDistribution)
.collect(Collectors.toList());
+ verify(distributions);
+
distributions.forEach(this::toBom);
}
+ /**
+ * If there are files inside a zip that we could not map
+ * back to an artifact in the local Maven repo, then the
+ * corresponding BOM will be incomplete and we must throw
+ * an error.
+ *
+ * People will not check warnings or log output of any kind
+ * so we must be obnixious with this.
+ */
+ private void verify(final List<Distribution> distributions) {
+ final List<Distribution> incomplete = distributions.stream()
+ .filter(distribution -> distribution.getMissing().size() > 0)
+ .collect(Collectors.toList());
+
+ throw new IncompleteMappingException(incomplete);
+ }
+
+ /**
+ * Overwrite (or create) the contents of the BOM files in:
+ *
+ * - $project.dir/boms/tomee-microprofile
+ * - $project.dir/boms/tomee-webprofile
+ * - $project.dir/boms/tomee-plume
+ * - $project.dir/boms/tomee-plus
+ */
private void toBom(final Distribution distribution) {
try {
final URL url = this.getClass().getClassLoader().getResource("pom-template.xml");
@@ -106,12 +173,40 @@ public class GenerateBoms {
}
}
+ /**
+ * Represents a particular apache-tomee-foo-1.2.3.zip
+ */
@Data
public static class Distribution {
+
+ /**
+ * The Maven coordinates for any jars found inside
+ * either tomee.home/lib/* or tomee.home/bin/*
+ */
private final List<Artifact> artifacts = new ArrayList<>();
+
+ /**
+ * The names of any files in tomee.home/lib/* or
+ * tomee.home/bin/* that could not be matched with
+ * something from the local Maven repository
+ */
private final List<File> missing = new ArrayList<>();
+
+ /**
+ * The corresponding apache-tomee-foo-1.2.3.zip
+ */
private final File zip;
+
+ /**
+ * The short name of the distribution. For example
+ * `tomee-webprofile` for apache-tomee-webprofile-1.2.3.zip
+ */
private final String name;
+
+ /**
+ * The display name of the distribution. For example
+ * `TomEE WebProfile` for apache-tomee-webprofile-1.2.3.zip
+ */
private final String displayName;
public Distribution(final File zip) {
@@ -139,15 +234,22 @@ public class GenerateBoms {
}
}
- private Distribution asDistribution(final File file) {
+ /**
+ * Extract the zip that represents a TomEE distribution. Find
+ * all jar files. Match them up with jars in the local Maven
+ * repository. Identify any jars we could not match. And finally,
+ * return all the data so we have a canonical representation of
+ * the distribution.
+ */
+ private Distribution asDistribution(final File zip) {
final File tmpdir = Files.tmpdir();
try {
- Zips.unzip(file, tmpdir);
+ Zips.unzip(zip, tmpdir);
} catch (IOException e) {
- throw new UncheckedIOException("Cannot unzip " + file.getAbsolutePath(), e);
+ throw new UncheckedIOException("Cannot unzip " + zip.getAbsolutePath(), e);
}
- final Distribution distribution = new Distribution(file);
+ final Distribution distribution = new Distribution(zip);
final List<File> jars = Files.collect(tmpdir, ".*.jar");
@@ -172,6 +274,16 @@ public class GenerateBoms {
return distribution;
}
+ /**
+ * This class represents the local Maven repository and is used to
+ * try and find the correct Maven coordinates for the jars inside
+ * the tomee/lib/ and tomee/bin/ directories.
+ *
+ * This does not attempt any online resolution to Maven Central itself
+ * as theoretically you just built all the TomEE dists so the jars that
+ * ended up in that dist where already downloaded and we just need to
+ * find them.
+ */
public static class Repository {
private final Map<String, File> artifacts = new HashMap<>();
private final File path;
@@ -185,6 +297,22 @@ public class GenerateBoms {
}
}
+ /**
+ * In several situations the jars inside the tomee/lib/*.jar or tomee/bin/*.jar
+ * are a little tricky to map back to something from Maven Central.
+ *
+ * The logic in this method handles all the edge cases.
+ *
+ * One of the most confusing is that nearly all `catalina-foo.jar` files do
+ * not contain any version, nor do they use the same artifact name that would
+ * exist in Maven Central. For Tomcat, all the `catalina-foo.jar` files tend
+ * to map to `tomcat-foo-1.2.3.jar` files in Maven Central.
+ *
+ * There is another known limitation that the Eclipse Compiler jar (ecj-4.12.jar)
+ * found in the Tomcat distribution is not available in Maven Central. The Tomcat
+ * build will download it directly from the Eclipse website. Very strangely, the
+ * Eclipse Compiler team does publish jars to Maven Central, but only for version 3.x
+ */
public Artifact from(final File jar) {
if (jar.getName().equals("commons-daemon.jar")) {
return new Artifact("commons-daemon", "commons-daemon", "1.1.0");
@@ -268,6 +396,10 @@ public class GenerateBoms {
return new Artifact("org.eclipse.jdt", "ecj", "3.22.0");
}
+ if (jar.getName().equals("openejb-javaagent.jar")) {
+ return new Artifact("org.apache.tomee", "openejb-javaagent", "${project.version}");
+ }
+
if (jar.getName().startsWith("openejb-")) {
final String artifact = jar.getName().replaceAll("-8.0.*", "");
return new Artifact("org.apache.tomee", artifact, "${project.version}");
@@ -314,9 +446,12 @@ public class GenerateBoms {
}
}
- @lombok.Builder(toBuilder = true)
+ /**
+ * A simple representation of a Maven Coordinate
+ */
@Getter
@ToString
+ @lombok.Builder(toBuilder = true)
public static class Artifact implements Comparable<Artifact> {
private final String groupId;
private final String artifactId;
@@ -329,6 +464,10 @@ public class GenerateBoms {
return a.compareTo(b);
}
+ /**
+ * Long term the dep in the BOM should not have a version
+ * and all such data would be in the parent pom.
+ */
public String asBomDep() {
final String g = groupId;
final String a = artifactId;
@@ -347,6 +486,11 @@ public class GenerateBoms {
" </dependency>\n";
}
+ /**
+ * Currently unused, but long term this will be the entry we'd need
+ * to add to the parent pom to ensure that the BOMs can just list
+ * the dependencies needed, but not duplicate the version information.
+ */
public String asManagedDep() {
final String g = groupId;
final String a = artifactId;
@@ -360,4 +504,36 @@ public class GenerateBoms {
}
}
+ /**
+ * Attempt to throw a detailed error message if we are unable to find the
+ * matching maven coordinates for a particular lib/*.jar
+ */
+ public static class IncompleteMappingException extends IllegalStateException {
+
+ private final List<Distribution> incomplete;
+
+ public IncompleteMappingException(final List<Distribution> incomplete) {
+ super(message(incomplete));
+ this.incomplete = incomplete;
+ }
+
+ public List<Distribution> getIncomplete() {
+ return incomplete;
+ }
+
+ private static String message(final List<Distribution> incomplete) {
+ final ByteArrayOutputStream bytes = new ByteArrayOutputStream();
+ final PrintStream out = new PrintStream(bytes);
+
+ out.println("Unable to find matching maven coordinates from the following distributions.");
+ for (Distribution distribution : incomplete) {
+ out.printf(" %s%n", distribution.getZip().getName());
+ for (File file : distribution.getMissing()) {
+ out.printf(" - %s%n", file.getName());
+ }
+ }
+ out.flush();
+ return new String(bytes.toByteArray());
+ }
+ }
}
diff --git a/tomee/tomee-bootstrap/src/test/resources/pom-template.xml b/tomee/tomee-bootstrap/src/test/resources/pom-template.xml
index 46965cb..f20e82e 100644
--- a/tomee/tomee-bootstrap/src/test/resources/pom-template.xml
+++ b/tomee/tomee-bootstrap/src/test/resources/pom-template.xml
@@ -18,6 +18,16 @@
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+ <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+ THIS FILE IS GENERATED, DO NOT MODIFY
+
+ This file is generated by inspecting the libraries in the server
+ distributions found in tomee/apache-tomee/target/apache-tomee-*.zip
+
+ Any improvements that might need to be made to this pom must go in
+ org.apache.tomee.bootstrap.GenerateBoms
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
+
<parent>
<groupId>org.apache.tomee.bom</groupId>
<artifactId>boms</artifactId>