rework the demo application

[pinhead84]

Both demo plugins are currently build as JAR files in the same way. To make it easier for new users and to better document the features of PF4J it might make sense, if one of the plugins is created as ZIP file (including a 3rd party library in the lib folder).

Because I'm always using ZIP plugins in my project and already have a working Maven configuration for this, I would provide a pull request, that changes the build process of the 2nd demo plugin in order to create a ZIP archive.

This would make it easier for new users to use one of the demo plugins as an example for their own project. We also might point from the packaging page of the documentation to both example plugins.

Let me know, what you think about this and if I can provide a pull request for this.

[pinhead84]

In the last few days I was playing around with the demo application. After looking a bit deeper into it, I feel, that we should consider to rework / simplify the demo application a little bit. In its current state the demo application might look quite confusing for new developers, who are interested in using PF4J.

Therefore I'm proposing the following improvements / modifications:

• It is not necessary anymore (since PF4J 0.9?) to use a plugin for the application itself (demo-app). For the sake of simplicity we should not use a plugin here anymore and put the demo-app library into the classpath instead.
• It is also not strictly necessary to provide a separate demo-api library. For the sake of simplicity its classes can be part of demo-app.
• The pf4j-demo-plugins parent project also makes the demo unnecessarily complex from my point of view. Both plugins could simply be put under the pf4j-demo root folder.
• As stated in my previous message, I would propose to create one of the demo plugins as ZIP archive and the other demo plugin as JAR archive.
• Finally I would suggest to create a separate distribution artifact within the pf4j-demo folder (similar to this approach). This artifact automatically assembles the application directory during the package phase. It copies plugins, dependencies and startup scripts into the application directory, from which the demo application can be executed.

These changes aim to provide a better starting point for new PF4J developers. They can simply copy the demo application and already have a solid base for their first experiments, which later can easily be migrated into their own application.

Finally one question comes to my mind regarding PF4J 3: Should we migrate the demo application to Java 11 with modules or should we stick with the "old school" approach? - I don't have a final opinion about this yet. But I think, that modules are the future, we should follow the latest developments of the Java platform and we should not invite new developers to adapt old / outdated techniques. But of course we could also provide separate demo applications for Java 8 and Java 11 with modules.

Please let me know, what you think about all this.

[decebals]

I feel, that we should consider to rework / simplify the demo application a little bit.

This is a very nice goal.

It is not necessary anymore (since PF4J 0.9?) to use a plugin for the application itself (demo-app). For the sake of simplicity we should not use a plugin here anymore and put the demo-app library into the classpath instead.

I don't understand very clear. The demo-app module contains only two extensions HowdyGreeting and WhazzupGreeting) and the Boot class (it loads, starts plugins. and display all extensions of Greeting extension point.

It is also not strictly necessary to provide a separate demo-api library. For the sake of simplicity its classes can be part of demo-app.

The demo-api module contains the Greeting extension point. This library must be included as dependency (with scope compile) in each plugin that supplies an extension for the Greeting extension point. If you move this extension point in app module you must add app as dependency in each plugin. In my mind, each application comes with a public API, supplied as separate jar(s) that can be used in each plugin that supplies extensions for extensions points defined in the app's API.

The pf4j-demo-plugins parent project also makes the demo unnecessarily complex from my point of view. Both plugins could simply be put under the pf4j-demo root folder.

The actual approach offer us multiple benefits:

• I can run my application with all plugins, from my IDE (IntelliJ in my case), without any modification, as a basic HelloWord application, if I will specify the runtime mode development (see Why "plugin.properties" is required? #209 (comment))
• I can push many Maven's settings of my plugins, from the plugin's pom.xml in the parent pom. In this mode, the plugin's pom is very clean, it will contains only the list with dependencies (see here)

These changes aim to provide a better starting point for new PF4J developers. They can simply copy the demo application and already have a solid base for their first experiments, which later can easily be migrated into their own application.

This is actually the purpose of the demo application. The first step is to create a project that contains demo application, verify that everything is OK (you can compile and run the application) and after this you can try to make modifications according to you goal/business. An idea is to extract demo module in
a separate pf4j-demo project on GitHub. In this case the user only clone the project and he has a good and solid start.

As stated in my previous message, I would propose to create one of the demo plugins as ZIP archive and the other demo plugin as JAR archive.

It's an idea but I don't know if this approach doesn't confuse the people. Normally, your application will contain only one plugin type format (JAR or ZIP). In this context is more easy to push most of Maven's settings of each plugin in the parent pom of plugins (see my discussion above, about this subject).

Finally one question comes to my mind regarding PF4J 3: Should we migrate the demo application to Java 11 with modules or should we stick with the "old school" approach? - I don't have a final opinion about this yet.

I think that the "old school" approach is OK (at least for the first phase).

[pinhead84]

Maybe I'm still a bit confused about the demo application. I think, that other developers, who want to discover the features PF4J, might feel the same. ;)

It is not necessary anymore (since PF4J 0.9?) to use a plugin for the application itself (demo-app). For the sake of simplicity we should not use a plugin here anymore and put the demo-app library into the classpath instead.

I don't understand very clear.

When running mvn clean install in the demo/app folder, a ZIP file is created in the target folder with the following contents:

 % unzip -l pf4j-demo-app-3.0.0-SNAPSHOT.zip 
Archive:  pf4j-demo-app-3.0.0-SNAPSHOT.zip
  Length      Date    Time    Name
---------  ---------- -----   ----
     7172  2019-03-26 00:14   pf4j-demo-app-3.0.0-SNAPSHOT.jar
        0  2019-03-26 00:14   lib/
   110971  2019-03-26 00:14   lib/pf4j-3.0.0-SNAPSHOT.jar
    41203  2017-04-01 07:50   lib/slf4j-api-1.7.25.jar
    46843  2018-12-03 17:40   lib/java-semver-0.9.0.jar
     2546  2019-03-26 00:14   lib/pf4j-demo-api-3.0.0-SNAPSHOT.jar
   481535  2013-07-28 02:00   lib/log4j-1.2.16.jar
    12244  2017-04-01 07:50   lib/slf4j-log4j12-1.7.25.jar
   261809  2013-07-28 02:00   lib/commons-lang-2.4.jar
---------                     -------
   964323                     9 files

I assumed this is a plugin file. But now I realize, that this is some sort of application bundle. Sorry, this was my mistake. :)

---

The demo-api module contains the Greeting extension point. This library must be included as dependency (with scope compile) in each plugin that supplies an extension for the Greeting extension point. If you move this extension point in app module you must add app as dependency in each plugin. In my mind, each application comes with a public API, supplied as separate jar(s) that can be used in each plugin that supplies extensions for extensions points defined in the app's API.

I understand your idea behind the pf4j-demo-api library. But I think it's not strictly necessary for an example / demo application. For the sake of simplicity, I would remove this library and make every plugin depend on the pf4j-demo-app instead. Otherwise a new user might think, that this approach is strictly necessary - but actually it's just a specific design pattern.

---

The pf4j-demo-plugins parent project also makes the demo unnecessarily complex from my point of view. Both plugins could simply be put under the pf4j-demo root folder.

I can run my application with all plugins from my IDE (IntelliJ in my case), without any modification, as a basic HelloWord application, if I will specify the runtime mode development (see #209 (comment))

That's interesting indeed. I wasn't aware of this DevelopmentPluginClasspath feature. I personally don't go this way and use another approach in my IDE, but now I understand your intentions. ;)

I can push many Maven's settings of my plugins, from the plugin's pom.xml in the parent pom. In this mode, the plugin's pom is very clean, it will contains only the list with dependencies (see here)

You might also put these default plugin settings in the root pom.xml. But assuming we want to keep the pf4j-demo-plugins of course it makes sense, to put these properties over there.

---

As stated in my previous message, I would propose to create one of the demo plugins as ZIP archive and the other demo plugin as JAR archive.

It's an idea but I don't know if this approach doesn't confuse the people. Normally, your application will contain only one plugin type format (JAR or ZIP).

You are somewhat inconsistent here. On one hand you only like to create JAR plugins and on the other hand you are using two different extension providers in the pf4j-demo-app library. ;)

---

These changes aim to provide a better starting point for new PF4J developers.

This is actually the purpose of the demo application.

Before making any changes, I guess we should answer the question: What is the main purpose of the demo application?

• Is it about an easy starting point for new developers? - For this use case the discussed Archetype might be a better / alternative solution (see provide an Archetype for new PF4J based projects #306). In this case it makes sense, to only use one specific default behavior.
• Or do we want to give examples about how to use the different features of PF4J (as an addition to the documentation website)?

From my point of view: Assuming we're going to provide an Archetype in the future, I think the demo application should be considered as an addition to the documentation. Therefore it should implement (and comment) different concepts (ZIP / JAR plugins, service extensions / legacy extensions, etc).

---

Finally one question comes to my mind regarding PF4J 3: Should we migrate the demo application to Java 11 with modules or should we stick with the "old school" approach?

I think that the "old school" approach is OK (at least for the first phase).

I was asking, because I've migrated the demo application to Java 11 on my local system for the purpose of testing PF4J with the Java Module System. But I agree, that it might not be necessary for the demo application.

But maybe it might not be that much of a deal to provide separate Archetypes for Java 8 and Java 9+.