🥳 New Feature 🥳 PlantUML visualization

[pdalfarr]

The goal of this PR is to add the ability to dump a Spring stateMachine to PlanUML State Diagram format and to .png format 🥳

Features:

1. Diagram Visualization 👁️ Allow you to 'visualize' your Spring State Machine as .puml or .png !

2. Current transition Highlight 🎯 If a state machine is dumped at org.springframework.statemachine.StateContext.Stage.TRANSITION_END phase, a red arrow is used between the 'source' state and the 'target' state. see https://github.com/spring-projects/spring-statemachine/blob/59df160f001877d59b32c24128f4b1a0f8dffa96/spring-statemachine-uml/src/main/java/org/springframework/statemachine/plantuml/PlantUmlWriterParameters.java#L246-L248

3. Actions and Guards description 🪪 Support BeanAware for Actions and Guards, so bean names are used in diagram -> much better than having labels like Action@0x1f4f5d1d

4. SpEL Expression support 🟰 Support for SpelExpressionAction and SpelExpressionGuard : SpEL expression is used as label.

5. Allow to 'tweak' the Diagram

• Modifying PlantUML diagram settings 🎚️
• Forcing Transition directions ➡️
• Hiding some transitions 🙈
• Adding a text note on State 📝

Unit tests:

1. Instantiate a Spring State Machine by loading (already existing) .uml file from test folder
2. Creating a PlantUML text representation of this state machine
3. Comparing it to to expected result 'see (new) .puml files in test folder)

What does it looks like?

Here are some results (I dumped .puml files to .png):

action-with-transition-choice.uml -> action-with-transition-choice.puml :

multijoin-forkjoin.uml -> multijoin-forkjoin.puml :

Note: Two *.uml files from test folder leads to inaccurate diagram. These 2 errors, in simple-connectionpointref.puml and simple-root-regions.puml, are likely to be related to some limitations in spring statemachine UML parser.

Credit: The idea of creating this feature came to me while reading https://github.com/DeveloperUtils/spring-state-machine-chart-dumper

[pivotal-cla]

@pdalfarr Please sign the Contributor License Agreement!

Click here to manually synchronize the status of this Pull Request.

See the FAQ for frequently asked questions.

[libinbin880521]

这是来自QQ邮箱的假期自动回复邮件。   您好，我最近正在休假中，无法亲自回复您的邮件。我将在假期结束后，尽快给您回复。

[pivotal-cla]

@pdalfarr Thank you for signing the Contributor License Agreement!

[pdalfarr]

Hi @bclozel I would like some Spring members to tell me if this PR can be useful for the Spring State Machine project or not. It turns out that you are second in the list of contributors here, hence this message for you 😄 Can I kindly ask you to have a look at this. I would be happy to elaborate more on why I think this could be useful to the project. Kind Regards, Pascal

[bclozel]

Hi there! This is probably a UI bug in GitHub as I don't remember contributing to statemachine and I'm not listed here https://github.com/spring-projects/spring-statemachine/graphs/contributors?from=2015-02-01&to=2024-07-12&type=c

[pdalfarr]

@bclozel Thanks for your reply. Yes, this is likely a bug: your avatar is visible in second position on main page of the project and you did not contribute indeed.

I see you are a committer on some Spring projects, so I take the opportunity to ask you this: how I can do to reach out to Spring State Machine "owner(s)" ? It looks like many PR are waiting here (not only mine) and I do not see much activity in Spring State Machine GitHub project. Should we (user of Spring State Mchine) worry about this? Is Spring State Machine still properly maintained?

( ? Maybe someone at Pivotal / VMWare could help regarding my questions ? )

[bclozel]

I think @jvalkeal knows.

[pdalfarr]

Hi @jvalkeal

Who can I reach out to, to discuss this PR?

Thanks

[pdalfarr]

@fmbenhassine , we can discuss this whenever you want ;-)

[fmbenhassine]

Hi @pdalfarr ,

Thank you for your time and effort to contribute this PR! This is a useful feature and would be a great addition to SSM 👍 . However, before digging into the details of this PR, I would like to validate a licensing issue: you are using the net.sourceforge.plantuml.SourceStringReader class from the net.sourceforge.plantuml:plantuml-lgpl module. This is LGPL code that is incompatible with the Apache License of SSM [1][2]. I tried to check if there is an ASL version of net.sourceforge.plantuml.SourceStringReader, but I could not find one. There is a copy of that code under the Eclipse license here, but I could not find one for ASL.

Can you please check? Unfortunately, without an ASL compatible license, we cannot merge this PR (unless you replace that code with something else).

[1]: https://www.apache.org/licenses/GPL-compatibility.html [2]: https://opensource.stackexchange.com/questions/8793/can-i-commit-lgpl3-derivative-work-to-an-apache-2-licensed-project

[pdalfarr]

Hi @fmbenhassine ! Thanks for your kind message :-)

I just made a change. Is this OK with net.sourceforge.plantuml:plantuml-asl:1.2025.2? Cfr https://github.com/spring-projects/spring-statemachine/pull/1158/commits/f8507fb32ce52996c88994e3dd853c998335b596

( see https://sakirtemel.github.io/plantuml-alternative-docs/docs/main/faq.html#_i_dont_like_gpl )

[pdalfarr]

@fmbenhassine I am trying to fix "DCO Action required after 1s — DCO" regarding Signed-off-by: Author Name [email protected], but it looks like the changes I made are not taken into account.

On my side, I now see the required Signed-off on my commits, but the DCO issue is still listed here :/ I am afraid I wasn't able to fix this, and I must confess I don't know how to do

cfr

[fmbenhassine]

Thank you for your feedback! The DCO issue is due to the fact that there are some commits among the 41 commits in that PR that are not signed off. You will need to squash all commits anyway.

Is this OK with net.sourceforge.plantuml:plantuml-asl:1.2025.2?

Yes, we can use that as long as the source code is available. Where is the source code of that module? We need the source code, not only a binary dependency. I also took some time to review the PR, and we need some updates:

• Please remove Lombok usage and replace it with Java records (use regular classes if you need mutability)
• The feature is about generating PlantUML diagrams and should focus on that. The code that generates images should be separate from that feature (one may ask why png and not jpeg?). This can be a utility class separate from the one that is related to the main feature. We can even have a separate PR that adds the ability to generate images from PlantUML diagrams as well as the existing Papyrus UML diagrams.
• Please add javadocs to public APIs (at least the main methods of the feature that users will use the most).

Please let me know if I can help on any of these.

Apart from that, I just wanted to mention that we have no plan to ship a feature release for v4 for the moment (only bug fixes are planned for now). So this PR will target v5 at a minimum.

[pdalfarr]

Thanks for your feedback.

1. Source jar for plantuml-asl-1.2025.2.jar is available here : https://repo1.maven.org/maven2/net/sourceforge/plantuml/plantuml-asl/1.2025.2/ https://repo1.maven.org/maven2/net/sourceforge/plantuml/plantuml-asl/1.2025.2/plantuml-asl-1.2025.2-sources.jar
2. Okay, I'll remove Lombok.
3. I'll (re)move png generation feature and probably create a dedicated PR for it. This makes sense.
4. Javadoc addition on public API: Roger that!

Thanks for the clarification on which version of SSM will likely ship this pull request 👍

[ouaibsky]

Hey,

looks like sprint state machine won't be under open source license (https://spring.io/blog/2025/04/21/spring-cloud-data-flow-commercial)

How it will work with this very interesting PR ?

[pdalfarr]

@ouaibsky maybe we could create a library which contains this code. I don't have much time to do this at the moment, but if you want to take my code and do it, feel free to do so 😉

[ouaibsky]

@pdalfarr , could you rebase to latest main ? Will see if we can progress on this, Would be nice to merge this PR into the latest OS version !

[pdalfarr]

@ouaibsky Sorry, I've been neglecting this PR a bit. Right now, I just don't have the time to dedicate to updating this code with SSM 4. Maybe later, but right now it's really not possible. You can take my PR and create a new one and do this work if you like. I might come back to this code in early 2026. ( Also, this PR was removed from Milestone 5.x, which is a bit disappointing for me. But that's the way it is. ) FYI, I am using this code in my project and it's working fine ;-)

[libinbin880521]

这是来自QQ邮箱的假期自动回复邮件。   您好，我最近正在休假中，无法亲自回复您的邮件。我将在假期结束后，尽快给您回复。

[ouaibsky]

@ouaibsky Sorry, I've been neglecting this PR a bit. Right now, I just don't have the time to dedicate to updating this code with SSM 4. Maybe later, but right now it's really not possible. You can take my PR and create a new one and do this work if you like. I might come back to this code in early 2026. ( Also, this PR was removed from Milestone 5.x, which is a bit disappointing for me. But that's the way it is. ) FYI, I am using this code in my project and it's working fine ;-)

Finally because of the end of support, I rewrotte a basic state machine framework with plantuml exporter.