Elemento place manager

hal · Mar 1, 2024 · 6c29ef9 · 6c29ef9
1 parent a192715
commit 6c29ef9
Show file tree

Hide file tree

Showing 20 changed files with 1,203 additions and 0 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,18 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Added
+
+#### Router
+
+Elemento now contains a very basic place manager. The place manager is minimal invasive and built around a few simple concepts:
+
+- `Route`: Annotation that can be used to decorate pages. An annotation processor collects all classes annotated with `@Route` and generates an implementation of `Routes`. 
+- `Routes`: Provides a collection of places and their corresponding pages.
+- `Place`: Class that represents a place in an application. A place is identified by a route, and can have an optional title and a custom root element.
+- `Page`: Interface that represents a collection of HTML elements.
+- `PlaceManager`: Class responsible for managing the routing and navigation within an application.
+
 ## [1.2.13] - 2024-02-06
 
 ### Added

diff --git a/bom/pom.xml b/bom/pom.xml
@@ -54,6 +54,16 @@
                 <artifactId>elemento-mathml</artifactId>
                 <version>${project.version}</version>
             </dependency>
+            <dependency>
+                <groupId>${project.groupId}</groupId>
+                <artifactId>elemento-router</artifactId>
+                <version>${project.version}</version>
+            </dependency>
+            <dependency>
+                <groupId>${project.groupId}</groupId>
+                <artifactId>elemento-router-processor</artifactId>
+                <version>${project.version}</version>
+            </dependency>
             <dependency>
                 <groupId>${project.groupId}</groupId>
                 <artifactId>elemento-svg</artifactId>

diff --git a/pom.xml b/pom.xml
@@ -110,6 +110,7 @@
         <version.keepachangelog>2.1.1</version.keepachangelog>
         <version.license.plugin>4.3</version.license.plugin>
         <version.nexus.staging.plugin>1.6.13</version.nexus.staging.plugin>
+        <version.shade.plugin>3.5.2</version.shade.plugin>
 
         <!-- Build related -->
         <encoding>UTF-8</encoding>
@@ -128,6 +129,8 @@
         <module>code-parent</module>
         <module>core</module>
         <module>mathml</module>
+        <module>router</module>
+        <module>router-processor</module>
         <module>svg</module>
     </modules>
 
@@ -230,6 +233,11 @@
                         </rules>
                     </configuration>
                 </plugin>
+                <plugin>
+                    <groupId>org.apache.maven.plugins</groupId>
+                    <artifactId>maven-shade-plugin</artifactId>
+                    <version>${version.shade.plugin}</version>
+                </plugin>
             </plugins>
         </pluginManagement>
 

diff --git a/router-processor/pom.xml b/router-processor/pom.xml
@@ -0,0 +1,104 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+     Copyright 2023 Red Hat
+
+     Licensed under the Apache License, Version 2.0 (the "License");
+     you may not use this file except in compliance with the License.
+     You may obtain a copy of the License at
+
+         https://www.apache.org/licenses/LICENSE-2.0
+
+     Unless required by applicable law or agreed to in writing, software
+     distributed under the License is distributed on an "AS IS" BASIS,
+     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+     See the License for the specific language governing permissions and
+     limitations under the License.
+
+-->
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>org.jboss.elemento</groupId>
+        <artifactId>elemento-code-parent</artifactId>
+        <version>1.2.14-SNAPSHOT</version>
+        <relativePath>../code-parent/pom.xml</relativePath>
+    </parent>
+
+    <artifactId>elemento-router-processor</artifactId>
+    <version>1.2.14-SNAPSHOT</version>
+    <packaging>jar</packaging>
+    <name>Elemento Router Processor</name>
+    <description>Elemento router annotation processor</description>
+
+    <properties>
+        <version.auto.common>1.2.2</version.auto.common>
+        <version.auto.service>1.1.1</version.auto.service>
+        <version.freemarker>2.3.32</version.freemarker>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>${project.groupId}</groupId>
+            <artifactId>elemento-router</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>com.google.auto</groupId>
+            <artifactId>auto-common</artifactId>
+            <version>${version.auto.common}</version>
+        </dependency>
+        <dependency>
+            <groupId>com.google.auto.service</groupId>
+            <artifactId>auto-service-annotations</artifactId>
+            <version>${version.auto.service}</version>
+        </dependency>
+        <dependency>
+            <groupId>com.google.auto.service</groupId>
+            <artifactId>auto-service</artifactId>
+            <version>${version.auto.service}</version>
+            <scope>provided</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.freemarker</groupId>
+            <artifactId>freemarker</artifactId>
+            <version>${version.freemarker}</version>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-shade-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <phase>package</phase>
+                        <goals>
+                            <goal>shade</goal>
+                        </goals>
+                        <configuration>
+                            <minimizeJar>true</minimizeJar>
+                            <artifactSet>
+                                <excludes>
+                                    <exclude>${project.groupId}:core</exclude>
+                                    <exclude>${project.groupId}:router</exclude>
+                                    <exclude>com.google.elemental2:*</exclude>
+                                    <exclude>com.google.jsinterop:*</exclude>
+                                    <exclude>org.gwtproject.event:*</exclude>
+                                    <exclude>org.gwtproject.safehtml:*</exclude>
+                                    <exclude>org.junit.jupiter:*</exclude>
+                                    <exclude>org.junit.platform:*</exclude>
+                                    <exclude>org.opentest4j:*</exclude>
+                                    <exclude>org.apiguardian:*</exclude>
+                                </excludes>
+                            </artifactSet>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    </build>
+</project>
diff --git a/router-processor/src/main/java/org/jboss/elemento/router/processor/CodeGenerator.java b/router-processor/src/main/java/org/jboss/elemento/router/processor/CodeGenerator.java
@@ -0,0 +1,71 @@
+/*
+ *  Copyright 2023 Red Hat
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+package org.jboss.elemento.router.processor;
+
+import java.io.BufferedWriter;
+import java.io.IOException;
+import java.io.StringWriter;
+import java.util.Map;
+
+import freemarker.template.Configuration;
+import freemarker.template.Template;
+import freemarker.template.TemplateException;
+import freemarker.template.Version;
+
+/**
+ * A code generator which generates code / resources from freemarker templates.
+ *
+ * @author Harald Pehl
+ */
+class CodeGenerator {
+
+    public static final Version VERSION = new Version(2, 3, 32);
+    private final Configuration config;
+
+    CodeGenerator(Class<?> resourceLoaderClass, String templates) {
+        config = new Configuration(Configuration.VERSION_2_3_32);
+        config.setDefaultEncoding("UTF-8");
+        config.setClassForTemplateLoading(resourceLoaderClass, templates);
+    }
+
+    /**
+     * Generates the code using the specified context and freemarker template. Wraps any kind of error inside a
+     * {@code GenerationException}.
+     *
+     * @param template the relative template name
+     * @param context a supplier function to create the templates' context
+     * @return the generated content
+     */
+    StringBuffer generate(String template, Map<String, Object> context) {
+        final StringWriter sw = new StringWriter();
+        final BufferedWriter bw = new BufferedWriter(sw);
+        try {
+            final Template t = config.getTemplate(template);
+            t.process(context, bw);
+        } catch (IOException | TemplateException e) {
+            throw new GenerationException("Error generating template " + template + ": " + e.getMessage(), e);
+        } finally {
+            try {
+                bw.close();
+                sw.close();
+            } catch (IOException ioe) {
+                // noinspection ThrowFromFinallyBlock
+                throw new GenerationException("Error generating template " + template + ": " + ioe.getMessage(), ioe);
+            }
+        }
+        return sw.getBuffer();
+    }
+}
diff --git a/router-processor/src/main/java/org/jboss/elemento/router/processor/GenerationException.java b/router-processor/src/main/java/org/jboss/elemento/router/processor/GenerationException.java
@@ -0,0 +1,26 @@
+/*
+ *  Copyright 2023 Red Hat
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+package org.jboss.elemento.router.processor;
+
+/**
+ * @author Harald Pehl
+ */
+class GenerationException extends RuntimeException {
+
+    GenerationException(final String message, Exception e) {
+        super(message, e);
+    }
+}
diff --git a/router-processor/src/main/java/org/jboss/elemento/router/processor/ProcessingException.java b/router-processor/src/main/java/org/jboss/elemento/router/processor/ProcessingException.java
@@ -0,0 +1,36 @@
+/*
+ *  Copyright 2023 Red Hat
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+package org.jboss.elemento.router.processor;
+
+import javax.lang.model.element.Element;
+
+class ProcessingException extends RuntimeException {
+
+    private final Element element;
+
+    ProcessingException(final String msg) {
+        this(null, msg);
+    }
+
+    ProcessingException(final Element element, final String msg) {
+        super(msg);
+        this.element = element;
+    }
+
+    Element getElement() {
+        return element;
+    }
+}
diff --git a/router-processor/src/main/java/org/jboss/elemento/router/processor/RouteInfo.java b/router-processor/src/main/java/org/jboss/elemento/router/processor/RouteInfo.java
@@ -0,0 +1,48 @@
+/*
+ *  Copyright 2023 Red Hat
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+package org.jboss.elemento.router.processor;
+
+@SuppressWarnings("unused")
+public class RouteInfo {
+
+    private final String route;
+    private final String title;
+    private final String selector;
+    private final String pageClass;
+
+    public RouteInfo(String route, String title, String selector, String pageClass) {
+        this.route = route;
+        this.title = title;
+        this.selector = selector;
+        this.pageClass = pageClass;
+    }
+
+    public String getRoute() {
+        return route;
+    }
+
+    public String getTitle() {
+        return title;
+    }
+
+    public String getSelector() {
+        return selector;
+    }
+
+    public String getPageClass() {
+        return pageClass;
+    }
+}