#27: Improved quoting and cleaned up handling of placeholders and parameters (#38)

* #27: Cleaned up code and documentation. Added more tests.

Author: redcatbear

.gitattributes

@@ -1 +1,4 @@
-pk_generated_parent.pom linguist-generated=true
+pk_generated_parent.pom linguist-generated=true
+versionsMavenPluginRules.xml linguist-generated=true
+dependencies.md linguist-generated=true
+doc/changes/changelog.md linguist-generated=true

README.md

@@ -44,37 +44,58 @@ Result:
 
 The optional third parameter for `parameter(placeholder, value, description)` is used by the [error-code-crawler-maven-plugin](https://github.com/exasol/error-code-crawler-maven-plugin) to generate a parameter description.
 
-The builder automatically quotes parameters of the following types:
-
-* `String`
-* `Character`
-* `Path`
-* `File`
-* `URI`
-* `URL`
-
-If you don't want that, use the `uq` switch in the correspondent placeholder. Switches are separated with a pipe symbol "|" from the parameter name.
+From version `0.3.0` on you can achieve the same result by specifying the parameter values directly in the `message()` method. This is a convenience variant that is a little more compact, but lacks the chance to describe the parameter.
 
 ```java
 ExaError.messageBuilder("E-TEST-2")
-    .message("Unknown input: {{input|uq}}.")
-    .parameter("input", "unknown", "The illegal user input.").toString();
+    .message("Message with {{first-parameter}} and {{second-parameter}}.", "first value", "second value").toString();
 ```
 
 Result:
 
-    E-TEST-2: Unknown input: unknown.
+    E-TEST-2: Message with 'q-value' and uq-value.
+
+#### Automatic Quoting
+
+When replacing placeholders in messages, `ExaError` quotes the values according to your choices. If you don't specify a quoting option in a placeholder, you get auto-quoting. In this mode values are quoted depending on their type.
+
+| Type                 | Quoted with     | Example                    | Since version |
+|----------------------|-----------------|----------------------------|--------------:|
+| `String`             | single quotes   | `'Hello world!'`           |               |
+| `Character` / `char` | single quotes   | `'A'`                      |               |
+| `Path`               | single quotes   | `'/etc/cron.d'`            |         1.0.0 |
+| `File`               | single quotes   | `'~/.bashrc'`              |         1.0.0 |
+| `URI`                | single quotes   | `'URN:ISBN:0-330-28700-1'` |         1.0.0 |
+| `URL`                | single quotes   | `'https://example.org'`    |         1.0.0 |
+| null values          | pointy brackets | `<null>`                   |               |
+| everything else      | not quoted      | `42`, `3.1415`, `true`     |               |
+
+#### Manual Quoting
 
-From version `0.3.0` on you can achieve the same result by specifying the parameter values directly in the `message()` method. This is a convenience variant that is a little bit more compact, but lacks the chance to describe the parameter.
+If you need a different quoting style, you can add switches to the placeholder definition:
+
+`u`
+: unquoted
+
+`q`
+: forced single quotes
+
+`d`
+: forced double quotes
+
+If multiple conflicting switches are given, the one with the highest precedence (see list above) is taken.
+
+Switches are separated with a pipe symbol `|` from the parameter name.
 
 ```java
 ExaError.messageBuilder("E-TEST-2")
-    .message("Message with {{quotedParameter}} and {{unquotedParameter|uq}}.", "q-value", "uq-value").toString();
+    .message("Unknown input: {{input|u}}.")
+    .parameter("input", "unknown", "The illegal user input.").toString();
 ```
 
 Result:
 
-    E-TEST-2: Message with 'q-value' and uq-value.
+    E-TEST-2: Unknown input: unknown.
 
 ### Mitigations
 

doc/changes/changes_1.0.0.md

@@ -1,14 +1,33 @@
-# error-reporting-java 1.0.0, released 2022-08-30
+# error-reporting-java 1.0.0, released 2022-09-02
 
 Code name: Quoting enhancements
 
 In this release we added a guideline for deleting error codes and migrated the project to Project Keeper 2.
 
 When you use Java types `Path`, `File`, `URL` or `URI` as parameter in a message, it now automatically gets quoted. Note that this can break existing unit tests in you code or client code that parses error messages.
 
+We also now support quoting with double quotes.
+
 Note that we removed the deprecated `unquotedParameter` methods.
 
-For the reviewers: open TODOs for this release: #28, #27, #19
+Quoting is now exclusively controlled by the following single-character switches:
+
+`u`
+: unquoted
+
+`q`
+: forced single quotes
+
+`d`
+: forced double quotes
+
+none
+: automatic quoting depending on the type
+
+If multiple conflicting switches are given, the one with the highest precedence (see list above) is taken.
+That means the previous `uq` switch still works because the `q` is ignored in this case.
+
+Quoting now supports all collections, not only lists.
 
 ## Documentation
 

src/main/java/com/exasol/errorreporting/ErrorMessageBuilder.java

@@ -9,8 +9,7 @@ public class ErrorMessageBuilder {
     private final String errorCode;
     private final StringBuilder messageBuilder = new StringBuilder();
     private final List<String> mitigations = new ArrayList<>();
-    private final Map<String, Object> parameterMapping = new HashMap<>();
-    private final Map<String, Object> explicitlyUnquotedParameterMapping = new HashMap<>();
+    private final ParameterDefinitionList parameterDefinitions = new ParameterDefinitionList();
 
     /**
      * Create a new instance of {@link ErrorMessageBuilder}.
@@ -22,47 +21,17 @@ public class ErrorMessageBuilder {
     }
 
     /**
-     * Format a given message pattern with placeholders, filling them with the arguments passed in the specified form.
+     * Define an error message.
      * <p>
-     * Placeholders are defined in the message pattern by using double curly brackets {@code {{}}}. By default,
-     * arguments are formatted with simple quotes unless specified other wise with the 'unquoted' format, defined by
-     * {@code {{|uq}}}.
+     * Error messages can optionally contain placeholders that can be replaced by arguments.
      * </p>
-     * <p>
-     * You should always define names in the placeholders. This name will be shown in case no argument is missing, by
-     * {@code {{argumentName}}} or {@code {{argumentName|uq}}}.
-     * </p>
-     * <p>
-     * Below you can find examples on how to use it.
-     * </p>
-     * <p>
-     * Example for quoted arguments:
-     * </p>
-     * <p>
-     * {@code ErrorMessageBuilder("ERROR_CODE").message("Message with {{namedQuotedArgument}}, {{}} and
-     * {{missingQuotedArgument}}, "named", "unnamed")}
-     * </p>
-     * <p>
-     * returns "ERROR_CODE: Message with 'named', 'unnamed' and UNKNOWN PLACEHOLDER('anotherQuotedArgument')".
-     * </p>
-     * <p>
-     * Example for unquoted arguments:
-     * </p>
-     * <p>
-     * {@code ErrorMessageBuilder("ERROR_CODE").message("Message with {{namedUnquotedArgument|uq}}, {{|uq}} and
-     * {{missingUnquotedArgument|uq}}, "named", "unnamed")}
-     * </p>
-     * <p>
-     * returns "ERROR_CODE: Message with named, unnamed and UNKNOWN PLACEHOLDER('anotherQuotedArgument')".
-     * </p>
-     *
      * @param message   message that may contain placeholders
      * @param arguments arguments to fill the placeholders
      * @return self for fluent programming
      */
     public ErrorMessageBuilder message(final String message, final Object... arguments) {
-        this.messageBuilder.append(message);
-        this.addParameters(message, arguments);
+        messageBuilder.append(message);
+        addParameters(message, arguments);
         return this;
     }
 
@@ -84,12 +53,12 @@ private Object[] getPatternArguments(final Object[] arguments) {
      * You can use the parameter in message and mitigation using {@code {{parameter}}}.
      * </p>
      *
-     * @param placeholder placeholder without parentheses
-     * @param value       value to insert
+     * @param name parameter name
+     * @param value value to insert
      * @return self for fluent programming
      */
-    public ErrorMessageBuilder parameter(final String placeholder, final Object value) {
-        this.parameterMapping.put(placeholder, value);
+    public ErrorMessageBuilder parameter(final String name, final Object value) {
+        parameterDefinitions.add(ParameterDefinition.builder(name).value(value).build());
         return this;
     }
 
@@ -98,14 +67,19 @@ public ErrorMessageBuilder parameter(final String placeholder, final Object valu
      * <p>
      * You can use the parameter in message and mitigation using {@code {{parameter}}}.
      * </p>
+     * <p>
+     * Note that the last parameter exists only as a means to add a description in the error catalog. It is not used
+     * when displaying error messages to the application users.
+     * </p>
      *
      * @param placeholder placeholder without parentheses
-     * @param value       value to insert
-     * @param description description for the error catalog
+     * @param value value to insert
+     * @param ignoredDescription description for the error catalog
      * @return self for fluent programming
      */
-    public ErrorMessageBuilder parameter(final String placeholder, final Object value, final String description) {
-        return this.parameter(placeholder, value);
+    public ErrorMessageBuilder parameter(final String placeholder, final Object value,
+            final String ignoredDescription) {
+        return parameter(placeholder, value);
     }
 
     /**
@@ -119,8 +93,8 @@ public ErrorMessageBuilder parameter(final String placeholder, final Object valu
      * @return self for fluent programming
      */
     public ErrorMessageBuilder mitigation(final String mitigation, final Object... arguments) {
-        this.mitigations.add(mitigation);
-        this.addParameters(mitigation, arguments);
+        mitigations.add(mitigation);
+        addParameters(mitigation, arguments);
         return this;
     }
 
@@ -161,7 +135,6 @@ public String toString() {
     }
 
     private String replacePlaceholders(final String subject) {
-        return PlaceholdersFiller.fillPlaceholders(subject, this.parameterMapping,
-                this.explicitlyUnquotedParameterMapping);
+        return PlaceholdersFiller.fillPlaceholders(subject, this.parameterDefinitions);
     }
 }

src/main/java/com/exasol/errorreporting/ParameterDefinition.java

@@ -0,0 +1,138 @@
+package com.exasol.errorreporting;
+
+/**
+ * The class models an error code parameter.
+ */
+public class ParameterDefinition {
+    /** Replacement Parameter in case a parameter is missing its name */
+    public static final ParameterDefinition UNDEFINED_PARAMETER = ParameterDefinition.builder("undefined parameter")
+            .build();
+    private final String name;
+    private final Object value;
+    private final String description;
+
+    private ParameterDefinition(final Builder builder) {
+        this.name = builder.name;
+        this.value = builder.value;
+        this.description = builder.description;
+    }
+
+    /**
+     * Create a builder for an error code {@link ParameterDefinition}.
+     *
+     * @param name name of the parameter
+     * @return parameter builder
+     */
+    public static ParameterDefinition.Builder builder(final String name) {
+        return new Builder(name);
+    }
+
+    /**
+     * Get the parameter name.
+     *
+     * @return name of the parameter
+     */
+    public String getName() {
+        return this.name;
+    }
+
+    /**
+     * Get the parameter value.
+     *
+     * @return value assigned to the parameter
+     */
+    public Object getValue() {
+        return this.value;
+    }
+
+    /**
+     * Get the parameter description.
+     *
+     * @return description of the parameter
+     */
+    public String getDescription() {
+        return this.description;
+    }
+
+    /**
+     * Check if the parameter has a name.
+     *
+     * @return {@code true} if the name is set.
+     */
+    public boolean hasName() {
+        return this.name != null;
+    }
+
+    /**
+     * Check if the value is set.
+     *
+     * @return {@code true} if the value is set.
+     */
+    public boolean hasValue() {
+        return this.value != null;
+    }
+
+    /**
+     * Check if the description is set.
+     *
+     * @return {@code true} if the description is set
+     */
+    public boolean hasDescription() {
+        return this.description != null;
+    }
+
+    @Override
+    public String toString() {
+        if(hasValue()) {
+            return this.value.toString();
+        }
+        else {
+            return "<null>";
+        }
+    }
+
+    /**
+     * Builder for an error code {@link ParameterDefinition}.
+     */
+    public static class Builder {
+        private final String name;
+        private Object value;
+        private String description;
+
+
+        private Builder(final String name) {
+            this.name = name;
+        }
+
+        /**
+         * Set the parameter value.
+         *
+         * @param value value of the parameter
+         * @return self for fluent programming
+         */
+        public Builder value(final Object value) {
+            this.value = value;
+            return this;
+        }
+
+        /**
+         * Set the parameter description.
+         *
+         * @param description description of the parameter
+         * @return self for fluent programming
+         */
+        public Builder description(final String description) {
+            this.description = description;
+            return this;
+        }
+
+        /**
+         * Build the {@link ParameterDefinition}.
+         *
+         * @return new {@link ParameterDefinition}
+         */
+        public ParameterDefinition build() {
+            return new ParameterDefinition(this);
+        }
+    }
+}