Make Dispatchers and Sources self described

Also introduce two "test" ones, one dispatcher and
one source, usable ONLY for testing, as those two
have nothing with "encryption".

Author: cstamas

src/main/java/org/codehaus/plexus/components/secdispatcher/MasterMeta.java

@@ -0,0 +1,13 @@
+package org.codehaus.plexus.components.secdispatcher;
+
+import java.util.Map;
+
+/**
+ * Meta description of master password source.
+ */
+public interface MasterMeta extends Meta {
+    /**
+     * Creates source configuration that can be used as "masterSource".
+     */
+    String createConfig(Map<String, String> data);
+}

src/main/java/org/codehaus/plexus/components/secdispatcher/Meta.java

@@ -0,0 +1,91 @@
+package org.codehaus.plexus.components.secdispatcher;
+
+import java.util.Collection;
+import java.util.Map;
+import java.util.Optional;
+
+import static java.util.Objects.requireNonNull;
+
+/**
+ * Meta description of dispatcher.
+ */
+public interface Meta {
+    class Field {
+        private final String key;
+        private final boolean optional;
+        private final String defaultValue;
+        private final String description;
+
+        private Field(String key, boolean optional, String defaultValue, String description) {
+            this.key = requireNonNull(key);
+            this.optional = optional;
+            this.defaultValue = defaultValue;
+            this.description = requireNonNull(description);
+        }
+
+        public String getKey() {
+            return key;
+        }
+
+        public boolean isOptional() {
+            return optional;
+        }
+
+        public Optional<String> getDefaultValue() {
+            return Optional.ofNullable(defaultValue);
+        }
+
+        public String getDescription() {
+            return description;
+        }
+
+        public static Builder builder(String key) {
+            return new Builder(key);
+        }
+
+        public static class Builder {
+            private final String key;
+            private boolean optional;
+            private String defaultValue;
+            private String description;
+
+            private Builder(String key) {
+                this.key = requireNonNull(key);
+            }
+
+            public Builder optional(boolean optional) {
+                this.optional = optional;
+                return this;
+            }
+
+            public Builder defaultValue(String defaultValue) {
+                this.defaultValue = defaultValue;
+                return this;
+            }
+
+            public Builder description(String description) {
+                this.description = requireNonNull(description);
+                return this;
+            }
+
+            public Field build() {
+                return new Field(key, optional, defaultValue, description);
+            }
+        }
+    }
+
+    /**
+     * The key of the item.
+     */
+    String id();
+
+    /**
+     * Returns the display (human) name of the item.
+     */
+    String displayName();
+
+    /**
+     * Returns the configuration fields of the item.
+     */
+    Collection<Field> fields();
+}

src/main/java/org/codehaus/plexus/components/secdispatcher/SecDispatcher.java

@@ -46,15 +46,20 @@ public interface SecDispatcher {
     String DISPATCHER_NAME_ATTR = "name";
 
     /**
-     * Returns the set of available dispatcher names, never {@code null}.
+     * Returns the set of available dispatcher metadata, never {@code null}.
      */
-    Set<String> availableDispatchers();
+    Set<Meta> availableDispatchers();
 
     /**
      * Returns the set of available ciphers, never {@code null}.
      */
     Set<String> availableCiphers();
 
+    /**
+     * Returns the set of available master password sources metadata, never {@code null}.
+     */
+    Set<MasterMeta> availableMasterSourcesMetadata();
+
     /**
      * Encrypt given plaintext string.
      *
@@ -87,7 +92,7 @@ public interface SecDispatcher {
      * Writes the effective configuration.
      *
      * @param configuration The configuration to write, may not be {@code null}
-     * @throws IOException In case of IO problem
+     * x     * @throws IOException In case of IO problem
      */
     void writeConfiguration(SettingsSecurity configuration) throws IOException;
 }

src/main/java/org/codehaus/plexus/components/secdispatcher/internal/DefaultSecDispatcher.java

@@ -28,6 +28,8 @@
 
 import org.codehaus.plexus.components.cipher.PlexusCipher;
 import org.codehaus.plexus.components.cipher.PlexusCipherException;
+import org.codehaus.plexus.components.secdispatcher.MasterMeta;
+import org.codehaus.plexus.components.secdispatcher.Meta;
 import org.codehaus.plexus.components.secdispatcher.SecDispatcher;
 import org.codehaus.plexus.components.secdispatcher.SecDispatcherException;
 import org.codehaus.plexus.components.secdispatcher.model.SettingsSecurity;
@@ -44,32 +46,38 @@ public class DefaultSecDispatcher implements SecDispatcher {
     public static final String ATTR_STOP = "]";
 
     protected final PlexusCipher cipher;
-    protected final Map<String, MasterPasswordSource> masterPasswordSources;
+    protected final Map<String, MasterSource> masterSources;
     protected final Map<String, Dispatcher> dispatchers;
     protected final String configurationFile;
 
     @Inject
     public DefaultSecDispatcher(
             PlexusCipher cipher,
-            Map<String, MasterPasswordSource> masterPasswordSources,
+            Map<String, MasterSource> masterSources,
             Map<String, Dispatcher> dispatchers,
             @Named("${configurationFile:-" + DEFAULT_CONFIGURATION + "}") final String configurationFile) {
         this.cipher = requireNonNull(cipher);
-        this.masterPasswordSources = requireNonNull(masterPasswordSources);
+        this.masterSources = requireNonNull(masterSources);
         this.dispatchers = requireNonNull(dispatchers);
         this.configurationFile = requireNonNull(configurationFile);
     }
 
     @Override
-    public Set<String> availableDispatchers() {
-        return Set.copyOf(dispatchers.keySet());
+    public Set<Meta> availableDispatchers() {
+        return Set.copyOf(dispatchers.values().stream().map(Dispatcher::meta).collect(Collectors.toSet()));
     }
 
     @Override
     public Set<String> availableCiphers() {
         return cipher.availableCiphers();
     }
 
+    @Override
+    public Set<MasterMeta> availableMasterSourcesMetadata() {
+        return Set.copyOf(
+                masterSources.values().stream().map(MasterSource::meta).collect(Collectors.toSet()));
+    }
+
     @Override
     public String encrypt(String str, Map<String, String> attr) throws SecDispatcherException {
         if (isEncryptedString(str)) return str;
@@ -204,12 +212,12 @@ private SettingsSecurity getConfiguration(boolean mandatory) throws SecDispatche
     }
 
     private String getMasterPassword(SettingsSecurity sec, boolean mandatory) throws SecDispatcherException {
-        if (sec == null && !mandatory) {
+        if ((sec == null || sec.getMasterSource() == null) && !mandatory) {
             return null;
         }
         requireNonNull(sec, "configuration is null");
         String masterSource = requireNonNull(sec.getMasterSource(), "masterSource is null");
-        for (MasterPasswordSource masterPasswordSource : masterPasswordSources.values()) {
+        for (MasterSource masterPasswordSource : masterSources.values()) {
             String masterPassword = masterPasswordSource.handle(masterSource);
             if (masterPassword != null) return masterPassword;
         }

src/main/java/org/codehaus/plexus/components/secdispatcher/internal/Dispatcher.java

@@ -15,6 +15,7 @@
 
 import java.util.Map;
 
+import org.codehaus.plexus.components.secdispatcher.Meta;
 import org.codehaus.plexus.components.secdispatcher.SecDispatcherException;
 
 /**
@@ -32,6 +33,11 @@ public interface Dispatcher {
      */
     String CONF_MASTER_PASSWORD = "masterPassword";
 
+    /**
+     * The metadata of this dispatcher.
+     */
+    Meta meta();
+
     /**
      * encrypt given plaintext string
      *

src/main/java/org/codehaus/plexus/components/secdispatcher/internal/MasterPasswordSource.java renamed to src/main/java/org/codehaus/plexus/components/secdispatcher/internal/MasterSource.java

@@ -13,12 +13,18 @@
 
 package org.codehaus.plexus.components.secdispatcher.internal;
 
+import org.codehaus.plexus.components.secdispatcher.MasterMeta;
 import org.codehaus.plexus.components.secdispatcher.SecDispatcherException;
 
 /**
  * Source of master password.
  */
-public interface MasterPasswordSource {
+public interface MasterSource {
+    /**
+     * Returns the "meta" of this master source, never {@code null}.
+     */
+    MasterMeta meta();
+
     /**
      * Handles the URI to get master password. Implementation may do one of the following things:
      * <ul>

src/main/java/org/codehaus/plexus/components/secdispatcher/internal/dispatchers/TestDispatcher.java

@@ -0,0 +1,74 @@
+/*
+ * Copyright (c) 2008 Sonatype, Inc. All rights reserved.
+ *
+ * This program is licensed to you under the Apache License Version 2.0,
+ * and you may not use this file except in compliance with the Apache License Version 2.0.
+ * You may obtain a copy of the Apache License Version 2.0 at http://www.apache.org/licenses/LICENSE-2.0.
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the Apache License Version 2.0 is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the Apache License Version 2.0 for the specific language governing permissions and limitations there under.
+ */
+
+package org.codehaus.plexus.components.secdispatcher.internal.dispatchers;
+
+import org.codehaus.plexus.components.secdispatcher.Meta;
+import org.codehaus.plexus.components.secdispatcher.SecDispatcherException;
+import org.codehaus.plexus.components.secdispatcher.internal.Dispatcher;
+
+import javax.inject.Named;
+import javax.inject.Singleton;
+import java.util.Collection;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * This dispatcher is purely for test purposes, is obviously NOT a true encryption implementation.
+ */
+@Singleton
+@Named(TestDispatcher.NAME)
+public class TestDispatcher implements Dispatcher {
+    public static final String NAME = "test";
+
+    @Override
+    public Meta meta() {
+        return new Meta() {
+            @Override
+            public String id() {
+                return NAME;
+            }
+
+            @Override
+            public String displayName() {
+                return "Test Dispatcher (for testing only)";
+            }
+
+            @Override
+            public Collection<Field> fields() {
+                return List.of(Field.builder("salt")
+                        .optional(false)
+                        .description("The salt for testing")
+                        .build());
+            }
+        };
+    }
+
+    protected String getSalt(Map<String, String> config) throws SecDispatcherException {
+        String salt = config.get("salt");
+        if (salt == null) {
+            throw new SecDispatcherException("The configuration is incomplete; missing salt");
+        }
+        return salt;
+    }
+
+    @Override
+    public String encrypt(String str, Map<String, String> attributes, Map<String, String> config) throws SecDispatcherException {
+        return new StringBuilder(str).reverse() + "@" + getSalt(config);
+    }
+
+    @Override
+    public String decrypt(String str, Map<String, String> attributes, Map<String, String> config) throws SecDispatcherException {
+        return new StringBuilder(str).reverse().substring(getSalt(config).length() + 1);
+    }
+}

src/main/java/org/codehaus/plexus/components/secdispatcher/internal/sources/EnvMasterPasswordSource.java renamed to src/main/java/org/codehaus/plexus/components/secdispatcher/internal/sources/EnvMasterSource.java

@@ -21,20 +21,55 @@
 import javax.inject.Named;
 import javax.inject.Singleton;
 
+import java.util.Collection;
+import java.util.List;
+import java.util.Map;
+
+import org.codehaus.plexus.components.secdispatcher.MasterMeta;
 import org.codehaus.plexus.components.secdispatcher.SecDispatcherException;
 
+import static java.util.Objects.requireNonNull;
+
 /**
  * Password source that uses env.
  */
 @Singleton
-@Named(EnvMasterPasswordSource.NAME)
-public final class EnvMasterPasswordSource extends PrefixMasterPasswordSourceSupport {
+@Named(EnvMasterSource.NAME)
+public final class EnvMasterSource extends PrefixMasterSourceSupport {
     public static final String NAME = "env";
 
-    public EnvMasterPasswordSource() {
+    public EnvMasterSource() {
         super(NAME + ":");
     }
 
+    @Override
+    public MasterMeta meta() {
+        return new MasterMeta() {
+            @Override
+            public String id() {
+                return NAME;
+            }
+
+            @Override
+            public String displayName() {
+                return "Environment Variable Source";
+            }
+
+            @Override
+            public Collection<Field> fields() {
+                return List.of(Field.builder("name")
+                        .optional(false)
+                        .description("Name of the environment variable")
+                        .build());
+            }
+
+            @Override
+            public String createConfig(Map<String, String> data) {
+                return NAME + ":" + requireNonNull(data.get("name"), "Config incomplete");
+            }
+        };
+    }
+
     @Override
     protected String doHandle(String transformed) throws SecDispatcherException {
         String value = System.getenv(transformed);