Step 1: make ExtensionFinder support refreshing

core/src/main/java/hudson/ExtensionFinder.java

@@ -23,9 +23,9 @@
  */
 package hudson;
 
+import com.google.common.collect.Lists;
 import com.google.inject.AbstractModule;
 import com.google.inject.Binding;
-import com.google.inject.CreationException;
 import com.google.inject.Guice;
 import com.google.inject.Injector;
 import com.google.inject.Key;
@@ -38,6 +38,8 @@ import com.google.common.collect.ImmutableList;
 import hudson.init.InitMilestone;
 import hudson.model.Descriptor;
 import hudson.model.Hudson;
+import jenkins.ExtensionComponentSet;
+import jenkins.ExtensionRefreshException;
 import jenkins.model.Jenkins;
 import net.java.sezpoz.Index;
 import net.java.sezpoz.IndexItem;
@@ -82,6 +84,35 @@ public abstract class ExtensionFinder implements ExtensionPoint {
         return Collections.emptyList();
     }
 
+    /**
+     * Returns true if this extension finder supports the {@link #refresh()} operation.
+     */
+    public boolean isRefreshable() {
+        try {
+            return getClass().getMethod("refresh").getDeclaringClass()!=ExtensionFinder.class;
+        } catch (NoSuchMethodException e) {
+            return false;
+        }
+    }
+
+    /**
+     * Rebuilds the internal index, if any, so that future {@link #find(Class, Hudson)} calls
+     * will discover components newly added to {@link PluginManager#uberClassLoader}.
+     *
+     * <p>
+     * The point of the refresh operation is not to disrupt instances of already loaded {@link ExtensionComponent}s,
+     * and only instantiate those that are new. Otherwise this will break the singleton semantics of various
+     * objects, such as {@link Descriptor}s.
+     *
+     * <p>
+     * The behaviour is undefined if {@link #isRefreshable()} is returning false.
+     *
+     * @since 1.DynamicExtensionFinder.
+     * @see #isRefreshable()
+     * @return never null
+     */
+    public abstract ExtensionComponentSet refresh() throws ExtensionRefreshException;
+
     /**
      * Discover extensions of the given type.
      *
@@ -89,6 +120,11 @@ public abstract class ExtensionFinder implements ExtensionPoint {
      * This method is called only once per the given type after all the plugins are loaded,
      * so implementations need not worry about caching.
      *
+     * <p>
+     * This method should return all the known components at the time of the call, including
+     * those that are discovered later via {@link #refresh()}, even though those components
+     * are separately retruend in {@link ExtensionComponentSet}.
+     *
      * @param <T>
      *      The type of the extension points. This is not bound to {@link ExtensionPoint} because
      *      of {@link Descriptor}, which by itself doesn't implement {@link ExtensionPoint} for
@@ -164,15 +200,34 @@ public abstract class ExtensionFinder implements ExtensionPoint {
      * Discovers components via sezpoz but instantiates them by using Guice.
      */
     public static abstract class AbstractGuiceFinder<T extends Annotation> extends ExtensionFinder {
+        /**
+         * Injector that we find components from.
+         * <p>
+         * To support refresh when Guice doesn't let us alter the bindings, we'll create
+         * a child container to house newly discovered components. This field points to the
+         * youngest such container.
+         */
         private Injector container;
 
+        /**
+         * Sezpoz index we are currently using in {@link #container} (and its ancestors.)
+         * Needed to compute delta.
+         */
+        private List<IndexItem<T,Object>> sezpozIndex;
+
         private final Map<Key,T> annotations = new HashMap<Key,T>();
+        private final Sezpoz moduleFinder = new Sezpoz();
+        private final Class<T> annotationType;
 
         public AbstractGuiceFinder(final Class<T> annotationType) {
+            this.annotationType = annotationType;
+
+            sezpozIndex = ImmutableList.copyOf(Index.load(annotationType, Object.class, Jenkins.getInstance().getPluginManager().uberClassLoader));
+
             List<Module> modules = new ArrayList<Module>();
-            modules.add(new SezpozModule(annotationType,Jenkins.getInstance().getPluginManager().uberClassLoader));
+            modules.add(new SezpozModule(sezpozIndex));
 
-            for (ExtensionComponent<Module> ec : new Sezpoz().find(Module.class, Hudson.getInstance())) {
+            for (ExtensionComponent<Module> ec : moduleFinder.find(Module.class, Hudson.getInstance())) {
                 modules.add(ec.getInstance());
             }
 
@@ -182,7 +237,48 @@ public abstract class ExtensionFinder implements ExtensionPoint {
                 LOGGER.log(Level.SEVERE, "Failed to create Guice container from all the plugins",e);
                 // failing to load all bindings are disastrous, so recover by creating minimum that works
                 // by just including the core
-                container = Guice.createInjector(new SezpozModule(annotationType,Jenkins.class.getClassLoader()));
+                container = Guice.createInjector(new SezpozModule(
+                        ImmutableList.copyOf(Index.load(annotationType, Object.class, Jenkins.class.getClassLoader()))));
+            }
+        }
+
+        /**
+         * The basic idea is:
+         *
+         * <ul>
+         *     <li>List up delta as a series of modules
+         *     <li>
+         * </ul>
+         */
+        @Override
+        public synchronized ExtensionComponentSet refresh() throws ExtensionRefreshException {
+            // figure out newly discovered sezpoz components
+            List<IndexItem<T, Object>> delta = Sezpoz.listDelta(annotationType,sezpozIndex);
+            List<IndexItem<T, Object>> l = Lists.newArrayList(sezpozIndex);
+            l.addAll(delta);
+            sezpozIndex = l;
+
+            List<Module> modules = new ArrayList<Module>();
+            modules.add(new SezpozModule(delta));
+            for (ExtensionComponent<Module> ec : moduleFinder.refresh().find(Module.class)) {
+                modules.add(ec.getInstance());
+            }
+
+            try {
+                final Injector child = container.createChildInjector(modules);
+                container = child;
+
+                return new ExtensionComponentSet() {
+                    @Override
+                    public <T> Collection<ExtensionComponent<T>> find(Class<T> type) {
+                        List<ExtensionComponent<T>> result = new ArrayList<ExtensionComponent<T>>();
+                        _find(type, result, child);
+                        return result;
+                    }
+                };
+            } catch (Throwable e) {
+                LOGGER.log(Level.SEVERE, "Failed to create Guice container from newly added plugins",e);
+                throw new ExtensionRefreshException(e);
             }
         }
 
@@ -213,8 +309,15 @@ public abstract class ExtensionFinder implements ExtensionPoint {
         }
 
         public <U> Collection<ExtensionComponent<U>> find(Class<U> type, Hudson hudson) {
+            // the find method contract requires us to traverse all known components
             List<ExtensionComponent<U>> result = new ArrayList<ExtensionComponent<U>>();
+            for (Injector i=container; i!=null; i=i.getParent()) {
+                _find(type, result, i);
+            }
+            return result;
+        }
 
+        private <U> void _find(Class<U> type, List<ExtensionComponent<U>> result, Injector container) {
             for (Entry<Key<?>, Binding<?>> e : container.getBindings().entrySet()) {
                 if (type.isAssignableFrom(e.getKey().getTypeLiteral().getRawType())) {
                     T a = annotations.get(e.getKey());
@@ -223,8 +326,6 @@ public abstract class ExtensionFinder implements ExtensionPoint {
                         result.add(new ExtensionComponent<U>(type.cast(o),a!=null?getOrdinal(a):0));
                 }
             }
-
-            return result;
         }
 
         /**
@@ -261,13 +362,16 @@ public abstract class ExtensionFinder implements ExtensionPoint {
 
         private static final Logger LOGGER = Logger.getLogger(GuiceFinder.class.getName());
 
+        /**
+         * {@link Module} that finds components via sezpoz index.
+         * Instead of using SezPoz to instantiate, we'll instantiate them by using Guice,
+         * so that we can take advantage of dependency injection.
+         */
         private class SezpozModule extends AbstractModule {
-            private final Class<T> annotationType;
-            private final ClassLoader cl;
+            private final List<IndexItem<T,Object>> index;;
 
-            public SezpozModule(Class<T> annotationType, ClassLoader cl) {
-                this.annotationType = annotationType;
-                this.cl = cl;
+            public SezpozModule(List<IndexItem<T,Object>> index) {
+                this.index = index;
             }
 
             /**
@@ -302,7 +406,7 @@ public abstract class ExtensionFinder implements ExtensionPoint {
             protected void configure() {
                 int id=0;
 
-                for (final IndexItem<T,Object> item : Index.load(annotationType, Object.class, cl)) {
+                for (final IndexItem<T,Object> item : index) {
                     id++;
                     try {
                         AnnotatedElement e = item.element();
@@ -379,10 +483,54 @@ public abstract class ExtensionFinder implements ExtensionPoint {
             return indices;
         }
 
+        /**
+         * {@inheritDoc}
+         *
+         * <p>
+         * SezPoz implements value-equality of {@link IndexItem}, so
+         */
+        @Override
+        public synchronized ExtensionComponentSet refresh() {
+            final List<IndexItem<Extension,Object>> old = indices;
+            if (old==null)      return ExtensionComponentSet.EMPTY; // we haven't loaded anything
+
+            final List<IndexItem<Extension, Object>> delta = listDelta(Extension.class,old);
+
+            List<IndexItem<Extension,Object>> r = Lists.newArrayList(old);
+            r.addAll(delta);
+            indices = ImmutableList.copyOf(r);
+
+            return new ExtensionComponentSet() {
+                @Override
+                public <T> Collection<ExtensionComponent<T>> find(Class<T> type) {
+                    return _find(type,delta);
+                }
+            };
+        }
+
+        static <T extends Annotation> List<IndexItem<T, Object>> listDelta(Class<T> annotationType, List<IndexItem<T, Object>> old) {
+            // list up newly discovered components
+            final List<IndexItem<T,Object>> delta = Lists.newArrayList();
+            ClassLoader cl = Jenkins.getInstance().getPluginManager().uberClassLoader;
+            for (IndexItem<T,Object> ii : Index.load(annotationType, Object.class, cl)) {
+                if (!old.contains(ii)) {
+                    delta.add(ii);
+                }
+            }
+            return delta;
+        }
+
         public <T> Collection<ExtensionComponent<T>> find(Class<T> type, Hudson hudson) {
+            return _find(type,getIndices());
+        }
+
+        /**
+         * Finds all the matching {@link IndexItem}s that match the given type and instantiate them.
+         */
+        private <T> Collection<ExtensionComponent<T>> _find(Class<T> type, List<IndexItem<Extension,Object>> indices) {
             List<ExtensionComponent<T>> result = new ArrayList<ExtensionComponent<T>>();
 
-            for (IndexItem<Extension,Object> item : getIndices()) {
+            for (IndexItem<Extension,Object> item : indices) {
                 try {
                     AnnotatedElement e = item.element();
                     Class<?> extType;

core/src/main/java/hudson/cli/declarative/CLIRegisterer.java

@@ -30,6 +30,8 @@ import hudson.Util;
 import hudson.cli.CLICommand;
 import hudson.cli.CloneableCLICommand;
 import hudson.model.Hudson;
+import jenkins.ExtensionComponentSet;
+import jenkins.ExtensionRefreshException;
 import jenkins.model.Jenkins;
 import hudson.remoting.Channel;
 import hudson.security.CliAuthenticator;
@@ -64,6 +66,12 @@ import java.util.logging.Logger;
  */
 @Extension
 public class CLIRegisterer extends ExtensionFinder {
+    @Override
+    public ExtensionComponentSet refresh() throws ExtensionRefreshException {
+        // TODO: this is not complex. just bit tedious.
+        return ExtensionComponentSet.EMPTY;
+    }
+
     public <T> Collection<ExtensionComponent<T>> find(Class<T> type, Hudson hudson) {
         if (type==CLICommand.class)
             return (List)discover(hudson);

core/src/main/java/jenkins/ExtensionComponentSet.java

+/*
+ * The MIT License
+ *
+ * Copyright (c) 2011, CloudBees, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+package jenkins;
+
+import com.google.common.collect.Lists;
+import hudson.ExtensionComponent;
+import hudson.ExtensionFinder;
+import hudson.ExtensionPoint;
+import hudson.model.Descriptor;
+
+import java.util.Collection;
+import java.util.Collections;
+import java.util.List;
+
+/**
+ * Represents the components that's newly discovered during {@link ExtensionFinder#refresh()}.
+ *
+ * @author Kohsuke Kawaguchi
+ * @since 1.DynamicExtensionFinder.
+ */
+public abstract class ExtensionComponentSet {
+    /**
+     * Discover extensions of the given type.
+     *
+     * <p>
+     * This method is called only once per the given type after all the plugins are loaded,
+     * so implementations need not worry about caching.
+     *
+     * @param <T>
+     *      The type of the extension points. This is not bound to {@link ExtensionPoint} because
+     *      of {@link Descriptor}, which by itself doesn't implement {@link ExtensionPoint} for
+     *      a historical reason.
+     * @return
+     *      Can be empty but never null.
+     */
+    public abstract <T> Collection<ExtensionComponent<T>> find(Class<T> type);
+
+    /**
+     * Constant that has zero component in it.
+     */
+    public static final ExtensionComponentSet EMPTY = new ExtensionComponentSet() {
+        @Override
+        public <T> Collection<ExtensionComponent<T>> find(Class<T> type) {
+            return Collections.emptyList();
+        }
+    };
+
+    /**
+     * Computes the union of all the given delta.
+     */
+    public static ExtensionComponentSet union(final Collection<? extends ExtensionComponentSet> base) {
+        return new ExtensionComponentSet() {
+            @Override
+            public <T> Collection<ExtensionComponent<T>> find(Class<T> type) {
+                List<ExtensionComponent<T>> r = Lists.newArrayList();
+                for (ExtensionComponentSet d : base)
+                    r.addAll(d.find(type));
+                return r;
+            }
+        };
+    }
+}

core/src/main/java/jenkins/ExtensionRefreshException.java

+/*
+ * The MIT License
+ *
+ * Copyright (c) 2011, CloudBees, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+package jenkins;
+
+import hudson.ExtensionFinder;
+
+/**
+ * Signals that {@link ExtensionFinder#refresh()} had failed.
+ *
+ * @author Kohsuke Kawaguchi
+ */
+public class ExtensionRefreshException extends Exception {
+    public ExtensionRefreshException() {
+    }
+
+    public ExtensionRefreshException(String message) {
+        super(message);
+    }
+
+    public ExtensionRefreshException(String message, Throwable cause) {
+        super(message, cause);
+    }
+
+    public ExtensionRefreshException(Throwable cause) {
+        super(cause);
+    }
+}