[freemarker-generator] branch FREEMARKER-172 updated: FREEMARKER-172 [freemarker-generator] Improve documentation

[sg...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

sgoeschl pushed a commit to branch FREEMARKER-172
in repository https://gitbox.apache.org/repos/asf/freemarker-generator.git


The following commit(s) were added to refs/heads/FREEMARKER-172 by this push:
     new 1cd9642  FREEMARKER-172 [freemarker-generator] Improve documentation
1cd9642 is described below

commit 1cd9642271cc805d4b39ea122a50d38d1a60cb61
Author: Siegfried Goeschl <si...@gmail.com>
AuthorDate: Fri Feb 5 09:06:02 2021 +0100

    FREEMARKER-172 [freemarker-generator] Improve documentation
---
 .../freemarker/generator/base/datasource/DataSource.java       |  5 +++--
 .../freemarker/generator/base/datasource/DataSources.java      | 10 ++++++++--
 .../freemarker/generator/cli/model/GeneratorObjectWrapper.java |  5 ++++-
 3 files changed, 15 insertions(+), 5 deletions(-)

diff --git a/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/datasource/DataSource.java b/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/datasource/DataSource.java
index 522f0f1..c030a19 100644
--- a/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/datasource/DataSource.java
+++ b/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/datasource/DataSource.java
@@ -238,7 +238,7 @@ public class DataSource implements Closeable, javax.activation.DataSource {
     }
 
     /**
-     * Gets the contents of an <code>InputStream</code> as a list of Strings,
+     * Get the content of an <code>InputStream</code> as a list of Strings,
      * one entry per line, using the specified character encoding.
      *
      * @return the list of Strings, never null
@@ -366,7 +366,8 @@ public class DataSource implements Closeable, javax.activation.DataSource {
 
     /**
      * If there is no content type we ask the underlying data source. E.g. for
-     * an URL data source this information is fetched from the remote server.
+     * an <code>URLDataSource</code> this information is fetched from the
+     * remote server.
      *
      * @return content type
      */
diff --git a/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/datasource/DataSources.java b/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/datasource/DataSources.java
index 48bf0fc..b95f100 100644
--- a/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/datasource/DataSources.java
+++ b/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/datasource/DataSources.java
@@ -26,6 +26,7 @@ import java.util.Collection;
 import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.Set;
 import java.util.stream.Collectors;
 
 import static java.util.function.Function.identity;
@@ -76,7 +77,6 @@ public class DataSources implements Closeable {
         return dataSources.stream()
                 .map(DataSource::getGroup)
                 .filter(StringUtils::isNotEmpty)
-                .sorted()
                 .distinct()
                 .collect(Collectors.toList());
     }
@@ -100,8 +100,14 @@ public class DataSources implements Closeable {
 
     /**
      * Get a map representation of the underlying data sources.
+     * In <code>freemarker-cli</code> the map is also used to
+     * iterate over data source so we need to return a
+     * <code>LinkedHashMap</code>.
+     * <p>
+     * The implementation also throws as <code>IllegalStateException</code>
+     * when finding duplicate keys to avoid "losing" data sources.
      *
-     * @return map of data sources
+     * @return linked hasp map of data sources
      */
     public Map<String, DataSource> toMap() {
         return dataSources.stream().collect(Collectors.toMap(
diff --git a/freemarker-generator-cli/src/main/java/org/apache/freemarker/generator/cli/model/GeneratorObjectWrapper.java b/freemarker-generator-cli/src/main/java/org/apache/freemarker/generator/cli/model/GeneratorObjectWrapper.java
index 393dcdd..921722c 100644
--- a/freemarker-generator-cli/src/main/java/org/apache/freemarker/generator/cli/model/GeneratorObjectWrapper.java
+++ b/freemarker-generator-cli/src/main/java/org/apache/freemarker/generator/cli/model/GeneratorObjectWrapper.java
@@ -23,6 +23,10 @@ import freemarker.template.TemplateModelException;
 import freemarker.template.Version;
 import org.apache.freemarker.generator.base.datasource.DataSources;
 
+/**
+ * Custom FreeMarker object wrapper to expose <code>DataSources</code>
+ * as <code>Map</code> in the FreeMarker data model.
+ */
 public class GeneratorObjectWrapper extends DefaultObjectWrapper {
 
     public GeneratorObjectWrapper(Version incompatibleImprovements) {
@@ -32,7 +36,6 @@ public class GeneratorObjectWrapper extends DefaultObjectWrapper {
     @Override
     protected TemplateModel handleUnknownType(Object obj) throws TemplateModelException {
         if (obj instanceof DataSources) {
-            // Expose "DataSources" as map in the FreeMarker data model
             final DataSources dataSources = (DataSources) obj;
             return DefaultMapAdapter.adapt((dataSources).toMap(), this);
         }