Skip to content

Commit b303b48

Browse files
cuzfrogcuzfrog
authored
108 maven plugin (#152)
* Add maven plugin module * Supply userProps to processor programmatically * Pass individual user props from plugin config * Failfast when custom code file does not exist * Add maven 3.2 compatibility test * Add diagnostic logging for maven plugin * Update doc * Fix java8 javac loading
1 parent 35e39b7 commit b303b48

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

41 files changed

+1245
-145
lines changed

‎.github/workflows/ci.yaml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,9 @@ jobs:
4848
run: ./mvnw install -e --ntp -B
4949
- name: Test JPMS
5050
run: ./mvnw clean verify -pl it/java8 -P it-jpms -e --ntp -B
51+
- name: Test Maven 3.2.5 compatibility
52+
working-directory: maven-plugin/it
53+
run: ./mvnw stype:gen -e -B
5154
- name: Javadoc
5255
run: ./mvnw -P release javadoc:javadoc --ntp -B
5356
- name: Upload generated sources
@@ -93,6 +96,9 @@ jobs:
9396
key: build_maven
9497
- name: Test
9598
run: ./mvnw verify -pl it/java8 -e --ntp -B
99+
- name: Maven Plugin Test
100+
working-directory: maven-plugin/it
101+
run: ./mvnw stype:gen -e -B
96102

97103
client_test:
98104
needs: [build_and_test]

‎README.md‎

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
[![CI](https://github.com/cuzfrog/sharedtype/actions/workflows/ci.yaml/badge.svg)](https://github.com/cuzfrog/sharedtype/actions/workflows/ci.yaml)
55
[![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)
66

7-
# SharedType - Sharing Java Types made easy
7+
# SharedType - Lightweight Java Type Sharing
88
From Java:
99
```java
1010
@SharedType
@@ -36,13 +36,11 @@ pub struct User {
3636
```
3737

3838
## Features
39-
* Java8 compatible; Java 9 module (Jigsaw) compatible.
39+
* Java8+ compatible.
4040
* Generics support.
4141
* Compile-time constant support.
42-
* Client source dependency is only `@SharedType` retained at source code level.
43-
* SharedType annotation processor has only 1 dependency: [mustache](https://github.com/spullara/mustache.java).
44-
* Parsing takes milliseconds with `-proc:only`.
45-
* Intuitive defaults, put `@SharedType` and there you go. Global + class level options.
42+
* Fast. (Execution takes milliseconds with `-proc:only`.)
43+
* Simple global + type level configurations.
4644

4745
## Documentation
4846
* [User Guide](doc/Usage.md)

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

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -157,8 +157,7 @@
157157
* <b>Custom code snippet:</b><br>
158158
* Clients can provide custom code snippets to be injected into the emitted file.
159159
* This can be useful when e.g. a 3rd party type is referenced at client code.
160-
* By default, SharedType will search files "sharedtype-custom-code.ts", "sharedtype-custom-code.rs" respectively on cmd path.
161-
* File paths can be configured via global properties.
160+
* Custom code file paths can be configured via global properties.
162161
* </p>
163162
*
164163
* <br>

‎doc/Development.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ Internal types also have javadoc for more information.
1414
* `java17` uses symlink to reuse types in `java8` then does more type checks, e.g. for Java `record`.
1515
* `client-test` contains target languages' tests respectively against generated code.
1616
* `e2e` contains e2e json 2-way serialization and deserialization tests against target languages' http servers.
17+
* `maven-plugin` contains maven plugin for SharedType annotation, and `maven-plugin/it` contains integration tests for maven plugin.
1718

1819
Domain types are shared among processor and integration tests to reduce maven module count.
1920

@@ -83,6 +84,12 @@ Compile specific classes, **along with debug, this is useful for developing a sp
8384
./mvnw clean compile -pl it/java17 -DcompileClasses=online/sharedtype/it/java8/TempClass.java
8485
```
8586

87+
### Maven Plugin Development
88+
Debug Maven plugin IT:
89+
```bash
90+
mvnd -pl maven-plugin clean install && ./mvne -pl maven-plugin/it sharedtype:gen
91+
```
92+
8693
## Coding Style Guide / Keep it simple
8794
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.
8895
2. no adding dependencies without strong justification.

‎doc/Usage.md‎

Lines changed: 39 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -5,51 +5,38 @@ Menu:
55
* [Configurations](#Configurations)
66

77
## Setup
8-
98
### Maven
109

11-
Add sharedtype dependency, the annotation `@SharedType` is only used at compile time on source code:
12-
```xml
13-
<dependency>
14-
<groupId>online.sharedtype</groupId>
15-
<artifactId>sharedtype</artifactId>
16-
<version>${sharedtype.version}</version>
17-
<scope>provided</scope>
18-
<optional>true</optional>
19-
</dependency>
20-
```
21-
2210
Add Maven properties:
2311
```xml
2412
<properties>
25-
<compilerArg /> <!-- Placeholder -->
26-
<sharedtype.version>0.12.1</sharedtype.version>
27-
<sharedtype.enabled>false</sharedtype.enabled> <!-- Disable by default so not to participate in every compilation -->
13+
<sharedtype.version>0.13.0</sharedtype.version>
2814
</properties>
2915
```
30-
Setup annotation processing:
16+
17+
Add sharedtype-maven-plugin:
3118
```xml
3219
<plugin>
33-
<groupId>org.apache.maven.plugins</groupId>
34-
<artifactId>maven-compiler-plugin</artifactId>
35-
<configuration>
36-
<annotationProcessorPaths>
37-
<path>
38-
<groupId>online.sharedtype</groupId>
39-
<artifactId>sharedtype-ap</artifactId>
40-
<version>${sharedtype.version}</version>
41-
</path>
42-
</annotationProcessorPaths>
43-
<showWarnings>true</showWarnings> <!-- Show annotation processing info log -->
44-
<compilerArgs>
45-
<!-- supplied as properties from cmd -->
46-
<arg>${compilerArg}</arg>
47-
<arg>-Asharedtype.enabled=${sharedtype.enabled}</arg>
48-
</compilerArgs>
49-
</configuration>
20+
<groupId>online.sharedtype</groupId>
21+
<artifactId>sharedtype-maven-plugin</artifactId>
22+
<version>${project.version}</version>
5023
</plugin>
5124
```
5225

26+
Add sharedtype dependency:
27+
```xml
28+
<dependency>
29+
<groupId>online.sharedtype</groupId>
30+
<artifactId>sharedtype</artifactId>
31+
<version>${sharedtype.version}</version>
32+
<scope>provided</scope>
33+
<optional>true</optional>
34+
</dependency>
35+
```
36+
37+
`sharedtype-maven-plugin` requires Maven 3.2.5+.
38+
Annotation processing can also be setup and configured via `maven-compiler-plugin`, see [example](../it/pom.xml).
39+
The advantage of using `sharedtype-maven-plugin` is that no need to execute other annotation processors if there are multiple.
5340
## Usage
5441

5542
### A simple example
@@ -59,8 +46,8 @@ Annotate on a class:
5946
record User(String name, int age, String email) {}
6047
```
6148

62-
Execute annotation processing:
63-
* maven: `./mvnw compile -DcompilerArg=-proc:only -Dsharedtype.enabled=true`
49+
Execute:
50+
* maven: `./mvnw stype:gen` (Why `stype`? Because it's easy to type while explicitly enough to remember.)
6451

6552
By default, below code will be generated:
6653
```typescript
@@ -75,25 +62,29 @@ export interface User {
7562

7663
#### Global options
7764
By default, the file `sharedtype.properties` on current cmd path will be picked up.
78-
You can customize the path by config `maven-compiler-plugin`:
65+
You can customize the path:
7966
```xml
80-
<compilerArgs>
81-
<arg>-Asharedtype.propsFile=${your.properties.path}</arg>
82-
</compilerArgs>
67+
<plugin>
68+
<configuration>
69+
<propertyFile>${project.basedir}/sharedtype-my-custom.properties</propertyFile>
70+
</configuration>
71+
</plugin>
8372
```
8473

85-
Properties can also be passed in as system properties, which will override the properties files, e.g.
86-
```bash
87-
./mvnw clean compile -Dsharedtype.typescript.custom-code-path=it/custom-code.ts
88-
```
89-
or
90-
```bash
91-
MAVEN_OPTS="-Dsharedtype.typescript.custom-code-path=it/custom-code.ts" ./mvnw clean compile
74+
You can also specify individual properties:
75+
```xml
76+
<plugin>
77+
<configuration>
78+
<properties>
79+
<sharedtype.typescript.custom-code-path>${project.basedir}/custom-code.ts</sharedtype.typescript.custom-code-path>
80+
</properties>
81+
</configuration>
82+
</plugin>
9283
```
93-
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.
9484

95-
See [Default Properties](../processor/src/main/resources/sharedtype-default.properties) for details.
85+
See [Default Properties](../processor/src/main/resources/sharedtype-default.properties) for all property entries.
9686

87+
Execution goal `gen` can be bound to a Maven lifecycle phase.
9788
#### Per annotation options
9889
See Javadoc on [@SharedType](../annotation/src/main/java/online/sharedtype/SharedType.java) for details.
9990

‎it/pom.xml‎

Lines changed: 18 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
<?xml version="1.0" encoding="UTF-8"?>
2-
<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">
2+
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
3+
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
34
<modelVersion>4.0.0</modelVersion>
45
<parent>
56
<groupId>online.sharedtype</groupId>
@@ -13,7 +14,7 @@
1314
<packaging>pom</packaging>
1415

1516
<properties>
16-
<compilerArg />
17+
<compilerArg/>
1718
<sharedtype.propsFile>it/sharedtype.properties</sharedtype.propsFile>
1819
<compileClasses/>
1920
<excludeClasses/>
@@ -99,39 +100,12 @@
99100
<arg>${compilerArg}</arg> <!-- supplied from cmd "-Dsharedtype.compilerArg=-proc:only" -->
100101
<arg>-Asharedtype.propsFile=${sharedtype.propsFile}</arg>
101102
<arg>-Asharedtype.enabled=true</arg>
103+
<!-- Execute processor: ./mvnw compile -DcompilerArg=-proc:only -Dsharedtype.enabled=true -->
102104
</compilerArgs>
103105
<includes>${compileClasses}</includes>
104106
<excludes>${excludeClasses}</excludes>
105107
</configuration>
106108
</plugin>
107-
<plugin>
108-
<groupId>org.codehaus.mojo</groupId>
109-
<artifactId>properties-maven-plugin</artifactId>
110-
<version>1.2.1</version>
111-
<executions>
112-
<execution>
113-
<goals>
114-
<goal>set-system-properties</goal>
115-
</goals>
116-
<configuration>
117-
<properties>
118-
<property>
119-
<name>sharedtype.typescript.custom-code-path</name>
120-
<value>it/custom-code.ts</value>
121-
</property>
122-
<property>
123-
<name>sharedtype.go.custom-code-path</name>
124-
<value>it/custom-code.go</value>
125-
</property>
126-
<property>
127-
<name>sharedtype.rust.custom-code-path</name>
128-
<value>it/custom-code.rs</value>
129-
</property>
130-
</properties>
131-
</configuration>
132-
</execution>
133-
</executions>
134-
</plugin>
135109
</plugins>
136110
</build>
137111
<profiles>
@@ -174,6 +148,20 @@
174148
</sources>
175149
</configuration>
176150
</execution>
151+
<execution>
152+
<id>add-test-resource</id>
153+
<phase>generate-test-resources</phase>
154+
<goals>
155+
<goal>add-test-resource</goal>
156+
</goals>
157+
<configuration>
158+
<resources>
159+
<resource>
160+
<directory>${project.build.directory}/generated-sources</directory>
161+
</resource>
162+
</resources>
163+
</configuration>
164+
</execution>
177165
</executions>
178166
</plugin>
179167
</plugins>

‎it/sharedtype.properties‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,3 +10,7 @@ sharedtype.typescript.type-mappings=online.sharedtype.it.java8.types.MyType1:Arr
1010
sharedtype.rust.type-mappings=online.sharedtype.it.java8.types.MyType1:Vec
1111

1212
sharedtype.go.type-mappings=online.sharedtype.it.java8.types.MyType1:[]
13+
14+
sharedtype.typescript.custom-code-path=it/custom-code.ts
15+
sharedtype.go.custom-code-path=it/custom-code.go
16+
sharedtype.rust.custom-code-path=it/custom-code.rs

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

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Licensed to the Apache Software Foundation (ASF) under one
2+
# or more contributor license agreements. See the NOTICE file
3+
# distributed with this work for additional information
4+
# regarding copyright ownership. The ASF licenses this file
5+
# to you under the Apache License, Version 2.0 (the
6+
# "License"); you may not use this file except in compliance
7+
# with the License. You may obtain a copy of the License at
8+
#
9+
# http://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# Unless required by applicable law or agreed to in writing,
12+
# software distributed under the License is distributed on an
13+
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14+
# KIND, either express or implied. See the License for the
15+
# specific language governing permissions and limitations
16+
# under the License.
17+
wrapperVersion=3.3.2
18+
distributionType=only-script
19+
20+
# This is for Maven compatibility test
21+
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‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
#!/bin/sh
2+
3+
export MAVEN_OPTS="-Xdebug -Xnoagent -Xint -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005 $MAVEN_OPTS"
4+
./mvnw "$@"

0 commit comments

Comments
 (0)