108 maven plugin

.github/workflows/ci.yaml

@@ -48,6 +48,9 @@ jobs:
         run: ./mvnw install -e --ntp -B
       - name: Test JPMS
         run: ./mvnw clean verify -pl it/java8 -P it-jpms -e --ntp -B
+      - name: Test Maven 3.2.5 compatibility
+        working-directory: maven-plugin/it
+        run: ./mvnw stype:gen -e -B
       - name: Javadoc
         run: ./mvnw -P release javadoc:javadoc --ntp -B
       - name: Upload generated sources
@@ -93,6 +96,9 @@ jobs:
           key: build_maven
       - name: Test
         run: ./mvnw verify -pl it/java8 -e --ntp -B
+      - name: Maven Plugin Test
+        working-directory: maven-plugin/it
+        run: ./mvnw stype:gen -e -B
 
   client_test:
     needs: [build_and_test]

README.md

@@ -4,7 +4,7 @@
 [![CI](https://github.com/cuzfrog/sharedtype/actions/workflows/ci.yaml/badge.svg)](https://github.com/cuzfrog/sharedtype/actions/workflows/ci.yaml)
 [![Maven Central](https://img.shields.io/maven-central/v/online.sharedtype/sharedtype?style=social)](https://central.sonatype.com/search?q=g:online.sharedtype++a:sharedtype&smo=true)
 
-# SharedType - Sharing Java Types made easy
+# SharedType - Lightweight Java Type Sharing
 From Java:
 ```java
 @SharedType
@@ -36,13 +36,11 @@ pub struct User {
 ```
 
 ## Features
-* Java8 compatible; Java 9 module (Jigsaw) compatible.
+* Java8+ compatible.
 * Generics support.
 * Compile-time constant support.
-* Client source dependency is only `@SharedType` retained at source code level.
-* SharedType annotation processor has only 1 dependency: [mustache](https://github.com/spullara/mustache.java).
-* Parsing takes milliseconds with `-proc:only`.
-* Intuitive defaults, put `@SharedType` and there you go. Global + class level options.
+* Fast. (Execution takes milliseconds with `-proc:only`.)
+* Simple global + type level configurations.
 
 ## Documentation
 * [User Guide](doc/Usage.md)

annotation/src/main/java/online/sharedtype/SharedType.java

@@ -157,8 +157,7 @@
  * <b>Custom code snippet:</b><br>
  * Clients can provide custom code snippets to be injected into the emitted file.
  * This can be useful when e.g. a 3rd party type is referenced at client code.
- * By default, SharedType will search files "sharedtype-custom-code.ts", "sharedtype-custom-code.rs" respectively on cmd path.
- * File paths can be configured via global properties.
+ * Custom code file paths can be configured via global properties.
  * </p>
  *
  * <br>

doc/Development.md

@@ -14,6 +14,7 @@ Internal types also have javadoc for more information.
     * `java17` uses symlink to reuse types in `java8` then does more type checks, e.g. for Java `record`.
 * `client-test` contains target languages' tests respectively against generated code.
 * `e2e` contains e2e json 2-way serialization and deserialization tests against target languages' http servers.
+* `maven-plugin` contains maven plugin for SharedType annotation, and `maven-plugin/it` contains integration tests for maven plugin.
 
 Domain types are shared among processor and integration tests to reduce maven module count.
 
@@ -83,6 +84,12 @@ Compile specific classes, **along with debug, this is useful for developing a sp
 ./mvnw clean compile -pl it/java17 -DcompileClasses=online/sharedtype/it/java8/TempClass.java
 ```
 
+### Maven Plugin Development
+Debug Maven plugin IT:
+```bash
+mvnd -pl maven-plugin clean install && ./mvne -pl maven-plugin/it sharedtype:gen
+```
+
 ## Coding Style Guide / Keep it simple
 1. since annotation processing is one shot execution, JIT is not likely to optimize the code. So prefer plain loop than long calling stacks like Stream chains.
 2. no adding dependencies without strong justification.

doc/Usage.md

@@ -5,51 +5,38 @@ Menu:
 * [Configurations](#Configurations)
 
 ## Setup
-
 ### Maven
 
-Add sharedtype dependency, the annotation `@SharedType` is only used at compile time on source code:
-```xml
-<dependency>
-    <groupId>online.sharedtype</groupId>
-    <artifactId>sharedtype</artifactId>
-    <version>${sharedtype.version}</version>
-    <scope>provided</scope>
-    <optional>true</optional>
-</dependency>
-```
-
 Add Maven properties:
 ```xml
 <properties>
-    <compilerArg /> <!-- Placeholder -->
-    <sharedtype.version>0.12.1</sharedtype.version>
-    <sharedtype.enabled>false</sharedtype.enabled> <!-- Disable by default so not to participate in every compilation -->
+    <sharedtype.version>0.13.0</sharedtype.version>
 </properties>
 ```
-Setup annotation processing:
+
+Add sharedtype-maven-plugin:
 ```xml
 <plugin>
-    <groupId>org.apache.maven.plugins</groupId>
-    <artifactId>maven-compiler-plugin</artifactId>
-    <configuration>
-        <annotationProcessorPaths>
-            <path>
-                <groupId>online.sharedtype</groupId>
-                <artifactId>sharedtype-ap</artifactId>
-                <version>${sharedtype.version}</version>
-            </path>
-        </annotationProcessorPaths>
-        <showWarnings>true</showWarnings> <!-- Show annotation processing info log -->
-        <compilerArgs>
-            <!-- supplied as properties from cmd -->
-            <arg>${compilerArg}</arg>
-            <arg>-Asharedtype.enabled=${sharedtype.enabled}</arg>
-        </compilerArgs>
-    </configuration>
+    <groupId>online.sharedtype</groupId>
+    <artifactId>sharedtype-maven-plugin</artifactId>
+    <version>${project.version}</version>
 </plugin>
 ```
 
+Add sharedtype dependency:
+```xml
+<dependency>
+    <groupId>online.sharedtype</groupId>
+    <artifactId>sharedtype</artifactId>
+    <version>${sharedtype.version}</version>
+    <scope>provided</scope>
+    <optional>true</optional>
+</dependency>
+```
+
+`sharedtype-maven-plugin` requires Maven 3.2.5+.
+Annotation processing can also be setup and configured via `maven-compiler-plugin`, see [example](../it/pom.xml).
+The advantage of using `sharedtype-maven-plugin` is that no need to execute other annotation processors if there are multiple.
 ## Usage
 
 ### A simple example
@@ -59,8 +46,8 @@ Annotate on a class:
 record User(String name, int age, String email) {}
 ```
 
-Execute annotation processing:
-* maven: `./mvnw compile -DcompilerArg=-proc:only -Dsharedtype.enabled=true`
+Execute:
+* maven: `./mvnw stype:gen` (Why `stype`? Because it's easy to type while explicitly enough to remember.)
 
 By default, below code will be generated:
 ```typescript
@@ -75,25 +62,29 @@ export interface User {
 
 #### Global options
 By default, the file `sharedtype.properties` on current cmd path will be picked up.
-You can customize the path by config `maven-compiler-plugin`:
+You can customize the path:
 ```xml
-<compilerArgs>
-    <arg>-Asharedtype.propsFile=${your.properties.path}</arg>
-</compilerArgs>
+<plugin>
+    <configuration>
+        <propertyFile>${project.basedir}/sharedtype-my-custom.properties</propertyFile>
+    </configuration>
+</plugin>
 ```
 
-Properties can also be passed in as system properties, which will override the properties files, e.g.
-```bash
-./mvnw clean compile -Dsharedtype.typescript.custom-code-path=it/custom-code.ts
-```
-or
-```bash
-MAVEN_OPTS="-Dsharedtype.typescript.custom-code-path=it/custom-code.ts" ./mvnw clean compile
+You can also specify individual properties:
+```xml
+<plugin>
+    <configuration>
+        <properties>
+            <sharedtype.typescript.custom-code-path>${project.basedir}/custom-code.ts</sharedtype.typescript.custom-code-path>
+        </properties>
+    </configuration>
+</plugin>
 ```
-or can use [properties-maven-plugin](https://www.mojohaus.org/properties-maven-plugin/usage.html#set-system-properties) to set system properties for the build.
 
-See [Default Properties](../processor/src/main/resources/sharedtype-default.properties) for details.
+See [Default Properties](../processor/src/main/resources/sharedtype-default.properties) for all property entries.
 
+Execution goal `gen` can be bound to a Maven lifecycle phase.
 #### Per annotation options
 See Javadoc on [@SharedType](../annotation/src/main/java/online/sharedtype/SharedType.java) for details.
 

it/pom.xml

@@ -1,5 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<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">
+<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>online.sharedtype</groupId>
@@ -13,7 +14,7 @@
     <packaging>pom</packaging>
 
     <properties>
-        <compilerArg />
+        <compilerArg/>
         <sharedtype.propsFile>it/sharedtype.properties</sharedtype.propsFile>
         <compileClasses/>
         <excludeClasses/>
@@ -99,39 +100,12 @@
                         <arg>${compilerArg}</arg> <!-- supplied from cmd "-Dsharedtype.compilerArg=-proc:only" -->
                         <arg>-Asharedtype.propsFile=${sharedtype.propsFile}</arg>
                         <arg>-Asharedtype.enabled=true</arg>
+                        <!-- Execute processor: ./mvnw compile -DcompilerArg=-proc:only -Dsharedtype.enabled=true -->
                     </compilerArgs>
                     <includes>${compileClasses}</includes>
                     <excludes>${excludeClasses}</excludes>
                 </configuration>
             </plugin>
-            <plugin>
-                <groupId>org.codehaus.mojo</groupId>
-                <artifactId>properties-maven-plugin</artifactId>
-                <version>1.2.1</version>
-                <executions>
-                    <execution>
-                        <goals>
-                            <goal>set-system-properties</goal>
-                        </goals>
-                        <configuration>
-                            <properties>
-                                <property>
-                                    <name>sharedtype.typescript.custom-code-path</name>
-                                    <value>it/custom-code.ts</value>
-                                </property>
-                                <property>
-                                    <name>sharedtype.go.custom-code-path</name>
-                                    <value>it/custom-code.go</value>
-                                </property>
-                                <property>
-                                    <name>sharedtype.rust.custom-code-path</name>
-                                    <value>it/custom-code.rs</value>
-                                </property>
-                            </properties>
-                        </configuration>
-                    </execution>
-                </executions>
-            </plugin>
         </plugins>
     </build>
     <profiles>
@@ -174,6 +148,20 @@
                                     </sources>
                                 </configuration>
                             </execution>
+                            <execution>
+                                <id>add-test-resource</id>
+                                <phase>generate-test-resources</phase>
+                                <goals>
+                                    <goal>add-test-resource</goal>
+                                </goals>
+                                <configuration>
+                                    <resources>
+                                        <resource>
+                                            <directory>${project.build.directory}/generated-sources</directory>
+                                        </resource>
+                                    </resources>
+                                </configuration>
+                            </execution>
                         </executions>
                     </plugin>
                 </plugins>

it/sharedtype.properties

@@ -10,3 +10,7 @@ sharedtype.typescript.type-mappings=online.sharedtype.it.java8.types.MyType1:Arr
 sharedtype.rust.type-mappings=online.sharedtype.it.java8.types.MyType1:Vec
 
 sharedtype.go.type-mappings=online.sharedtype.it.java8.types.MyType1:[]
+
+sharedtype.typescript.custom-code-path=it/custom-code.ts
+sharedtype.go.custom-code-path=it/custom-code.go
+sharedtype.rust.custom-code-path=it/custom-code.rs

maven-plugin/it/.mvn/wrapper/maven-wrapper.properties

@@ -0,0 +1,21 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you 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
+#
+#   http://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.
+wrapperVersion=3.3.2
+distributionType=only-script
+
+# This is for Maven compatibility test
+distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.2.5/apache-maven-3.2.5-bin.zip

maven-plugin/it/mvne

@@ -0,0 +1,4 @@
+#!/bin/sh
+
+export MAVEN_OPTS="-Xdebug -Xnoagent -Xint -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005 $MAVEN_OPTS"
+./mvnw "$@"