Merge pull request #3 from mrsarm/rc2-improvements

Release 1.0.0

Author: mrsarm

README.md

@@ -9,6 +9,7 @@ Hosted on _(release candidate)_: https://plugins.gradle.org/plugin/com.github.mr
 
  - [Getting started](#getting-started)
  - [Startup options](#startup-options)
+ - [Spring Boot applications](#spring-boot-applications)
  - [Troubleshooting](#troubleshooting)
  - [System Requirements](#system-requirements)
  - [Build and Publish](#build-an-publish)
@@ -22,7 +23,7 @@ To use this plugin, add the following to your `build.gradle`:
 
 ```groovy
 plugins {
-  id "com.github.mrsarm.jshell.plugin" version "1.0.0-RC1"
+  id "com.github.mrsarm.jshell.plugin" version "1.0.0"
 }
 ```
 
@@ -36,7 +37,7 @@ buildscript {
     }
   }
   dependencies {
-    classpath "gradle.plugin.com.github.mrsarm:jshell-plugin:1.0.0-RC1"
+    classpath "gradle.plugin.com.github.mrsarm:jshell-plugin:1.0.0"
   }
 }
 
@@ -86,6 +87,109 @@ arguments, like:
 
     $ gradle --console plain jshell -Pjshell.startup=/path/to/run.jsh
 
+If you have a `startup.jsh` script at the root of the project
+but at some point you don't want to execute it nor any other
+startup script, just pass the `jshell.startup` property with an empty
+value: `gradle --console plain jshell -Pjshell.startup=`.
+
+Spring Boot applications
+------------------------
+
+The JShell plugin allows to startup a Spring Boot application
+within the console and access to the business object from there,
+but you will need to do some extra configurations, and add
+a dependency to the project to make easier to access
+to the Spring beans.
+
+1. Setup the plugin following the steps in the
+   [Getting started](#getting-started) section.
+
+2. Add the library [spring-ctx](https://github.com/mrsarm/spring-ctx)
+   to your dependencies as follows:
+
+   - Add the following dependency to your `dependencies` section:
+     
+     ```groovy
+     implementation 'com.github.mrsarm:spring-ctx:1.0.0'
+     ```
+
+   - At the end of the `repositories` section:
+
+     ```groovy
+     maven { url 'https://jitpack.io' }
+     ```
+
+3. Any Spring Boot application has a class annotated with
+   `@SpringBootApplication` that is the starting point of
+   the application, with a `public static void main(String[] args)`
+   method, you need to create a [startup.jsh](#startup-options) file
+   at the root of your project calling that method, eg:
+
+   ```java
+   com.my.package.MyApplication.main(new String).main(new String[]{})
+   ```
+
+   You can also add the imports of the business classes you are going
+   to play with, as many as you have, otherwise you can import them
+   once the JShell started:
+
+   ```java
+   import com.my.package.services.MyUserService
+   ```
+
+4. Done. You can start playing with your Spring application, you can
+   access to the bean objects once the JShell started as
+   following:
+
+   ```
+   ./gradlew --console plain jshell
+   
+     .   ____          _            __ _ _
+    /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
+   ( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
+    \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
+     '  |____| .__|_| |_|_| |_\__, | / / / /
+    =========|_|==============|___/=/_/_/_/
+    :: Spring Boot ::        (v2.2.4.RELEASE)
+   
+   14:43:28.320  INFO com.my.package.MyApplication             : Starting Application on kubu1910 with PID 5225 (/projects/...
+   14:43:28.323 DEBUG com.my.package.MyApplication             : Running with Spring Boot v2.2.4.RELEASE, Spring v5.2.3.RELEASE
+   14:43:28.324  INFO com.my.package.MyApplication             : The following profiles are active: ...
+   14:43:30.229  INFO boot.web.embedded.tomcat.TomcatWebServer : Tomcat initialized with port(s): 8010 (http)
+   
+   ...
+   ...
+   
+   14:43:33.729  INFO tuate.endpoint.web.EndpointLinksResolver : Exposing 3 endpoint(s) beneath base path ''
+   14:43:33.811  INFO boot.web.embedded.tomcat.TomcatWebServer : Tomcat started on port(s): 8010 (http) with context path ''
+   14:43:33.816  INFO com.my.package.MyApplication             : Started Application in 6.995 seconds (JVM running for 10.524)
+   
+   > Task :jshell
+   |  Welcome to JShell -- Version 11.0.6
+   |  For an introduction type: /help intro
+   
+   jshell> var myUserService = ctx.App.getBean(MyUserService.class)
+   
+   jshell> ctx.App.ppjson(myUserService.getByUsername("admin"))
+   {
+     "name" : "Jhon",
+     "lastName" : "Due",
+     "username" : "admin",
+     "age" : null
+   }
+   ```
+
+   You can add to the `startup.jsh` not just the call to the `main` method
+   and useful imports, but also adds the bean declarations you are
+   going to use most likely, eg.
+   `var myUserService = ctx.App.getBean(MyUserService.class)`, or any other
+   snippet of Java code that may save you time running each time the JShell.
+
+   The class `ctx.App` comes from the `spring-ctx` dependency added, checkout the
+   [documentation](https://github.com/mrsarm/spring-ctx/blob/master/README.md)
+   of all the useful methods it has to help you to play with
+   the Spring framework.
+
 
 Troubleshooting
 ---------------
@@ -104,7 +208,7 @@ Gradle command:
 
     $ gradle --console plain classes jshell
 
-### I have a JDK 9+ installation but my default JDK is the JDK 8 or below
+### I have a JDK 9+ installation, but my default JDK is the JDK 8 or below
 
 In that case Gradle will try to use the default JDK, and `jshell` is
 not available in Java 8 and above. Moreover the steps to change the
@@ -124,9 +228,9 @@ not have effect anymore.
 You can even create an alias in your `~/.profile` / `~/.bashrc`
 file like: `alias setjava9='export JAVA_HOME=/System/Library/Java/...'`
 to later switch easily to the other distribution calling
-`setjava9`.
+`setjava9`, or `setjava8` to switch back.
 
-### Gradle output is print with the jshell output in the console
+### Gradle output is mixed with the jshell output in the console
 
 If content like `<-------------> 0% EXECUTING [16s]` is mixed
 in the console with the jshell output each time you try
@@ -137,6 +241,13 @@ adding the option `--no-daemon` to start up the jshell:
 
     $ gradle --no-daemon --console plain jshell
 
+### Tab completion not working
+
+Auto-completion does not work, and pressing arrow keys triggers
+weird characters in the console. Unfortunately, with the
+current console support from Gradle, there is no
+solution for this [bug](https://github.com/mrsarm/jshell-plugin/issues/2).
+
 
 System Requirements
 -------------------
@@ -169,10 +280,10 @@ I forked it because the original project is not receiving patches
 and this version solves some issues and adds the following features:
 
  - It works with **multi-module projects**
- - There is no need to set the env variable `JAVA_OPTS` with a bunch of
+ - There is no need to set the env variable `JAVA_OPTS` with a bunch
    of arguments _"--add-exports jdk.jshell/jdk.intern..."_
  - It allows to run at the beginning of the session a _.jsh_ startup script
- - _Coming soon_: special support to the **Spring Framework**
+ - Special support to the **Spring Framework**
 
 Project: https://github.com/mrsarm/jshell-plugin
 

build.gradle

@@ -2,10 +2,11 @@ plugins {
     id 'com.gradle.plugin-publish' version '0.11.0'
     id 'maven-publish'
     id 'groovy'
+    id 'java-library'
 }
 
 group 'com.github.mrsarm'
-version '1.0.0-RC1'
+version '1.0.0'
 
 sourceCompatibility = 9
 targetCompatibility = 9

src/main/groovy/com/github/mrsarm/jshell/plugin/JShellPlugin.groovy

@@ -18,56 +18,79 @@ package com.github.mrsarm.jshell.plugin
 import jdk.jshell.tool.JavaShellToolBuilder
 import org.gradle.api.Plugin
 import org.gradle.api.Project
+import org.gradle.api.Task
 import org.gradle.api.tasks.JavaExec
 
 class JShellPlugin implements Plugin<Project> {
 
-    @Override
-    void apply(Project project) {
-        def jshellTask = project.tasks.create('jshell')
+    private String[] shellArgs
+
+    // This task could be merged with the main task in just one,
+    // the problem is that the main task is a JavaExec one,
+    // and at least for now I couldn't find a way
+    // to get the dependencies list with this type
+    private Task createJshellSetupTask(Project project) {
+        Task jshellTask = project.tasks.create('jshellSetup')
         def classesTask = project.tasks.find { it.name == "classes" }
         if (classesTask) {
             jshellTask.dependsOn classesTask
-        } else {
-            // Some multi-module projects may not have the :classes task
-            jshellTask.logger.warn ":jshell task :classes not found, be sure to compile the project first"
         }
         jshellTask.doLast {
+            if (!jshellTask.dependsOn) {
+                // Some multi-module projects may not have the :classes task
+                jshellTask.logger.warn ":jshell task :classes not found, be sure to compile the project first"
+            }
             Set pathSet = []
             project.tasks.withType(JavaExec) {
-                pathSet.addAll(classpath.findAll{ it.exists() })
+                pathSet.addAll(classpath.findAll { it.exists() })
             }
             project.subprojects.each {
                 it.tasks.withType(JavaExec) {
-                    pathSet.addAll(classpath.findAll{ it.exists() })
+                    pathSet.addAll(classpath.findAll { it.exists() })
                 }
             }
-            Thread.currentThread().setContextClassLoader(ClassLoader.getSystemClassLoader()) // promote class loader
             def path = pathSet.join(System.properties['os.name'].toLowerCase().contains('windows') ? ';' : ':')
             jshellTask.logger.info(":jshell executing with --class-path \"{}\"", path)
-            String[] args = [
+            shellArgs = [
                 "--class-path", path,
                 "--startup", "DEFAULT",
                 "--startup", "PRINTING"
             ]
-            if (project.findProperty("jshell.startup")) {
+            if (project.findProperty("jshell.startup") == "") {
+                // Nothing, just avoid to run the startup.jsh if exists
+            }
+            else if (project.findProperty("jshell.startup")) {
                 def jshellStartup = project.findProperty("jshell.startup")
                 jshellTask.logger.info(":jshell executing with --startup DEFAULT --startup PRINTING " +
                                        "--startup \"{}\"", jshellStartup)
-                args = args + (String[]) ["--startup", jshellStartup]
-            } else {
+                shellArgs = shellArgs + (String[]) ["--startup", jshellStartup]
+            }
+            else {
                 def startupJsh = new File("${project.projectDir}/startup.jsh")
                 if (startupJsh.exists()) {
                     def startupJshPath = startupJsh.absolutePath
                     jshellTask.logger.info(":jshell executing with --startup DEFAULT --startup PRINTING" +
                                            " --startup \"{}\"", startupJshPath)
-                    args = args + (String[]) ["--startup", startupJshPath]
+                    shellArgs = shellArgs + (String[]) ["--startup", startupJshPath]
                 } else {
                     jshellTask.logger.info(":jshell did not find a startup.jsh script at the project dir " +
                                            "nor a `jshell.startup` configuration")
                 }
             }
-            JavaShellToolBuilder.builder().run(args)
+        }
+        return jshellTask
+    }
+
+    @Override
+    void apply(Project project) {
+        Task jshellSetupTask = createJshellSetupTask(project)
+        Task jshellTask = project.tasks.create('jshell')
+        jshellTask.group = 'application'
+        jshellTask.description = 'Runs a JShell session with all the code and dependencies.'
+        jshellTask.dependsOn jshellSetupTask
+        jshellTask.doLast {
+            Thread.currentThread().setContextClassLoader(ClassLoader.getSystemClassLoader()) // promote class loader
+            JavaShellToolBuilder.builder().run(shellArgs)
         }
     }
 }