[JENKINS-66563] add a supported API for a plugin to insert jars into its classpath (#5711)

* Revive support for `URLClassLoader`

* [JENKINS-66563] add a supported API for a plugin to insert jars into its classpath

Required for BouncyCastle plugin so it does not try and expose its
classes when running in a JVM in FIPS mode, but can be other use cases
as yet unknown.

* [JENKINS-66563] add test case for new functionality

* [JENKINS-66563] and @since javadoc

* [JENKINS-66563] correct indent for new test

* mark the API Beta and document do not do this

Feedback from Jesse was we should be clearer that you probably should
not be using this interface and that there are other approaches that
should be used first.
To that end add some extra Javadoc and mark the API as Beta

* [JENKINS-66563] fix javadoc errors

* Fix typo

Co-authored-by: Devin Nusbaum <dwnusbaum@users.noreply.github.com>

Co-authored-by: Basil Crow <me@basilcrow.com>
Co-authored-by: Tim Jacomb <timjacomb1+github@gmail.com>
Co-authored-by: Tim Jacomb <21194782+timja@users.noreply.github.com>
Co-authored-by: Devin Nusbaum <dwnusbaum@users.noreply.github.com>
This commit is contained in:
authored and GitHub committed 2021-09-16 08:09:46 +01:00
1 parent 1c3880c342
commit ca0508eaa9
2 files changed
+104 -3

No files matched your search

+56 -1
View File
@@ -36,10 +36,13 @@ import io.jenkins.lib.versionnumber.JavaSpecificationVersion;
import jenkins.YesNoMaybe;
import jenkins.model.Jenkins;
import jenkins.security.UpdateSiteWarningsMonitor;
import jenkins.util.AntClassLoader;
import jenkins.util.URLClassLoader2;
import jenkins.util.java.JavaUtils;
import org.apache.commons.lang.StringUtils;
import org.apache.commons.logging.LogFactory;
import org.kohsuke.accmod.Restricted;
import org.kohsuke.accmod.restrictions.Beta;
import org.kohsuke.accmod.restrictions.DoNotUse;
import org.kohsuke.accmod.restrictions.NoExternalUse;
import org.kohsuke.stapler.HttpResponse;
@@ -57,6 +60,7 @@ import java.io.File;
import java.io.IOException;
import java.io.OutputStream;
import java.net.URL;
import java.net.URLClassLoader;
import java.nio.file.Files;
import java.nio.file.InvalidPathException;
import java.util.ArrayList;
@@ -110,6 +114,7 @@ import static org.apache.commons.io.FilenameUtils.getBaseName;
*/
@ExportedBean
public class PluginWrapper implements Comparable<PluginWrapper>, ModelObject {
/**
* A plugin won't be loaded unless his declared dependencies are present and match the required minimal version.
* This can be set to false to disable the version check (legacy behaviour)
@@ -377,6 +382,56 @@ public class PluginWrapper implements Comparable<PluginWrapper>, ModelObject {
return !getDeprecations().isEmpty();
}
/**
* Inject the specified jar file(s) to the plugins classpath.
* <p><strong>Warning:</strong> This is advanced usage that you should not be needed in 99.9% of all cases, any jar insertion
* should happen early into the plugins lifecycle to prevent classloading issues in dependent plugins.
* </p><p>
* Rather than use this functionality it is to have co-operative behaviour between any consumer of the libraries and load the classes in a separate {@link ClassLoader}.
* you can expose third-party libraries from a dynamic location in various ways, such as:
*
* <ul>
* <li>You could split your plugin into two modules:
* <ul>
* <li>regular Jenkins plugin code, plus some interface encapsulating access to the lib via a minimal, simplified
* API
* <li>an implementation of that interface which compiles against a provided static reference copy of the library,
* and which is packaged in your plugin as a resource (not in WEB-INF/lib/*.jar)
* </ul>
* <li>with coordination:
* <ul>
* <li>dynamically find some JAR(s) on the controller (or perhaps even agent)
* <li>find the bridge JAR in your plugin’s resources area
* <li>create some {@link URLClassLoader} loading them both, parented to the plugin {@link ClassLoader}
* <li>use reflection to load &amp; instantiate the class of the bridge implementation, casting to the interface from
* the plugin
* </ul>
* </ul>
* For a concrete example see the <a href=
* "https://github.com/jenkinsci/database-plugin/blob/117.va2009e38b882/src/main/java/org/jenkinsci/plugins/database/GenericDatabase.java#L129-L142">database
* plugin</a>. *
*
* @throws Exception if the File could not be inserted into the classpath for some reason.
* @since TODO
*/
@Restricted(Beta.class)
public void injectJarsToClasspath(File... jars) throws Exception {
if (classLoader instanceof AntClassLoader) {
for (File f : jars) {
LOGGER.log(Level.CONFIG, () -> "Inserting " + f + " into " + shortName + " plugin's classpath");
((AntClassLoader) classLoader).addPathComponent(f);
}
} else if (classLoader instanceof URLClassLoader2) {
for (File f : jars) {
LOGGER.log(Level.CONFIG, () -> "Inserting " + f + " into " + shortName + " plugin's classpath");
((URLClassLoader2) classLoader).addURL(f.toURI().toURL());
}
} else {
throw new AssertionError("PluginWrapper classloader has changed type, but this code has not been updated accordingly");
}
}
@ExportedBean
public static final class Dependency {
@Exported
@@ -640,7 +695,7 @@ public class PluginWrapper implements Comparable<PluginWrapper>, ModelObject {
* Generally coming from the {@code java.level} extracted as MANIFEST's metadata with
* <a href="https://github.com/jenkinsci/plugin-pom/pull/134">this addition on the plugins' parent pom</a>.
*
* @see <a href="https://github.com/jenkinsci/maven-hpi-plugin/pull/75">maven-hpi-plugin#PR-75</a>.
* @see <a href="https://github.com/jenkinsci/maven-hpi-plugin/pull/75">maven-hpi-plugin#PR-75</a>
*
* @since 2.158
*/