You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by re...@apache.org on 2022/11/03 15:35:25 UTC
[tomcat-jakartaee-migration] branch main updated: Updates for javadoc 18+
This is an automated email from the ASF dual-hosted git repository.
remm pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/tomcat-jakartaee-migration.git
The following commit(s) were added to refs/heads/main by this push:
new 32474b4 Updates for javadoc 18+
32474b4 is described below
commit 32474b4a967ccac41f0933d64ab78ef5c6e2a1b6
Author: remm <re...@apache.org>
AuthorDate: Thu Nov 3 16:35:12 2022 +0100
Updates for javadoc 18+
This is particularly annoying, especially the "warning: use of default
constructor, which does not provide a comment" which means adding the
default constructor just to comment on it (!!). This cannot be disabled
except by filtering out a lot more.
I don't think it is realistic to do this for Tomcat.
---
.../apache/tomcat/jakartaee/ClassConverter.java | 25 +++++++++++++
.../org/apache/tomcat/jakartaee/Converter.java | 8 ++++
.../org/apache/tomcat/jakartaee/EESpecProfile.java | 20 ++++++++++
.../apache/tomcat/jakartaee/EESpecProfiles.java | 9 +++++
.../org/apache/tomcat/jakartaee/GlobMatcher.java | 7 ++++
.../java/org/apache/tomcat/jakartaee/Info.java | 7 ++++
.../apache/tomcat/jakartaee/ManifestConverter.java | 5 +++
.../org/apache/tomcat/jakartaee/Migration.java | 43 +++++++++++++++++++++-
.../org/apache/tomcat/jakartaee/MigrationCLI.java | 13 +++++++
.../org/apache/tomcat/jakartaee/MigrationTask.java | 21 +++++++++++
.../tomcat/jakartaee/PassThroughConverter.java | 8 ++++
.../org/apache/tomcat/jakartaee/TextConverter.java | 7 ++++
.../java/org/apache/tomcat/jakartaee/Util.java | 16 ++++++++
13 files changed, 188 insertions(+), 1 deletion(-)
diff --git a/src/main/java/org/apache/tomcat/jakartaee/ClassConverter.java b/src/main/java/org/apache/tomcat/jakartaee/ClassConverter.java
index e07814f..47fae3c 100644
--- a/src/main/java/org/apache/tomcat/jakartaee/ClassConverter.java
+++ b/src/main/java/org/apache/tomcat/jakartaee/ClassConverter.java
@@ -33,15 +33,30 @@ import org.apache.bcel.classfile.ConstantUtf8;
import org.apache.bcel.classfile.JavaClass;
import org.apache.commons.io.IOUtils;
+/**
+ * Class converter and transformer.
+ */
public class ClassConverter implements Converter, ClassFileTransformer {
private static final Logger logger = Logger.getLogger(ClassConverter.class.getCanonicalName());
private static final StringManager sm = StringManager.getManager(ClassConverter.class);
+ /**
+ * The configured spec profile.
+ */
protected final EESpecProfile profile;
+
+ /**
+ * Create a class converter with the default TOMCAT profile.
+ */
public ClassConverter() {
this(EESpecProfiles.TOMCAT);
}
+
+ /**
+ * Create a class converter with the specified spec profile.
+ * @param profile the specification profile to use for conversion
+ */
public ClassConverter(EESpecProfile profile) {
this.profile = profile;
}
@@ -79,6 +94,16 @@ public class ClassConverter implements Converter, ClassFileTransformer {
}
+ /**
+ * Convert specified class bytecode.
+ * @param path the path
+ * @param src the source byte stream
+ * @param dest the output byte stream
+ * @param profile the specification profile to use
+ * @param loader the class loader
+ * @return true if conversion occurred
+ * @throws IOException rethrow on byte read or write
+ */
protected boolean convertInternal(String path, InputStream src, OutputStream dest, EESpecProfile profile, ClassLoader loader)
throws IOException {
byte[] classBytes = IOUtils.toByteArray(src);
diff --git a/src/main/java/org/apache/tomcat/jakartaee/Converter.java b/src/main/java/org/apache/tomcat/jakartaee/Converter.java
index 1bba1a1..c96ae09 100644
--- a/src/main/java/org/apache/tomcat/jakartaee/Converter.java
+++ b/src/main/java/org/apache/tomcat/jakartaee/Converter.java
@@ -20,8 +20,16 @@ import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
+/**
+ * The main Converter interface, used for package prefix conversion.
+ */
public interface Converter {
+ /**
+ * Check if the file can be processed by this converter.
+ * @param filename the file name
+ * @return true if the converter will process this file
+ */
boolean accepts(String filename);
/**
diff --git a/src/main/java/org/apache/tomcat/jakartaee/EESpecProfile.java b/src/main/java/org/apache/tomcat/jakartaee/EESpecProfile.java
index 321e8cb..34ba3a2 100644
--- a/src/main/java/org/apache/tomcat/jakartaee/EESpecProfile.java
+++ b/src/main/java/org/apache/tomcat/jakartaee/EESpecProfile.java
@@ -20,16 +20,36 @@ package org.apache.tomcat.jakartaee;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
+/**
+ * Used to represent a specification profile.
+ */
public interface EESpecProfile {
+ /**
+ * Convert the specified name to the target namespace.
+ * @param name the name to convert
+ * @return the converted name
+ */
default String convert(String name) {
Matcher m = getPattern().matcher(name);
return m.replaceAll(getTarget() + "$1");
}
+ /**
+ * The source namespace.
+ * @return the source namespace
+ */
String getSource();
+ /**
+ * The target namespace.
+ * @return the target namespace
+ */
String getTarget();
+ /**
+ * The pattern used for conversion.
+ * @return the pattern
+ */
Pattern getPattern();
}
diff --git a/src/main/java/org/apache/tomcat/jakartaee/EESpecProfiles.java b/src/main/java/org/apache/tomcat/jakartaee/EESpecProfiles.java
index 881cd01..ff8c3a3 100644
--- a/src/main/java/org/apache/tomcat/jakartaee/EESpecProfiles.java
+++ b/src/main/java/org/apache/tomcat/jakartaee/EESpecProfiles.java
@@ -25,6 +25,9 @@ import java.util.regex.Pattern;
*/
public enum EESpecProfiles implements EESpecProfile {
+ /**
+ * Specification profile matching the packages provided with Tomcat.
+ */
TOMCAT("javax", "jakarta",
"javax([/\\.](annotation[/\\.](" + Patterns.ANNOTATION_CLASSES + ")" +
"|ejb" +
@@ -36,8 +39,14 @@ public enum EESpecProfiles implements EESpecProfile {
"|transaction(?![/\\.]xa)" +
"|websocket))"),
+ /**
+ * Specification profile for the full EE.
+ */
EE("javax", "jakarta", "javax" + Patterns.EE),
+ /**
+ * Specification profile for the full EE, to convert from Jakarta to EE 8.
+ */
JEE8("jakarta", "javax", "jakarta" + Patterns.EE);
private static final class Patterns {
diff --git a/src/main/java/org/apache/tomcat/jakartaee/GlobMatcher.java b/src/main/java/org/apache/tomcat/jakartaee/GlobMatcher.java
index 87bff59..5f25a34 100644
--- a/src/main/java/org/apache/tomcat/jakartaee/GlobMatcher.java
+++ b/src/main/java/org/apache/tomcat/jakartaee/GlobMatcher.java
@@ -29,6 +29,13 @@ import java.util.Set;
*/
public final class GlobMatcher {
+
+ /**
+ * Construct the matcher.
+ */
+ public GlobMatcher() {}
+
+
/**
* Tests whether or not a given file name matches any file name pattern in
* the given set. The match is performed case-sensitively.
diff --git a/src/main/java/org/apache/tomcat/jakartaee/Info.java b/src/main/java/org/apache/tomcat/jakartaee/Info.java
index a8de1a0..83c22dc 100644
--- a/src/main/java/org/apache/tomcat/jakartaee/Info.java
+++ b/src/main/java/org/apache/tomcat/jakartaee/Info.java
@@ -19,6 +19,9 @@ package org.apache.tomcat.jakartaee;
import java.io.IOException;
import java.util.Properties;
+/**
+ * Manifest version decorator.
+ */
public class Info {
private static final String VERSION;
@@ -43,6 +46,10 @@ public class Info {
}
}
+ /**
+ * Get the configured version.
+ * @return the version
+ */
public static String getVersion() {
return VERSION;
}
diff --git a/src/main/java/org/apache/tomcat/jakartaee/ManifestConverter.java b/src/main/java/org/apache/tomcat/jakartaee/ManifestConverter.java
index ab3a2b3..d07435f 100644
--- a/src/main/java/org/apache/tomcat/jakartaee/ManifestConverter.java
+++ b/src/main/java/org/apache/tomcat/jakartaee/ManifestConverter.java
@@ -40,6 +40,11 @@ public class ManifestConverter implements Converter {
private static final Logger logger = Logger.getLogger(ManifestConverter.class.getCanonicalName());
private static final StringManager sm = StringManager.getManager(ManifestConverter.class);
+ /**
+ * Manifest converter constructor.
+ */
+ public ManifestConverter() {}
+
@Override
public boolean accepts(String filename) {
if (filename.equals(JarFile.MANIFEST_NAME) || filename.endsWith("/" + JarFile.MANIFEST_NAME)) {
diff --git a/src/main/java/org/apache/tomcat/jakartaee/Migration.java b/src/main/java/org/apache/tomcat/jakartaee/Migration.java
index da6d757..4f11e66 100644
--- a/src/main/java/org/apache/tomcat/jakartaee/Migration.java
+++ b/src/main/java/org/apache/tomcat/jakartaee/Migration.java
@@ -45,6 +45,9 @@ import org.apache.commons.io.IOUtils;
import org.apache.commons.io.input.CloseShieldInputStream;
import org.apache.commons.io.output.CloseShieldOutputStream;
+/**
+ * The main class for the Migration tool.
+ */
public class Migration {
private static final Logger logger = Logger.getLogger(Migration.class.getCanonicalName());
@@ -99,6 +102,9 @@ public class Migration {
private final List<Converter> converters;
private final Set<String> excludes = new HashSet<>();
+ /**
+ * Construct a new migration tool instance.
+ */
public Migration() {
// Initialise the converters
converters = new ArrayList<>();
@@ -111,9 +117,21 @@ public class Migration {
converters.add(new PassThroughConverter());
}
+ /**
+ * The tool state.
+ */
public enum State {
+ /**
+ * Migration not started yet.
+ */
NOT_STARTED,
+ /**
+ * Migration in progress.
+ */
RUNNING,
+ /**
+ * Migration complete.
+ */
COMPLETE
}
@@ -135,18 +153,34 @@ public class Migration {
return profile;
}
+ /**
+ * Enable the default exclusion list for the tool.
+ * @param enableDefaultExcludes true to enable the default
+ */
public void setEnableDefaultExcludes(boolean enableDefaultExcludes) {
this.enableDefaultExcludes = enableDefaultExcludes;
}
+ /**
+ * Buffer all conversion operations for compressed archives in memory.
+ * @param zipInMemory true to buffer in memory
+ */
public void setZipInMemory(boolean zipInMemory) {
this.zipInMemory = zipInMemory;
}
+ /**
+ * Add specified resource exclusion.
+ * @param exclude the exclude to add
+ */
public void addExclude(String exclude) {
this.excludes.add(exclude);
}
+ /**
+ * Set source file.
+ * @param source the source file
+ */
public void setSource(File source) {
if (!source.canRead()) {
throw new IllegalArgumentException(sm.getString("migration.cannotReadSource",
@@ -155,7 +189,10 @@ public class Migration {
this.source = source;
}
-
+ /**
+ * Set destination file.
+ * @param destination the destination file
+ */
public void setDestination(File destination) {
this.destination = destination;
}
@@ -175,6 +212,10 @@ public class Migration {
}
+ /**
+ * Execute migration operation.
+ * @throws IOException when an exception occurs
+ */
public void execute() throws IOException {
if (state == State.RUNNING) {
throw new IllegalStateException(sm.getString("migration.alreadyRunning"));
diff --git a/src/main/java/org/apache/tomcat/jakartaee/MigrationCLI.java b/src/main/java/org/apache/tomcat/jakartaee/MigrationCLI.java
index 05c50cb..6c12a09 100644
--- a/src/main/java/org/apache/tomcat/jakartaee/MigrationCLI.java
+++ b/src/main/java/org/apache/tomcat/jakartaee/MigrationCLI.java
@@ -26,6 +26,9 @@ import java.util.Locale;
import java.util.logging.Level;
import java.util.logging.Logger;
+/**
+ * Command line interface wrapper for the migration tool.
+ */
public class MigrationCLI {
private static final StringManager sm = StringManager.getManager(MigrationCLI.class);
@@ -35,6 +38,16 @@ public class MigrationCLI {
private static final String PROFILE_ARG = "-profile=";
private static final String ZIPINMEMORY_ARG = "-zipInMemory";
+ /**
+ * Build the migration tool CLI instance.
+ */
+ public MigrationCLI() {}
+
+ /**
+ * Main method for the CLI tool.
+ * @param args the command line arguments
+ * @throws IOException when an exception occurs
+ */
public static void main(String[] args) throws IOException {
// Defaults
diff --git a/src/main/java/org/apache/tomcat/jakartaee/MigrationTask.java b/src/main/java/org/apache/tomcat/jakartaee/MigrationTask.java
index f5fd264..24a9b1f 100644
--- a/src/main/java/org/apache/tomcat/jakartaee/MigrationTask.java
+++ b/src/main/java/org/apache/tomcat/jakartaee/MigrationTask.java
@@ -29,24 +29,45 @@ import org.apache.tools.ant.Task;
*/
public class MigrationTask extends Task {
+ /**
+ * Default constructor.
+ */
+ public MigrationTask() {}
+
private File src;
private File dest;
private String profile = EESpecProfiles.TOMCAT.toString();
private boolean zipInMemory = false;
private String excludes;
+ /**
+ * Set the source file.
+ * @param src the source file
+ */
public void setSrc(File src) {
this.src = src;
}
+ /**
+ * Set the destination file.
+ * @param dest the destination file
+ */
public void setDest(File dest) {
this.dest = dest;
}
+ /**
+ * Set the profile that should be used.
+ * @param profile the profile to be used
+ */
public void setProfile(String profile) {
this.profile = profile;
}
+ /**
+ * Set the option to handle compressed archive entries in memory.
+ * @param zipInMemory true to buffer in memory
+ */
public void setZipInMemory(boolean zipInMemory) {
this.zipInMemory = zipInMemory;
}
diff --git a/src/main/java/org/apache/tomcat/jakartaee/PassThroughConverter.java b/src/main/java/org/apache/tomcat/jakartaee/PassThroughConverter.java
index 1d6a48c..8205e5c 100644
--- a/src/main/java/org/apache/tomcat/jakartaee/PassThroughConverter.java
+++ b/src/main/java/org/apache/tomcat/jakartaee/PassThroughConverter.java
@@ -22,11 +22,19 @@ import java.io.OutputStream;
import java.util.logging.Level;
import java.util.logging.Logger;
+/**
+ * No conversion.
+ */
public class PassThroughConverter implements Converter {
private static final Logger logger = Logger.getLogger(PassThroughConverter.class.getCanonicalName());
private static final StringManager sm = StringManager.getManager(PassThroughConverter.class);
+ /**
+ * Default constructor.
+ */
+ public PassThroughConverter() {}
+
@Override
public boolean accepts(String filename) {
// Accepts everything
diff --git a/src/main/java/org/apache/tomcat/jakartaee/TextConverter.java b/src/main/java/org/apache/tomcat/jakartaee/TextConverter.java
index 3c91117..fd3833b 100644
--- a/src/main/java/org/apache/tomcat/jakartaee/TextConverter.java
+++ b/src/main/java/org/apache/tomcat/jakartaee/TextConverter.java
@@ -26,6 +26,9 @@ import java.util.List;
import java.util.logging.Level;
import java.util.logging.Logger;
+/**
+ * Converter for text resources.
+ */
public class TextConverter implements Converter {
private static final Logger logger = Logger.getLogger(TextConverter.class.getCanonicalName());
@@ -48,6 +51,10 @@ public class TextConverter implements Converter {
supportedExtensions.add("groovy");
}
+ /**
+ * Default constructor.
+ */
+ public TextConverter() {}
@Override
public boolean accepts(String filename) {
diff --git a/src/main/java/org/apache/tomcat/jakartaee/Util.java b/src/main/java/org/apache/tomcat/jakartaee/Util.java
index 1fbca92..790e454 100644
--- a/src/main/java/org/apache/tomcat/jakartaee/Util.java
+++ b/src/main/java/org/apache/tomcat/jakartaee/Util.java
@@ -23,6 +23,9 @@ import java.io.OutputStream;
import java.nio.charset.Charset;
import java.util.Locale;
+/**
+ * Utility methods.
+ */
public class Util {
/**
@@ -41,6 +44,12 @@ public class Util {
return filename.substring(lastPeriod + 1).toLowerCase(Locale.ENGLISH);
}
+ /**
+ * Buffered copy.
+ * @param is the input
+ * @param os the output
+ * @throws IOException if an exception occurs
+ */
public static void copy(InputStream is, OutputStream os) throws IOException {
byte[] buf = new byte[8192];
int numRead;
@@ -49,6 +58,13 @@ public class Util {
}
}
+ /**
+ * Convert the input bytes as a string.
+ * @param is the input byte stream
+ * @param charset the charset to use
+ * @return the converted string
+ * @throws IOException if an exception occurs
+ */
public static String toString(InputStream is, Charset charset) throws IOException {
ByteArrayOutputStream baos = new ByteArrayOutputStream();
Util.copy(is, baos);
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org