Adds PlantUML/Mermaid/Kroki importers, refactoring to support new library responsibilities.

Author: simonbrowndotje

build.gradle

@@ -9,7 +9,7 @@ repositories {
 }
 
 dependencies {
-    api 'com.structurizr:structurizr-client:1.19.0'
+    api 'com.structurizr:structurizr-client:1.20.0'
 
     testImplementation 'org.junit.jupiter:junit-jupiter:5.9.0'
 }

src/main/java/com/structurizr/importer/diagrams/AbstractDiagramImporter.java

@@ -0,0 +1,19 @@
+package com.structurizr.importer.diagrams;
+
+import com.structurizr.view.View;
+import com.structurizr.view.ViewSet;
+
+public abstract class AbstractDiagramImporter {
+
+    protected static final String CONTENT_TYPE_IMAGE_PNG = "image/png";
+
+    protected String getViewOrViewSetProperty(View view, String name) {
+        ViewSet views = view.getViewSet();
+
+        return
+                view.getProperties().getOrDefault(name,
+                        views.getConfiguration().getProperties().get(name)
+                );
+    }
+
+}

src/main/java/com/structurizr/importer/diagrams/kroki/KrokiEncoder.java

@@ -0,0 +1,30 @@
+package com.structurizr.importer.diagrams.kroki;
+
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.util.Base64;
+import java.util.zip.Deflater;
+
+/**
+ * See https://docs.kroki.io/kroki/setup/encode-diagram/#java
+ */
+class KrokiEncoder {
+
+    public String encode(String decoded) throws IOException {
+        byte[] bytes = Base64.getUrlEncoder().encode(compress(decoded.getBytes()));
+        return new String(bytes, StandardCharsets.UTF_8);
+    }
+
+    private byte[] compress(byte[] source) throws IOException {
+        Deflater deflater = new Deflater(Deflater.BEST_COMPRESSION);
+        deflater.setInput(source);
+        deflater.finish();
+
+        byte[] buffer = new byte[2048];
+        int compressedLength = deflater.deflate(buffer);
+        byte[] result = new byte[compressedLength];
+        System.arraycopy(buffer, 0, result, 0, compressedLength);
+        return result;
+    }
+
+}

src/main/java/com/structurizr/importer/diagrams/kroki/KrokiImporter.java

@@ -0,0 +1,35 @@
+package com.structurizr.importer.diagrams.kroki;
+
+import com.structurizr.importer.diagrams.AbstractDiagramImporter;
+import com.structurizr.util.StringUtils;
+import com.structurizr.view.ImageView;
+
+import java.io.File;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+
+public class KrokiImporter extends AbstractDiagramImporter {
+
+    private static final String KROKI_URL_PROPERTY = "kroki.url";
+
+    public void importDiagram(ImageView view, String format, File file) throws Exception {
+        String content = new String(Files.readAllBytes(file.toPath()), StandardCharsets.UTF_8);
+        view.setTitle(file.getName());
+
+        importDiagram(view, format, content);
+    }
+
+    public void importDiagram(ImageView view, String format, String content) throws Exception {
+        String krokiServer = getViewOrViewSetProperty(view, KROKI_URL_PROPERTY);
+        if (StringUtils.isNullOrEmpty(krokiServer)) {
+            throw new IllegalArgumentException("Please define a view/viewset property named " + KROKI_URL_PROPERTY + " to specify your Kroki server");
+        }
+
+        String encodedDiagram = new KrokiEncoder().encode(content);
+        String url = String.format("%s/%s/png/%s", krokiServer, format, encodedDiagram);
+
+        view.setContent(url);
+        view.setContentType(CONTENT_TYPE_IMAGE_PNG);
+    }
+
+}

src/main/java/com/structurizr/importer/diagrams/mermaid/MermaidEncoder.java

@@ -0,0 +1,18 @@
+package com.structurizr.importer.diagrams.mermaid;
+
+import java.nio.charset.StandardCharsets;
+import java.util.Base64;
+
+/**
+ *  Encodes a Mermaid diagram definition to base64 format, for use with image URLs, etc.
+ */
+public class MermaidEncoder {
+
+    private static final String TEMPLATE = "{ \"code\":\"%s\", \"mermaid\":{\"theme\":\"default\"}}";
+
+    public String encode(String mermaidDefinition) {
+        String s = String.format(TEMPLATE, mermaidDefinition.replaceAll("\n", "\\\\n").replaceAll("\"", "\\\\\""));
+        return Base64.getEncoder().encodeToString(s.getBytes(StandardCharsets.UTF_8));
+    }
+
+}

src/main/java/com/structurizr/importer/diagrams/mermaid/MermaidImporter.java

@@ -0,0 +1,34 @@
+package com.structurizr.importer.diagrams.mermaid;
+
+import com.structurizr.importer.diagrams.AbstractDiagramImporter;
+import com.structurizr.util.StringUtils;
+import com.structurizr.view.ImageView;
+
+import java.io.File;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+
+public class MermaidImporter extends AbstractDiagramImporter {
+
+    private static final String MERMAID_URL_PROPERTY = "mermaid.url";
+
+    public void importDiagram(ImageView view, File file) throws Exception {
+        String content = new String(Files.readAllBytes(file.toPath()), StandardCharsets.UTF_8);
+        view.setTitle(file.getName());
+
+        importDiagram(view, content);
+    }
+
+    public void importDiagram(ImageView view, String content) {
+        String mermaidServer = getViewOrViewSetProperty(view, MERMAID_URL_PROPERTY);
+        if (StringUtils.isNullOrEmpty(mermaidServer)) {
+            throw new IllegalArgumentException("Please define a view/viewset property named " + MERMAID_URL_PROPERTY + " to specify your Mermaid server");
+        }
+
+        String encodedMermaid = new MermaidEncoder().encode(content);
+        String url = String.format("%s/img/%s", mermaidServer, encodedMermaid);
+        view.setContent(url);
+        view.setContentType(CONTENT_TYPE_IMAGE_PNG);
+    }
+
+}

src/main/java/com/structurizr/importer/diagrams/plantuml/PlantUMLEncoder.java

@@ -0,0 +1,73 @@
+package com.structurizr.importer.diagrams.plantuml;
+
+import java.io.ByteArrayOutputStream;
+import java.nio.charset.StandardCharsets;
+import java.util.zip.Deflater;
+import java.util.zip.DeflaterOutputStream;
+
+/**
+ *  A Java implementation of http://plantuml.com/code-javascript-synchronous
+ *  that uses Java's built-in Deflate algorithm.
+ */
+class PlantUMLEncoder {
+
+    String encode(String plantUMLDefinition) throws Exception {
+        ByteArrayOutputStream baos = new ByteArrayOutputStream();
+        Deflater deflater = new Deflater(Deflater.BEST_COMPRESSION, true);
+
+        DeflaterOutputStream dos = new DeflaterOutputStream(baos, deflater, true);
+        dos.write(plantUMLDefinition.getBytes(StandardCharsets.UTF_8));
+        dos.finish();
+
+        return encode(baos.toByteArray());
+    }
+
+    private String encode(byte[] bytes) {
+        StringBuilder buf = new StringBuilder();
+        for (int i = 0; i < bytes.length; i += 3) {
+            int b1 = (bytes[i]) & 0xFF;
+            int b2 = (i + 1 < bytes.length ? bytes[i + 1] : (byte)0) & 0xFF;
+            int b3 = (i + 2 < bytes.length ? bytes[i + 2] : (byte)0) & 0xFF;
+
+            append3bytes(buf, b1, b2, b3);
+        }
+
+        return buf.toString();
+    }
+
+    private char encode6bit(byte b) {
+        if (b < 10) {
+            return (char) ('0' + b);
+        }
+        b -= 10;
+        if (b < 26) {
+            return (char) ('A' + b);
+        }
+        b -= 26;
+        if (b < 26) {
+            return (char) ('a' + b);
+        }
+        b -= 26;
+        if (b == 0) {
+            return '-';
+        }
+        if (b == 1) {
+            return '_';
+        }
+
+        return '?';
+    }
+
+    private void append3bytes(StringBuilder buf, int b1, int b2, int b3) {
+        int c1 = b1 >> 2;
+        int c2 = (b1 & 0x3) << 4 | b2 >> 4;
+        int c3 = (b2 & 0xF) << 2 | b3 >> 6;
+        int c4 = b3 & 0x3F;
+
+        buf.append(encode6bit((byte)(c1 & 0x3F)));
+        buf.append(encode6bit((byte)(c2 & 0x3F)));
+        buf.append(encode6bit((byte)(c3 & 0x3F)));
+        buf.append(encode6bit((byte)(c4 & 0x3F)));
+    }
+
+}

src/main/java/com/structurizr/importer/diagrams/plantuml/PlantUMLImporter.java

@@ -0,0 +1,44 @@
+package com.structurizr.importer.diagrams.plantuml;
+
+import com.structurizr.importer.diagrams.AbstractDiagramImporter;
+import com.structurizr.util.StringUtils;
+import com.structurizr.view.ImageView;
+
+import java.io.File;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+
+public class PlantUMLImporter extends AbstractDiagramImporter {
+
+    private static final String PLANTUML_URL_PROPERTY = "plantuml.url";
+    private static final String TITLE_STRING = "title ";
+    private static final String NEWLINE = "\n";
+
+    public void importDiagram(ImageView view, File file) throws Exception {
+        String content = new String(Files.readAllBytes(file.toPath()), StandardCharsets.UTF_8);
+        view.setTitle(file.getName());
+
+        importDiagram(view, content);
+    }
+
+    public void importDiagram(ImageView view, String content) throws Exception {
+        String plantUMLServer = getViewOrViewSetProperty(view, PLANTUML_URL_PROPERTY);
+        if (StringUtils.isNullOrEmpty(plantUMLServer)) {
+            throw new IllegalArgumentException("Please define a view/viewset property named " + PLANTUML_URL_PROPERTY + " to specify your PlantUML server");
+        }
+
+        String encodedPlantUML = new PlantUMLEncoder().encode(content);
+        String url = String.format("%s/png/%s", plantUMLServer, encodedPlantUML);
+        view.setContent(url);
+        view.setContentType(CONTENT_TYPE_IMAGE_PNG);
+
+        String[] lines = content.split(NEWLINE);
+        for (String line : lines) {
+            if (line.startsWith(TITLE_STRING)) {
+                String title = line.substring(TITLE_STRING.length());
+                view.setTitle(title);
+            }
+        }
+    }
+
+}

src/main/java/com/structurizr/documentation/importer/AdrToolsDecisionImporter.java renamed to src/main/java/com/structurizr/importer/documentation/AdrToolsDecisionImporter.java

@@ -1,4 +1,4 @@
-package com.structurizr.documentation.importer;
+package com.structurizr.importer.documentation;
 
 import com.structurizr.documentation.Decision;
 import com.structurizr.documentation.Documentable;
@@ -97,7 +97,7 @@ public void importDocumentation(Documentable documentable, File path) {
         }
 
         try {
-            Map<String,Decision> decisionsById = new LinkedHashMap<>();
+            Map<String, Decision> decisionsById = new LinkedHashMap<>();
 
             File[] markdownFiles = path.listFiles((dir, name) -> name.endsWith(".md"));
             if (markdownFiles != null) {

src/main/java/com/structurizr/documentation/importer/DefaultDocumentationImporter.java renamed to src/main/java/com/structurizr/importer/documentation/DefaultDocumentationImporter.java

@@ -1,16 +1,13 @@
-package com.structurizr.documentation.importer;
+package com.structurizr.importer.documentation;
 
 import com.structurizr.documentation.Documentable;
 import com.structurizr.documentation.Format;
 import com.structurizr.documentation.Section;
-import com.structurizr.documentation.util.FormatFinder;
 
 import java.io.File;
 import java.nio.charset.StandardCharsets;
 import java.nio.file.Files;
-import java.util.ArrayList;
 import java.util.Arrays;
-import java.util.List;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 

src/main/java/com/structurizr/documentation/importer/DefaultImageImporter.java renamed to src/main/java/com/structurizr/importer/documentation/DefaultImageImporter.java

@@ -1,4 +1,4 @@
-package com.structurizr.documentation.importer;
+package com.structurizr.importer.documentation;
 
 import com.structurizr.documentation.Documentable;
 import com.structurizr.documentation.Image;

src/main/java/com/structurizr/documentation/importer/DocumentationImportException.java renamed to src/main/java/com/structurizr/importer/documentation/DocumentationImportException.java

@@ -1,4 +1,4 @@
-package com.structurizr.documentation.importer;
+package com.structurizr.importer.documentation;
 
 public class DocumentationImportException extends RuntimeException {
 

src/main/java/com/structurizr/documentation/importer/DocumentationImporter.java renamed to src/main/java/com/structurizr/importer/documentation/DocumentationImporter.java

@@ -1,4 +1,4 @@
-package com.structurizr.documentation.importer;
+package com.structurizr.importer.documentation;
 
 import com.structurizr.documentation.Documentable;
 

src/main/java/com/structurizr/documentation/util/FormatFinder.java renamed to src/main/java/com/structurizr/importer/documentation/FormatFinder.java

@@ -1,4 +1,4 @@
-package com.structurizr.documentation.util;
+package com.structurizr.importer.documentation;
 
 import com.structurizr.documentation.Format;
 
@@ -9,9 +9,9 @@
 
 public class FormatFinder {
 
-    private static Set<String> MARKDOWN_EXTENSIONS = new HashSet<>(Arrays.asList(".md", ".markdown", ".text"));
+    private static final Set<String> MARKDOWN_EXTENSIONS = new HashSet<>(Arrays.asList(".md", ".markdown", ".text"));
 
-    private static Set<String> ASCIIDOC_EXTENSIONS = new HashSet<>(Arrays.asList(".asciidoc", ".adoc", ".asc"));
+    private static final Set<String> ASCIIDOC_EXTENSIONS = new HashSet<>(Arrays.asList(".asciidoc", ".adoc", ".asc"));
 
     public static boolean isMarkdownOrAsciiDoc(File file) {
         String extension = file.getName().substring(file.getName().lastIndexOf("."));

src/main/java/com/structurizr/documentation/importer/RecursiveDefaultDocumentationImporter.java renamed to src/main/java/com/structurizr/importer/documentation/RecursiveDefaultDocumentationImporter.java

@@ -1,4 +1,4 @@
-package com.structurizr.documentation.importer;
+package com.structurizr.importer.documentation;
 
 import com.structurizr.documentation.Documentable;
 import com.structurizr.documentation.Section;

src/test/diagrams/kroki/diagram.dot

@@ -0,0 +1 @@
+digraph G {Hello->World}

src/test/diagrams/mermaid/class.mmd

@@ -0,0 +1,21 @@
+classDiagram
+    Animal <|-- Duck
+    Animal <|-- Fish
+    Animal <|-- Zebra
+    Animal : +int age
+    Animal : +String gender
+    Animal: +isMammal()
+    Animal: +mate()
+    class Duck{
+      +String beakColor
+      +swim()
+      +quack()
+    }
+    class Fish{
+      -int sizeInFeet
+      -canEat()
+    }
+    class Zebra{
+      +bool is_wild
+      +run()
+    }

src/test/diagrams/mermaid/flowchart.mmd

@@ -0,0 +1,2 @@
+flowchart TD
+    Start --> Stop

src/test/diagrams/plantuml/with-title.puml

@@ -0,0 +1,4 @@
+@startuml
+title Sequence diagram example
+Bob -> Alice : hello
+@enduml

src/test/diagrams/plantuml/without-title.puml

@@ -0,0 +1,3 @@
+@startuml
+Bob -> Alice : hello
+@enduml