structurizr-dsl: Adds archetype support for custom elements.

simonbrowndotje · simonbrowndotje · commit 1bc95cc9d6f1 · 2025-04-08T17:03:30.000+01:00
diff --git a/changelog.md b/changelog.md
@@ -3,6 +3,7 @@
 ## v4.0.1 (unreleased)
 
 - structurizr-dsl: Allows archetypes to be used via workspace extension.
+- structurizr-dsl: Adds archetype support for custom elements.
 - structurizr-dsl: Fixes https://github.com/structurizr/java/issues/392 (SVG not supported in base 64 encoding not mentioned in documentation).
 - structurizr-export: Adds support for rank and node separation to the StructurizrPlantUMLExporter.
 
diff --git a/structurizr-dsl/src/main/java/com/structurizr/dsl/Archetype.java b/structurizr-dsl/src/main/java/com/structurizr/dsl/Archetype.java
@@ -11,6 +11,7 @@ final class Archetype implements PropertyHolder, PerspectivesHolder {
 
     private final String name;
     private final String type;
+    private String metadata = "";
     private String description = "";
     private String technology = "";
     private final Set<String> tags = new LinkedHashSet<>();
@@ -35,6 +36,14 @@ String getType() {
         return type;
     }
 
+    String getMetadata() {
+        return metadata;
+    }
+
+    void setMetadata(String metadata) {
+        this.metadata = metadata;
+    }
+
     String getDescription() {
         return description;
     }
diff --git a/structurizr-dsl/src/main/java/com/structurizr/dsl/ArchetypeParser.java b/structurizr-dsl/src/main/java/com/structurizr/dsl/ArchetypeParser.java
@@ -31,6 +31,20 @@ void parseTags(ArchetypeDslContext context, Tokens tokens) {
         }
     }
 
+    void parseMetadata(ArchetypeDslContext context, Tokens tokens) {
+        // metadata <metadata>
+        if (tokens.hasMoreThan(VALUE_INDEX)) {
+            throw new RuntimeException("Too many tokens, expected: metadata <metadata>");
+        }
+
+        if (!tokens.includes(NAME_INDEX)) {
+            throw new RuntimeException("Expected: metadata <metadata>");
+        }
+
+        String metadata = tokens.get(VALUE_INDEX);
+        context.getArchetype().setMetadata(metadata);
+    }
+
     void parseDescription(ArchetypeDslContext context, Tokens tokens) {
         // description <description>
         if (tokens.hasMoreThan(VALUE_INDEX)) {
diff --git a/structurizr-dsl/src/main/java/com/structurizr/dsl/CustomElementArchetypeDslContext.java b/structurizr-dsl/src/main/java/com/structurizr/dsl/CustomElementArchetypeDslContext.java
@@ -0,0 +1,21 @@
+package com.structurizr.dsl;
+
+final class CustomElementArchetypeDslContext extends ElementArchetypeDslContext {
+
+    CustomElementArchetypeDslContext(Archetype archetype) {
+        super(archetype);
+    }
+
+    @Override
+    protected String[] getPermittedTokens() {
+        return new String[] {
+            StructurizrDslTokens.METADATA_TOKEN,
+            StructurizrDslTokens.DESCRIPTION_TOKEN,
+            StructurizrDslTokens.TAG_TOKEN,
+            StructurizrDslTokens.TAGS_TOKEN,
+            StructurizrDslTokens.PROPERTIES_TOKEN,
+            StructurizrDslTokens.PERSPECTIVES_TOKEN
+        };
+    }
+
+}
diff --git a/structurizr-dsl/src/main/java/com/structurizr/dsl/CustomElementParser.java b/structurizr-dsl/src/main/java/com/structurizr/dsl/CustomElementParser.java
@@ -13,7 +13,7 @@ final class CustomElementParser extends AbstractParser {
     private final static int DESCRIPTION_INDEX = 3;
     private final static int TAGS_INDEX = 4;
 
-    CustomElement parse(ModelDslContext context, Tokens tokens) {
+    CustomElement parse(ModelDslContext context, Tokens tokens, Archetype archetype) {
         // element <name> [metadata] [description] [tags]
 
         if (tokens.hasMoreThan(TAGS_INDEX)) {
@@ -26,22 +26,23 @@ CustomElement parse(ModelDslContext context, Tokens tokens) {
 
         String name = tokens.get(NAME_INDEX);
 
-        String metadata = "";
+        String metadata = archetype.getMetadata();
         if (tokens.includes(METADATA_INDEX)) {
             metadata = tokens.get(METADATA_INDEX);
         }
 
-        String description = "";
+        String description = archetype.getDescription();
         if (tokens.includes(DESCRIPTION_INDEX)) {
             description = tokens.get(DESCRIPTION_INDEX);
         }
 
         CustomElement customElement = context.getWorkspace().getModel().addCustomElement(name, metadata, description);
 
+        String[] tags = archetype.getTags().toArray(new String[0]);
         if (tokens.includes(TAGS_INDEX)) {
-            String tags = tokens.get(TAGS_INDEX);
-            customElement.addTags(tags.split(","));
+            tags = tokens.get(TAGS_INDEX).split(",");
         }
+        customElement.addTags(tags);
 
         if (context.hasGroup()) {
             customElement.setGroup(context.getGroup().getName());
diff --git a/structurizr-dsl/src/main/java/com/structurizr/dsl/StructurizrDslParser.java b/structurizr-dsl/src/main/java/com/structurizr/dsl/StructurizrDslParser.java
@@ -49,6 +49,7 @@ public final class StructurizrDslParser extends StructurizrDslTokens {
 
     private Map<String,Map<String,Archetype>> archetypes = Map.of(
             StructurizrDslTokens.GROUP_TOKEN, new HashMap<>(),
+            StructurizrDslTokens.CUSTOM_ELEMENT_TOKEN, new HashMap<>(),
             StructurizrDslTokens.PERSON_TOKEN, new HashMap<>(),
             StructurizrDslTokens.SOFTWARE_SYSTEM_TOKEN, new HashMap<>(),
             StructurizrDslTokens.CONTAINER_TOKEN, new HashMap<>(),
@@ -421,8 +422,9 @@ void parse(List<String> lines, File dslFile, boolean fragment, boolean includeIn
                             startContext(new RelationshipsDslContext(getContext(), relationships));
                         }
 
-                    } else if (CUSTOM_ELEMENT_TOKEN.equalsIgnoreCase(firstToken) && (inContext(ModelDslContext.class))) {
-                        CustomElement customElement = new CustomElementParser().parse(getContext(ModelDslContext.class), tokens.withoutContextStartToken());
+                    } else if (isElementKeywordOrArchetype(firstToken, CUSTOM_ELEMENT_TOKEN) && (inContext(ModelDslContext.class))) {
+                        Archetype archetype = getArchetype(CUSTOM_ELEMENT_TOKEN, firstToken);
+                        CustomElement customElement = new CustomElementParser().parse(getContext(ModelDslContext.class), tokens.withoutContextStartToken(), archetype);
 
                         if (shouldStartContext(tokens)) {
                             startContext(new CustomElementDslContext(customElement));
@@ -673,6 +675,15 @@ void parse(List<String> lines, File dslFile, boolean fragment, boolean includeIn
                         extendArchetype(archetype, firstToken);
                         addArchetype(archetype);
 
+                    } else if (isElementKeywordOrArchetype(firstToken, CUSTOM_ELEMENT_TOKEN) && inContext(ArchetypesDslContext.class)) {
+                        Archetype archetype = new Archetype(identifier, CUSTOM_ELEMENT_TOKEN);
+                        extendArchetype(archetype, firstToken);
+                        addArchetype(archetype);
+
+                        if (shouldStartContext(tokens)) {
+                            startContext(new CustomElementArchetypeDslContext(archetype));
+                        }
+
                     } else if (isElementKeywordOrArchetype(firstToken, PERSON_TOKEN) && inContext(ArchetypesDslContext.class)) {
                         Archetype archetype = new Archetype(identifier, PERSON_TOKEN);
                         extendArchetype(archetype, firstToken);
@@ -737,6 +748,9 @@ void parse(List<String> lines, File dslFile, boolean fragment, boolean includeIn
                             startContext(new RelationshipArchetypeDslContext(archetype));
                         }
 
+                    } else if (METADATA_TOKEN.equalsIgnoreCase(firstToken) && inContext(CustomElementArchetypeDslContext.class)) {
+                        new ArchetypeParser().parseMetadata(getContext(ArchetypeDslContext.class), tokens);
+
                     } else if (DESCRIPTION_TOKEN.equalsIgnoreCase(firstToken) && inContext(ArchetypeDslContext.class)) {
                         new ArchetypeParser().parseDescription(getContext(ArchetypeDslContext.class), tokens);
 
@@ -1384,6 +1398,7 @@ private void extendArchetype(Archetype archetype, String archetypeName) {
         archetypeName = archetypeName.toLowerCase();
         Archetype parentArchetype = getArchetype(archetype.getType(), archetypeName);
 
+        archetype.setMetadata(parentArchetype.getMetadata());
         archetype.setDescription(parentArchetype.getDescription());
         archetype.setTechnology(parentArchetype.getTechnology());
         archetype.addTags(parentArchetype.getTags().toArray(new String[0]));
diff --git a/structurizr-dsl/src/main/java/com/structurizr/dsl/StructurizrDslTokens.java b/structurizr-dsl/src/main/java/com/structurizr/dsl/StructurizrDslTokens.java
@@ -15,6 +15,7 @@ class StructurizrDslTokens {
     static final String COMPONENT_TOKEN = "component";
     static final String GROUP_TOKEN = "group";
     static final String NAME_TOKEN = "name";
+    static final String METADATA_TOKEN = "metadata";
     static final String DESCRIPTION_TOKEN = "description";
     static final String TECHNOLOGY_TOKEN = "technology";
     static final String INSTANCES_TOKEN = "instances";
diff --git a/structurizr-dsl/src/test/java/com/structurizr/dsl/CustomElementParserTests.java b/structurizr-dsl/src/test/java/com/structurizr/dsl/CustomElementParserTests.java
@@ -8,11 +8,12 @@
 class CustomElementParserTests extends AbstractTests {
 
     private CustomElementParser parser = new CustomElementParser();
+    private Archetype archetype = new Archetype("name", "type");
 
     @Test
     void test_parse_ThrowsAnException_WhenThereAreTooManyTokens() {
         try {
-            parser.parse(context(), tokens("element", "name", "metadata", "description", "tags", "extra"));
+            parser.parse(context(), tokens("element", "name", "metadata", "description", "tags", "extra"), archetype);
             fail();
         } catch (Exception e) {
             assertEquals("Too many tokens, expected: element <name> [metadata] [description] [tags]", e.getMessage());
@@ -22,7 +23,7 @@ void test_parse_ThrowsAnException_WhenThereAreTooManyTokens() {
     @Test
     void test_parse_ThrowsAnException_WhenTheNameIsNotSpecified() {
         try {
-            parser.parse(context(), tokens("element"));
+            parser.parse(context(), tokens("element"), archetype);
             fail();
         } catch (Exception e) {
             assertEquals("Expected: element <name> [metadata] [description] [tags]", e.getMessage());
@@ -31,7 +32,7 @@ void test_parse_ThrowsAnException_WhenTheNameIsNotSpecified() {
 
     @Test
     void test_parse_CreatesACustomElement() {
-        parser.parse(context(), tokens("element", "Name"));
+        parser.parse(context(), tokens("element", "Name"), archetype);
 
         assertEquals(1, model.getElements().size());
         CustomElement element = model.getCustomElementWithName("Name");
@@ -42,7 +43,7 @@ void test_parse_CreatesACustomElement() {
 
     @Test
     void test_parse_CreatesACustomElementWithMetadata() {
-        parser.parse(context(), tokens("element", "Name", "Box"));
+        parser.parse(context(), tokens("element", "Name", "Box"), archetype);
 
         assertEquals(1, model.getElements().size());
         CustomElement element = model.getCustomElementWithName("Name");
@@ -54,7 +55,7 @@ void test_parse_CreatesACustomElementWithMetadata() {
 
     @Test
     void test_parse_CreatesACustomElementWithMetadataAndDescription() {
-        parser.parse(context(), tokens("element", "Name", "Box", "Description"));
+        parser.parse(context(), tokens("element", "Name", "Box", "Description"), archetype);
 
         assertEquals(1, model.getElements().size());
         CustomElement element = model.getCustomElementWithName("Name");
@@ -66,7 +67,7 @@ void test_parse_CreatesACustomElementWithMetadataAndDescription() {
 
     @Test
     void test_parse_CreatesACustomElementWithMetadataAndDescriptionAndTags() {
-        parser.parse(context(), tokens("element", "Name", "Box", "Description", "Tag 1, Tag 2"));
+        parser.parse(context(), tokens("element", "Name", "Box", "Description", "Tag 1, Tag 2"), archetype);
 
         assertEquals(1, model.getElements().size());
         CustomElement element = model.getCustomElementWithName("Name");
diff --git a/structurizr-dsl/src/test/java/com/structurizr/dsl/DslTests.java b/structurizr-dsl/src/test/java/com/structurizr/dsl/DslTests.java
@@ -1474,6 +1474,18 @@ void test_archetypes() throws Exception {
         assertEquals("HTTPS", relationship.getTechnology());
     }
 
+    @Test
+    void test_archetypesForCustomElements() throws Exception {
+        File parentDslFile = new File("src/test/resources/dsl/archetypes-for-custom-elements.dsl");
+        StructurizrDslParser parser = new StructurizrDslParser();
+        parser.parse(parentDslFile);
+        Workspace workspace = parser.getWorkspace();
+
+        CustomElement b = workspace.getModel().getCustomElementWithName("B");
+        assertEquals("Hardware System", b.getMetadata());
+        assertTrue(b.getTagsAsSet().contains("Hardware System"));
+    }
+
     @Test
     void test_archetypesForDefaults() throws Exception {
         File parentDslFile = new File("src/test/resources/dsl/archetypes-for-defaults.dsl");
diff --git a/structurizr-dsl/src/test/resources/dsl/archetypes-for-custom-elements.dsl b/structurizr-dsl/src/test/resources/dsl/archetypes-for-custom-elements.dsl
@@ -0,0 +1,17 @@
+workspace {
+
+    model {
+        archetypes {
+            hardwareSystem = element {
+                metadata "Hardware System"
+                tag "Hardware System"
+            }
+        }
+
+        a = softwareSystem "A"
+        b = hardwareSystem "B"
+
+        a -> b "Gets data from"
+    }
+
+}
