Merge branch 'main' into feat-classpath-extension-loading

# Conflicts:
#	jjava-kernel/src/main/java/org/dflib/jjava/kernel/JavaKernel.java

Author: m-dzianishchyts

RELEASE-NOTES.md

@@ -12,7 +12,9 @@
 - #82 Refactoring: Move JavaKernel init logic from constructor to Builder
 - #83 Simplify Kernel metadata loading approach
 - #84 Refactoring: reorg Maven modules for reusability
-
+- #86 ineffecient / incorrect classpath handling
+- #89 Deprecate redundant magics: %jars, %addMavenDependency
+- #90 Deprecate Ivy artifact syntax for %maven magic
 
 ## 1.0-a5
 

jjava-distro/src/main/java/org/dflib/jjava/distro/Env.java

@@ -1,14 +1,12 @@
 package org.dflib.jjava.distro;
 
-import org.dflib.jjava.jupyter.kernel.util.GlobFinder;
+import org.dflib.jjava.jupyter.kernel.util.PathsHandler;
 
-import java.io.File;
 import java.io.IOException;
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.util.ArrayList;
 import java.util.List;
-import java.util.regex.Pattern;
 
 /**
  * Defines environment variables supported by the kernel.
@@ -29,8 +27,6 @@ final class Env {
     // not used by JJava, but rather by the kernel launcher script
     public static final String JJAVA_JVM_OPTS = "JJAVA_JVM_OPTS";
 
-    private static final Pattern PATH_SPLITTER = Pattern.compile(File.pathSeparator, Pattern.LITERAL);
-
     public static String timeout() {
         return System.getenv(Env.JJAVA_TIMEOUT);
     }
@@ -52,9 +48,8 @@ public static List<String> compilerOpts() {
         return optsString != null ? Opts.splitOpts(optsString) : java.util.List.of();
     }
 
-    public static List<String> extraClasspath() {
-        String cpString = System.getenv(Env.JJAVA_CLASSPATH);
-        return cpString != null ? java.util.List.of(PATH_SPLITTER.split(cpString)) : java.util.List.of();
+    public static String extraClasspath() {
+        return System.getenv(Env.JJAVA_CLASSPATH);
     }
 
     public static List<String> startupSnippets() {
@@ -74,22 +69,12 @@ public static List<String> startupSnippets() {
     }
 
     private static void appendSnippestFromScriptPaths(List<String> startupScripts, String scriptPaths) {
-        for (String glob : PATH_SPLITTER.split(scriptPaths)) {
-            Iterable<Path> globScriptPaths;
-
-            try {
-                globScriptPaths = new GlobFinder(glob).computeMatchingPaths();
-            } catch (IOException e) {
-                throw new RuntimeException(java.lang.String.format("Error while computing startup scripts for '%s': %s", glob, e.getMessage()), e);
-            }
-
-            for (Path path : globScriptPaths) {
-                if (Files.isRegularFile(path) && Files.isReadable(path)) {
-                    try {
-                        startupScripts.add(Files.readString(path));
-                    } catch (IOException e) {
-                        throw new RuntimeException(java.lang.String.format("Error while loading startup script for '%s': %s", path, e.getMessage()), e);
-                    }
+        for (Path path : PathsHandler.splitAndResolveGlobs(scriptPaths)) {
+            if (Files.isRegularFile(path) && Files.isReadable(path)) {
+                try {
+                    startupScripts.add(Files.readString(path));
+                } catch (IOException e) {
+                    throw new RuntimeException(java.lang.String.format("Error while loading startup script for '%s': %s", path, e.getMessage()), e);
                 }
             }
         }

jjava-distro/src/main/java/org/dflib/jjava/distro/JJava.java

@@ -8,6 +8,7 @@
 import org.dflib.jjava.kernel.magics.JarsMagic;
 import org.dflib.jjava.kernel.magics.LoadCodeMagic;
 import org.dfllib.jjava.maven.MavenDependencyResolver;
+import org.dfllib.jjava.maven.magics.AddMavenDependencyMagic;
 import org.dfllib.jjava.maven.magics.LoadFromPomCellMagic;
 import org.dfllib.jjava.maven.magics.LoadFromPomLineMagic;
 import org.dfllib.jjava.maven.magics.MavenMagic;
@@ -62,8 +63,11 @@ public static void main(String[] args) throws Exception {
                 .lineMagic("maven", new MavenMagic(mavenResolver))
                 .lineMagic("mavenRepo", new MavenRepoMagic(mavenResolver))
                 .lineMagic("loadFromPOM", new LoadFromPomLineMagic(mavenResolver))
-                .lineMagic("jars", new JarsMagic()) // TODO: deprecate redundant "jars" alias; "classpath" is a superset of this
-                .lineMagic("addMavenDependency", new MavenMagic(mavenResolver)) // TODO: deprecate redundant "addMavenDependency" alias
+
+                // temporarily support a few deprecated magics
+                .lineMagic("jars", new JarsMagic())
+                .lineMagic("addMavenDependency", new AddMavenDependencyMagic(mavenResolver))
+
                 .cellMagic("loadFromPOM", new LoadFromPomCellMagic(mavenResolver))
 
                 .build();

jjava-distro/src/test/java/org/dflib/jjava/distro/KernelMagicIT.java

@@ -10,6 +10,7 @@
 
 public class KernelMagicIT extends ContainerizedKernelCase {
 
+    @Deprecated
     @Test
     public void jars() throws Exception {
         String jar = CONTAINER_RESOURCES + "/jakarta.annotation-api-3.0.0.jar";
@@ -45,7 +46,7 @@ public void classpath() throws Exception {
     }
 
     @Test
-    public void addMavenDependency() throws Exception {
+    public void maven() throws Exception {
         String snippet = String.join("\n",
                 "%maven org.dflib:dflib-jupyter:1.0.0-RC1",
                 "System.getProperty(\"java.class.path\")"
@@ -56,8 +57,9 @@ public void addMavenDependency() throws Exception {
         assertThat(snippetResult.getStdout(), containsString("dflib-jupyter-1.0.0-RC1.jar"));
     }
 
+    @Deprecated
     @Test
-    public void addIvyDependency() throws Exception {
+    public void mavenIvySyntax() throws Exception {
         String snippet = String.join("\n",
                 "%maven jakarta.annotation#jakarta.annotation-api;3.0.0",
                 "System.getProperty(\"java.class.path\")"

jjava-jupyter/src/main/java/org/dflib/jjava/jupyter/ExtensionLoader.java

@@ -1,6 +1,7 @@
 package org.dflib.jjava.jupyter;
 
 import org.dflib.jjava.jupyter.kernel.BaseKernel;
+import org.dflib.jjava.jupyter.kernel.util.PathsHandler;
 
 import java.io.IOException;
 import java.net.MalformedURLException;
@@ -12,7 +13,6 @@
 import java.util.ServiceLoader;
 import java.util.Set;
 import java.util.stream.Collectors;
-import java.util.stream.StreamSupport;
 
 /**
  * This class is responsible for discovering and initializing a set of {@link Extension} instances.
@@ -35,24 +35,28 @@ public ExtensionLoader() {
     }
 
     /**
-     * Loads available {@code Extension} implementations and initializes them. Calls should manually invoke
-     * {@link Extension#install(BaseKernel)} to initialize extension. This method performs discovery of extension
-     * classes based on a {@link ServiceLoader} API, using the kernel default ClassLoader
+     * Locates and loads {@code Extension} implementations. Extension classes discovery is performed with
+     * {@link ServiceLoader}, using the kernel's default ClassLoader. Callers should manually invoke
+     * {@link Extension#install(BaseKernel)} to initialize each extension.
+     *
+     * @return a list of the discovered extensions
      */
-    public List<Extension> loadFromClasspath() {
+    public List<Extension> loadFromDefaultClasspath() {
         return load(getClass().getClassLoader());
     }
 
     /**
-     * Loads available {@code Extension} implementations and initializes them. Calls should manually invoke
-     * {@link Extension#install(BaseKernel)} to initialize extension. This method performs discovery of extension
-     * classes based on a {@link ServiceLoader} API, but only scanning the specified jars, not the entire classpath.
+     * Locates and loads {@code Extension} implementations. Extension classes discovery is performed with
+     * {@link ServiceLoader}, only scanning the locations present in the classpath argument, not the entire classpath.
+     * Callers should invoke {@link Extension#install(BaseKernel)} to initialize each extension.
      *
-     * @param jarPaths paths to jar files to scan for extensions
-     * @return list of the available extensions
+     * @param classpath one or more filesystem paths separated by {@link java.io.File#pathSeparator}.
+     * @return a list of the discovered extensions
      */
-    public List<Extension> loadFromJars(Iterable<String> jarPaths) {
-        URL[] urls = StreamSupport.stream(jarPaths.spliterator(), false)
+    public List<Extension> loadFromClasspath(String classpath) {
+
+        URL[] urls = PathsHandler.split(classpath)
+                .stream()
                 .map(ExtensionLoader::toURL)
                 .toArray(URL[]::new);
 

jjava-jupyter/src/main/java/org/dflib/jjava/jupyter/kernel/BaseKernelBuilder.java

@@ -14,8 +14,6 @@
 
 import java.nio.charset.Charset;
 import java.nio.charset.StandardCharsets;
-import java.util.LinkedHashMap;
-import java.util.Map;
 
 /**
  * A common builder superclass for BaseKernel subclasses.
@@ -31,12 +29,10 @@ public abstract class BaseKernelBuilder<
     protected MagicTranspiler magicTranspiler;
     protected HistoryManager historyManager;
     protected Boolean extensionsEnabled;
-    protected final Map<String, LineMagic<?, ?>> lineMagics;
-    protected final Map<String, CellMagic<?, ?>> cellMagics;
+    protected final MagicsRegistry magicsRegistry;
 
     protected BaseKernelBuilder() {
-        this.cellMagics = new LinkedHashMap<>();
-        this.lineMagics = new LinkedHashMap<>();
+        this.magicsRegistry = new MagicsRegistry();
     }
 
     public B name(String name) {
@@ -60,12 +56,12 @@ public B historyManager(HistoryManager historyManager) {
     }
 
     public B lineMagic(String name, LineMagic<?, ?> magic) {
-        lineMagics.put(name, magic);
+        magicsRegistry.registerLineMagic(name, magic);
         return (B) this;
     }
 
     public B cellMagic(String name, CellMagic<?, ?> magic) {
-        cellMagics.put(name, magic);
+        magicsRegistry.registerCellMagic(name, magic);
         return (B) this;
     }
 
@@ -119,7 +115,7 @@ protected boolean buildExtensionsEnabled() {
     }
 
     protected MagicsRegistry buildMagicsRegistry() {
-        return new MagicsRegistry(lineMagics, cellMagics);
+        return magicsRegistry;
     }
 
     protected MagicTranspiler buildMagicTranspiler() {

jjava-jupyter/src/main/java/org/dflib/jjava/jupyter/kernel/comm/Comm.java

@@ -16,11 +16,7 @@ public abstract class Comm {
 
     private boolean closed = false;
 
-    public Comm(CommManager manager, String id, String targetName) {
-        this(manager, id, targetName, null);
-    }
-
-    public Comm(CommManager manager, String id, String targetName, JsonElement initializationData) {
+    protected Comm(CommManager manager, String id, String targetName) {
         this.manager = manager;
         this.id = id;
         this.targetName = targetName;
@@ -47,7 +43,7 @@ public void send(JsonObject data, Map<String, Object> metadata, List<byte[]> blo
     }
 
     /**
-     * A callback for when the kernel receives a message who's destination is
+     * A callback for when the kernel receives a message whose destination is
      * this comm. This handler gets access to the entire message so that if desired
      * the comms may make use of the low level blob segments or want to make use of
      * the parent, identities, etc.

jjava-jupyter/src/main/java/org/dflib/jjava/jupyter/kernel/comm/CommFactory.java

@@ -8,13 +8,14 @@ public interface CommFactory<T extends Comm> {
 
     /**
      * Create a new {@link Comm} and optionally attach data to the open message before it is sent.
-     * @param manager the {@link CommManager} that will be responsible for transporting messages
-     *                to and from the created {@link Comm}.
-     * @param id the id of the new {@link Comm}
-     * @param target the name of the target on the front-end to communicate with
+     *
+     * @param manager           the {@link CommManager} that will be responsible for transporting messages
+     *                          to and from the created {@link Comm}.
+     * @param id                the id of the new {@link Comm}
+     * @param target            the name of the target on the front-end to communicate with
      * @param openMessageToSend the message that will be sent after creating the comm. There are 2 places to attach
      *                          additional data to the send
      * @return a new comm. If data must be immediately sent it should be appended to the {@code openMessageToSend}.
      */
-    public T produce(CommManager manager, String id, String target, Message<CommOpenCommand> openMessageToSend);
+    T produce(CommManager manager, String id, String target, Message<CommOpenCommand> openMessageToSend);
 }

jjava-jupyter/src/main/java/org/dflib/jjava/jupyter/kernel/comm/CommManager.java

@@ -59,7 +59,7 @@ public Comm getCommByID(String id) {
 
     /**
      * Register a new comm that this manager should forward messages to in the event that
-     * it receives one addressed to a comm with the the {@code comm}'s id.
+     * it receives one addressed to a comm with the {@code comm}'s id.
      *
      * @param comm the comm to register with this handler
      */
@@ -195,7 +195,7 @@ public CommTarget getTarget(String targetName) {
     }
 
     // Default comm message handlers. These shouldn't need to be overridden but are more like
-    // lambda targets that capture this comm manager in it's scope.
+    // lambda targets that capture this comm manager in its scope.
 
     public void handleCommOpenCommand(ReplyEnvironment env, Message<CommOpenCommand> commOpenCommandMessage) {
         CommOpenCommand openCommand = commOpenCommandMessage.getContent();

jjava-jupyter/src/main/java/org/dflib/jjava/jupyter/kernel/comm/CommTarget.java

@@ -5,11 +5,12 @@
 
 @FunctionalInterface
 public interface CommTarget {
+
     /**
      * Create a new comm as a result of the frontend making a {@code comm_open} request. This
      * is designed to be a constructor reference to a class that extends {@link Comm} overriding
      * the {@link Comm#onMessage(Message)}.
-     *
+     * <p>
      * For example a plain no-op handler may be {@code CommTarget noop = Comm::new;}. Which would create
      * comms that do nothing when the receive a message.
      *
@@ -20,8 +21,7 @@ public interface CommTarget {
      * @param msg         the entire message that the manager received commanding it to open the comm. This may
      *                    carry additional data in the messages content. Specifically the {@link
      *                    CommOpenCommand#getData() data field}.
-     *
      * @return the newly created comm
      */
-    public Comm createComm(CommManager commManager, String id, String targetName, Message<CommOpenCommand> msg);
+    Comm createComm(CommManager commManager, String id, String targetName, Message<CommOpenCommand> msg);
 }