feature: create a hello channel extension point

closes #3

Signed-off-by: Jorge Aguilera <[email protected]>

Author: jorgeaguileraseqera

README.md

@@ -3,6 +3,9 @@
 This project shows how to implement a simple Nextflow plugin named `nf-hello` that intercepts 
 workflow execution events to print a message when the execution starts and on workflow completion.
 
+Also, this plugin enriches the `channel` with a `producer` a `consumer` methods (`sayHello` and `goodbye`)
+allowing to include them into the script 
+
 ## Plugin assets 
                     
 - `settings.gradle`
@@ -38,6 +41,18 @@ workflow execution events to print a message when the execution starts and on wo
 
     The plugin unit tests. 
 
+## ExtensionPointS
+
+ExtensionPoint is the basic interface who use nextflow-core to integrate plugins into it.
+It's only a basic interface and serves as starting point for more specialized extensions. 
+
+Among others, nextflow-core integrate following sub ExtensionPointS:
+
+- `TraceObserverFactory` to provide a list of TraceObserverS 
+- `ChannelExtensionPoint` to enrich the channel with custom methods
+
+In this plugin you can find examples for both of them
+
 ## Compile & run unit tests 
 
 Run the following command in the project root directory (ie. where the file `settings.gradle` is located):

plugins/nf-hello/src/main/nextflow/hello/HelloExtension.groovy

@@ -23,23 +23,57 @@ import java.util.concurrent.CompletableFuture
 @Scoped('hello')
 class HelloExtension extends ChannelExtensionPoint{
 
+    /*
+     * A session hold information about current execution of the script
+     */
     private Session session
 
+    /*
+     * nf-core initializes the plugin once loaded and session is ready
+     * @param session
+     */
     @Override
     protected void init(Session session) {
         this.session = session
     }
 
-    DataflowWriteChannel sayHello() {
-        createHelloChannel()
+    /*
+     * reverse is a `producer` method and will be available to the script because:
+     *
+     * - it's public
+     * - it returns a DataflowWriteChannel
+     *
+     * nf-core will inspect the extension class and allow the script to call all these kind of methods
+     *
+     * the method can require arguments but it's not mandatory, it depends of the business logic of the method
+     *
+     * business logic can write into the channel once ready and values will be consumed from it
+     */
+    DataflowWriteChannel reverse(String message) {
+        createReverseChannel(message)
     }
 
     static String goodbyeMessage
 
+    /*
+    * goodbye is a `consumer` method as it receives values from a channel to perform some logic.
+    *
+    * Consumer methods are introspected by nextflow-core and include into the DSL if the method:
+    *
+    * - it's public
+    * - it returns a DataflowWriteChannel
+    * - it has only one arguments of DataflowReadChannel class
+    *
+    * a consumer method needs to proporcionate 2 closures:
+    * - a closure to consume items (one by one)
+    * - a finalizer closure
+    *
+    * in this case `goodbye` will consume a message and will store it as an upper case
+    */
     DataflowWriteChannel goodbye(DataflowReadChannel source) {
         final target = CH.createBy(source)
         final next = {
-            goodbyeMessage = "$it"
+            goodbyeMessage = "$it".toString().toUpperCase()
             target.bind(it)
         }
         final done = {
@@ -49,26 +83,33 @@ class HelloExtension extends ChannelExtensionPoint{
         target
     }
 
-    protected DataflowWriteChannel createHelloChannel(){
+    protected DataflowWriteChannel createReverseChannel(final String message){
         final channel = CH.create()
         if( NF.isDsl2() ){
             session.addIgniter { ->
-                sayHelloImpl(channel)
+                businessLogicHere(channel, message)
             }
         }else{
-            sayHelloImpl(channel)
+            businessLogicHere(channel, message)
         }
         channel
     }
 
-    protected sayHelloImpl(final DataflowWriteChannel channel){
+    /*
+    * businessLogicHere will send, across the channel, the message reversed
+    * and after will send an STOP signal to let know the channel it has been finished
+    */
+    protected static businessLogicHere(final DataflowWriteChannel channel, final String message){
         def future = CompletableFuture.runAsync({
-            channel.bind("Hi")
+            channel.bind(message.reverse())
             channel.bind(Channel.STOP)
         })
         future.exceptionally(this.&handlerException)
     }
 
+    /*
+    * an util class to trace exceptions
+    */
     static private void handlerException(Throwable e) {
         final error = e.cause ?: e
         log.error(error.message, error)

plugins/nf-hello/src/resources/META-INF/MANIFEST.MF

@@ -1,6 +1,6 @@
 Manifest-Version: 1.0
 Plugin-Id: nf-hello
-Plugin-Version: 0.1.0
+Plugin-Version: 0.2.0
 Plugin-Class: nextflow.hello.HelloPlugin
 Plugin-Provider: nextflow
-Plugin-Requires: >=21.04.0
+Plugin-Requires: >=22.04.0

plugins/nf-hello/src/test/nextflow/hello/ChannelExtensionHelloTest.groovy

@@ -22,14 +22,14 @@ class ChannelExtensionHelloTest extends Specification{
         def helloExtension = new HelloExtension(); helloExtension.init(session)
 
         when:
-        def result = helloExtension.sayHello()
+        def result = helloExtension.reverse("Hi")
 
         then:
-        result.val == 'Hi'
+        result.val == 'iH'
         result.val == Channel.STOP
     }
 
-    def "should receive a hi from hello"(){
+    def "should consume a message from script"(){
 
         given:
         def session = Mock(Session)
@@ -48,6 +48,6 @@ class ChannelExtensionHelloTest extends Specification{
         then:
         result.val == 'Goodbye folks'
         result.val == Channel.STOP
-        helloExtension.goodbyeMessage == 'Goodbye folks'
+        helloExtension.goodbyeMessage == 'Goodbye folks'.toUpperCase()
     }
 }

plugins/nf-hello/src/test/nextflow/hello/HelloDslTest.groovy

@@ -4,12 +4,14 @@ import nextflow.Channel
 import nextflow.extension.ChannelExtensionDelegate
 import nextflow.plugin.Plugins
 import spock.lang.Specification
+import spock.lang.Timeout
 
 
 /**
  * @author : jorge <[email protected]>
  *
  */
+@Timeout(10)
 class HelloDslTest extends Specification{
 
     def setup () {
@@ -19,12 +21,12 @@ class HelloDslTest extends Specification{
     def 'should perform a hi and create a channel' () {
         when:
         def SCRIPT = '''
-            channel.hello.sayHello() 
+            channel.hello.reverse('hi!') 
             '''
         and:
         def result = new MockScriptRunner([:]).setScript(SCRIPT).execute()
         then:
-        result.val == 'Hi'
+        result.val == '!ih'
         result.val == Channel.STOP
     }
 
@@ -42,6 +44,6 @@ class HelloDslTest extends Specification{
         result.val == Channel.STOP
 
         and:
-        HelloExtension.goodbyeMessage == 'Bye bye folks'
+        HelloExtension.goodbyeMessage == 'Bye bye folks'.toUpperCase()
     }
 }