Feature/jspwiki 1198 plugin api change, discovery and in browser auto complete snippets

ChangeLog.md

@@ -16,6 +16,12 @@ KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.
 -->
+**2025-11-16 Alex O'Ree (alexoree AT apache DOT org)**
+
+* _3.0.0-git-09_
+
+* [JSPWIKI-1198](https://issues.apache.org/jira/browse/JSPWIKI-1198) - Plugin API change that enables all plugins to be internationalized and visible in the auto complete suggestion/snippet menu
+
 
 **2025-11-16 Alex O'Ree (alexoree AT apache DOT org)**
 

jspwiki-api/src/main/java/org/apache/wiki/api/Release.java

@@ -69,7 +69,7 @@ public final class Release {
      *  <p>
      *  If the build identifier is empty, it is not added.
      */
-    public static final String     BUILD         = "08";
+    public static final String     BUILD         = "09";
 
     /**
      *  This is the generic version string you should use when printing out the version.  It is of

jspwiki-api/src/main/java/org/apache/wiki/api/plugin/Plugin.java

@@ -18,6 +18,7 @@ Licensed to the Apache Software Foundation (ASF) under one
  */
 package org.apache.wiki.api.plugin;
 
+import java.util.Locale;
 import org.apache.wiki.api.core.Context;
 import org.apache.wiki.api.exceptions.PluginException;
 
@@ -48,5 +49,34 @@ public interface Plugin {
      *  @throws PluginException In case anything goes wrong.
      */
     String execute( Context context, Map< String, String > params ) throws PluginException;
+
+    /**
+     * Provides the ability for a plugin to provide a suggestion or template
+     * for execution within a wiki page. Default returns just the FQCN of the 
+     * plugin, which should enable it to fire off, however no parameters are 
+     * provided in this case. Override it to provide example inputs to aid users
+     * with configuring your plugin.
+     * 
+     * Example: com.company.Plugin inputParamter='test'
+     * 
+     * @since 3.0.0
+     * @return String
+     */
+    default String getSnipExample() {
+        return this.getClass().getCanonicalName();
+    }
+    /**
+     * Provides the ability for a plugin to provide it's display name that 
+     * is visible via the [{}] autocomplete/suggestion mechanism within the 
+     * editor.Example: Calls My Custom plugin 
+     * 
+     *
+     * @param locale 
+     * @since 3.0.0
+     * @return String
+     */
+    default String getDisplayName(Locale locale) {
+        return this.getClass().getSimpleName();
+    }
 
 }

jspwiki-it-tests/jspwiki-test-plugin/pom.xml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent> <!-- tests reuse [1/3]: reads common configuration for ITs and brings jspwiki-war as dependency -->
+        <groupId>org.apache.jspwiki.it</groupId>
+        <artifactId>jspwiki-it-tests</artifactId>
+        <version>3.0.0-SNAPSHOT</version>
+    </parent>
+    <artifactId>jspwiki-test-plugin</artifactId>
+    <packaging>jar</packaging>
+    <dependencies>
+        <dependency>
+            <groupId>org.apache.jspwiki</groupId>
+            <artifactId>jspwiki-main</artifactId>
+            <version>${project.version}</version>
+        </dependency>
+    </dependencies>
+</project>

jspwiki-it-tests/jspwiki-test-plugin/readme.txt

@@ -0,0 +1,22 @@
+This test plugin was created for testing the newer (v3.0.0) API
+changes that provide plugin discovery and the ability to get 
+an example available in the UI.
+
+In case that's not clear, after installing this plugin, then 
+starting the server and editing a page, ctrl+space will show 
+a snippet (refered to as a "snip" in the code) that provides
+a usage example in the browser. This helps to eliminate guess
+work and provides a better user experience.
+
+To deploy this plugin:
+	mvn clean install
+Then 
+	copy target\*.jar $JSPWIKI_HOME
+Where $JSPWIKI_HOME is something like
+	tomcat/webapps/jspwiki/WEB-INF/lib
+Then start up the tomcat server/container that you're running.
+
+That should be it. Enjoy.
+
+Remember this is just a test plugin, meaning it's only to 
+demonstrate the proof of concept. It really doesn't do much.

jspwiki-it-tests/jspwiki-test-plugin/src/main/java/org/apache/jspwiki/jspwiki/test/plugin/JspwikiTestPlugin.java

@@ -0,0 +1,36 @@
+/*
+ * Copyright 2025 The Apache Software Foundation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.jspwiki.jspwiki.test.plugin;
+
+import java.util.Map;
+import org.apache.wiki.api.core.Context;
+import org.apache.wiki.api.exceptions.PluginException;
+import org.apache.wiki.api.plugin.Plugin;
+
+/**
+ * a simple hello world test plugin
+ *
+ */
+public class JspwikiTestPlugin implements Plugin {
+
+    public JspwikiTestPlugin() {
+    }
+
+    @Override
+    public String execute(Context context, Map<String, String> params) throws PluginException {
+        return "<h1>HelloWorld</h1>";
+    }
+}

jspwiki-it-tests/jspwiki-test-plugin/src/main/resources/META-INF/services/org.apache.wiki.api.plugin,Plugin

@@ -0,0 +1 @@
+org.apache.jspwiki.jspwiki.test.plugin.JspwikiTestPlugin

jspwiki-it-tests/jspwiki-test-plugin/src/main/resources/ini/jspwiki_module.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<modules>
+   <plugin class="org.apache.jspwiki.jspwiki.test.plugin.JspwikiTestPlugin">
+      <author>Apache</author>
+      <minVersion>3.0.0</minVersion>
+      <alias>JspwikiTestPlugin</alias>
+   </plugin>
+</modules>

jspwiki-it-tests/pom.xml

@@ -38,6 +38,7 @@
     <module>jspwiki-it-test-custom-jdbc</module>
     <module>jspwiki-it-test-cma</module>
     <module>jspwiki-it-test-cma-jdbc</module>
+	<module>jspwiki-test-plugin</module>
   </modules>
 
   <dependencies>

jspwiki-main/src/main/java/org/apache/wiki/plugin/CurrentTimePlugin.java

@@ -27,44 +27,57 @@ Licensed to the Apache Software Foundation (ASF) under one
 
 import java.text.SimpleDateFormat;
 import java.util.Date;
+import java.util.Locale;
 import java.util.Map;
 import java.util.ResourceBundle;
 
 /**
- *  Just displays the current date and time.
- *  The time format is exactly like in the java.text.SimpleDateFormat class.
+ * Just displays the current date and time. The time format is exactly like in
+ * the java.text.SimpleDateFormat class.
  *
- *  <p>Parameters : </p>
- *  NONE
- *  @since 1.7.8
- *  @see java.text.SimpleDateFormat
+ * <p>
+ * Parameters : </p>
+ * NONE
+ *
+ * @since 1.7.8
+ * @see java.text.SimpleDateFormat
  */
 public class CurrentTimePlugin implements Plugin {
 
-    // private static Logger log = LogManager.getLogger( CurrentTimePlugin.class );
+    @Override
+    public String getDisplayName(Locale locale) {
+        final ResourceBundle rb = ResourceBundle.getBundle(PluginManager.PLUGIN_RESOURCE_LOCATION, locale);
+        return rb.getString(this.getClass().getSimpleName());
+
+    }
+
+    @Override
+    public String getSnipExample() {
+        return "CurrentTimePlugin format='yyyy mm-dd'";
+    }
 
     /**
-     *  {@inheritDoc}
+     * {@inheritDoc}
      */
     @Override
-    public String execute( final Context context, final Map< String, String > params ) throws PluginException {
-        final String formatString = params.get( "format" );
+    public String execute(final Context context, final Map< String, String> params) throws PluginException {
+        final String formatString = params.get("format");
 
         try {
             final SimpleDateFormat fmt;
-            if( formatString != null ) {
-                fmt = new SimpleDateFormat( formatString );
+            if (formatString != null) {
+                fmt = new SimpleDateFormat(formatString);
             } else {
-                fmt = Preferences.getDateFormat( context, TimeFormat.DATETIME );
+                fmt = Preferences.getDateFormat(context, TimeFormat.DATETIME);
             }
 
             final Date d = new Date();  // Now.
 
-            return TextUtil.replaceEntities( fmt.format( d ) );
+            return TextUtil.replaceEntities(fmt.format(d));
 
-        } catch( final IllegalArgumentException e ) {
-            final ResourceBundle rb = Preferences.getBundle( context, Plugin.CORE_PLUGINS_RESOURCEBUNDLE );
-            throw new PluginException( rb.getString( "currenttimeplugin.badformat" ) + e.getMessage() );
+        } catch (final IllegalArgumentException e) {
+            final ResourceBundle rb = Preferences.getBundle(context, Plugin.CORE_PLUGINS_RESOURCEBUNDLE);
+            throw new PluginException(rb.getString("currenttimeplugin.badformat") + e.getMessage());
         }
     }
 

jspwiki-main/src/main/java/org/apache/wiki/plugin/DefaultPluginManager.java

@@ -59,11 +59,13 @@ Licensed to the Apache Software Foundation (ASF) under one
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.HashMap;
+import java.util.HashSet;
 import java.util.List;
 import java.util.Map;
 import java.util.NoSuchElementException;
 import java.util.Properties;
 import java.util.ResourceBundle;
+import java.util.Set;
 import java.util.StringTokenizer;
 
 /**
@@ -719,4 +721,20 @@ public Plugin newWikiPlugin( final String pluginName, final ResourceBundle rb )
         return plugin;
     }
 
+    @Override
+    public List<Plugin> getDiscoveredPlugins() {
+        Collection<WikiModuleInfo> pluginModules = modules();
+        Set<Plugin> plugins = new HashSet<>();
+        for(WikiModuleInfo plugin : pluginModules) {
+            try {
+                Plugin p = (Plugin) Class.forName(((WikiPluginInfo)plugin).getClassName()).getDeclaredConstructor().newInstance();
+                plugins.add(p);
+            } catch (Throwable ex) {
+                LOG.error("failed to load class " + plugin.getName(), ex);
+            }
+        }
+
+        return new ArrayList<>(plugins);
+    }
+
 }

jspwiki-main/src/main/java/org/apache/wiki/plugin/Denounce.java

@@ -40,8 +40,10 @@ Licensed to the Apache Software Foundation (ASF) under one
 import java.util.ArrayList;
 import java.util.Enumeration;
 import java.util.List;
+import java.util.Locale;
 import java.util.Map;
 import java.util.Properties;
+import java.util.ResourceBundle;
 
 /**
  *  Denounces a link by removing it from any search engine.
@@ -119,6 +121,12 @@ public class Denounce implements Plugin {
         }
     }
 
+    @Override
+    public String getDisplayName(Locale locale) {
+
+        final ResourceBundle rb = ResourceBundle.getBundle(PluginManager.PLUGIN_RESOURCE_LOCATION, locale);
+        return rb.getString(this.getClass().getSimpleName());
+    }
     /**
      *  {@inheritDoc}
      */

jspwiki-main/src/main/java/org/apache/wiki/plugin/Groups.java

@@ -30,7 +30,9 @@ Licensed to the Apache Software Foundation (ASF) under one
 import java.security.Principal;
 import java.util.Arrays;
 import java.util.Comparator;
+import java.util.Locale;
 import java.util.Map;
+import java.util.ResourceBundle;
 
 /**
  *  <p>Prints the groups managed by this wiki, separated by commas.
@@ -45,6 +47,13 @@ public class Groups implements Plugin {
 
     private static final Comparator<Principal> COMPARATOR = new PrincipalComparator();
 
+    @Override
+    public String getDisplayName(Locale locale) {
+
+        final ResourceBundle rb = ResourceBundle.getBundle(PluginManager.PLUGIN_RESOURCE_LOCATION, locale);
+        return rb.getString(this.getClass().getSimpleName());
+    }
+
     /**
      *  {@inheritDoc}
      */

jspwiki-main/src/main/java/org/apache/wiki/plugin/IfPlugin.java

@@ -38,7 +38,10 @@ Licensed to the Apache Software Foundation (ASF) under one
 import org.apache.wiki.variables.VariableManager;
 
 import java.security.Principal;
+import java.util.Locale;
 import java.util.Map;
+import java.util.ResourceBundle;
+import org.apache.wiki.i18n.InternationalizationManager;
 
 /**
  *  The IfPlugin allows parts of a WikiPage to be executed conditionally, and is intended as a flexible way
@@ -140,6 +143,16 @@ public class IfPlugin implements Plugin {
     /** The parameter name for checking whether a page/var exists.  Value is <tt>{@value}</tt>. */
     public static final String PARAM_EXISTS   = "exists";
 
+    @Override
+    public String getDisplayName(Locale locale) {
+        final ResourceBundle rb = ResourceBundle.getBundle(PluginManager.PLUGIN_RESOURCE_LOCATION, locale);
+        return rb.getString(this.getClass().getSimpleName());
+    }
+
+    @Override
+    public String getSnipExample() {
+        return "If name='{value}' page='pagename' exists='true' contains='regexp'\n\nbody\n";
+    }
     /**
      *  {@inheritDoc}
      */

jspwiki-main/src/main/java/org/apache/wiki/plugin/Image.java

@@ -18,6 +18,7 @@ Licensed to the Apache Software Foundation (ASF) under one
  */
 package org.apache.wiki.plugin;
 
+import java.util.Locale;
 import org.apache.wiki.api.core.Attachment;
 import org.apache.wiki.api.core.Context;
 import org.apache.wiki.api.core.ContextEnum;
@@ -30,6 +31,7 @@ Licensed to the Apache Software Foundation (ASF) under one
 import org.apache.wiki.util.TextUtil;
 
 import java.util.Map;
+import java.util.ResourceBundle;
 
 
 /**
@@ -89,6 +91,19 @@ public class Image implements Plugin {
     private static String getCleanParameter( final Map< String, String > params, final String paramId ) {
         return TextUtil.replaceEntities( params.get( paramId ) );
     }
+
+    @Override
+    public String getDisplayName(Locale locale) {
+        final ResourceBundle rb = ResourceBundle.getBundle(PluginManager.PLUGIN_RESOURCE_LOCATION, locale);
+        return rb.getString(this.getClass().getSimpleName());
+    }
+
+    @Override
+    public String  getSnipExample() {
+        return  "Image src='{image.jpg}'";
+    }
+
+
 
     /**
      *  {@inheritDoc}