🥳 New Feature 🥳 PlantUML visualization #1158

pdalfarr · 2024-07-05T08:49:48Z

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:

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

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

spring-statemachine/spring-statemachine-uml/src/main/java/org/springframework/statemachine/plantuml/PlantUmlWriterParameters.java

Lines 246 to 248 in 59df160

    
           public String getArrowColor(boolean isCurrentTransaction) { 
        
               return isCurrentTransaction ? "[#FF0000]" : ""; 
        
           }

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
SpEL Expression support 🟰
Support for SpelExpressionAction and SpelExpressionGuard : SpEL expression is used as label.
Allow to 'tweak' the Diagram

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

Unit tests:

Instantiate a Spring State Machine by loading (already existing) .uml file from test folder
Creating a PlantUML text representation of this state machine
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

…to illustrate the issue

… image

pivotal-cla · 2024-07-05T08:49:50Z

@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 · 2024-07-05T08:50:27Z

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

pivotal-cla · 2024-07-05T09:04:26Z

@pdalfarr Thank you for signing the Contributor License Agreement!

pdalfarr · 2024-07-05T15:11:28Z

...emachine-uml/src/test/java/org/springframework/statemachine/plantuml/PlantUmlWriterTest.java

+                // It seems Spring statemachine does not support org.eclipse.uml2.uml.ConnectionPointReference !
+                // Arguments.of("org/springframework/statemachine/uml/simple-connectionpointref", null),


Limitation in Spring state machine ?

pdalfarr · 2024-07-05T15:11:43Z

...emachine-uml/src/test/java/org/springframework/statemachine/plantuml/PlantUmlWriterTest.java

+                // It seems Spring statemachine UML parser creates duplicated transitions!
+                // Arguments.of("org/springframework/statemachine/uml/simple-root-regions", null),


Bug in Spring state machine ?

pdalfarr · 2024-07-05T15:12:20Z

...emachine-uml/src/test/java/org/springframework/statemachine/plantuml/PlantUmlWriterTest.java

+                        new PlantUmlWriterParameters<String>()
+                                .hiddenTransition("S1", RIGHT, "S2")
+                ),
+                Arguments.of("org/springframework/statemachine/uml/simple-guards", null),
+                Arguments.of("org/springframework/statemachine/uml/simple-history-deep", null),
+                Arguments.of("org/springframework/statemachine/uml/simple-history-default", null),
+                Arguments.of("org/springframework/statemachine/uml/simple-history-shallow", null),
+                Arguments.of("org/springframework/statemachine/uml/simple-junction", null),
+                Arguments.of("org/springframework/statemachine/uml/simple-localtransition",
+                        // add some parameters to make diagram more readable
+                        new PlantUmlWriterParameters<String>()
+                                .arrowDirection("S22", UP, "S2")
+                                .arrowDirection("S21", UP, "S2")
+                                .arrowDirection("S22", UP, "S2")
+                                .arrowDirection("S21", UP, "S2")


PlantUmlWriterParameters allow to tweak diagram by 'forcing' direction of some arrows / transitions

… tests resources accordingly

pdalfarr · 2024-07-12T07:00:02Z

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 · 2024-07-12T07:03:44Z

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 · 2024-07-12T07:08:49Z

...temachine-uml/src/main/java/org/springframework/statemachine/plantuml/helper/NameGetter.java

+	/**
+	 * Implement a 'name strategy' based on this sequence:
+	 * <UL>
+	 * <LI>{@link Expression}</LI>
+	 * <LI>{@link BeanNameAware}</LI>
+	 * <LI>Lambda's unique "arg$1" parameter</LI>
+	 * </UL>
+	 * If all these strategy are failing, fallback to "class name" of the object
+	 *
+	 * @param object object to get "name" from
+	 * @return name of the object
+	 */
+	public static String getName(Object object) {


This class should probably be compared to

spring-statemachine/spring-statemachine-autoconfigure/src/main/java/org/springframework/statemachine/boot/support/BootStateMachineMonitor.java

Lines 137 to 143 in 26ef2bc

private static <S, E> String actionToName(Function<StateContext<S, E>, Mono<Void>> action) {

return ObjectUtils.getDisplayString(action);

}

private static <S, E> String actionFunctionToName(Function<StateContext<S, E>, Mono<Void>> action) {

return ObjectUtils.getDisplayString(action);

}

which seems to be the current mean to get "names" of Spring State Machine actions, guard, etc..

pdalfarr · 2024-07-12T11:11:58Z

@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 · 2024-07-12T12:49:22Z

I think @jvalkeal knows.

pdalfarr · 2024-07-12T13:00:45Z

Hi @jvalkeal

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

Thanks

… make 'Connection' cComparable

pdalfarr · 2024-10-21T12:58:20Z

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

pdalfarr · 2025-03-04T14:02:50Z

...ne-uml/src/main/java/org/springframework/statemachine/plantuml/PlantUmlWriterParameters.java

+	public PlantUmlWriterParameters<S> note(S state, String note) {
+		// escape line return in note as it must fit in one single line
+		note = note
+				.replace("\n", "\\n")
+				.replace("\r", "\\r")
+		;
+		stateNotes.put(state, note);
+		return this;
+	}


New Feature:
"Adding a note" 📝 on State :-)

See

spring-statemachine/spring-statemachine-uml/src/test/java/org/springframework/statemachine/plantuml/PlantUmlWriterTest.java

Lines 80 to 87 in 9ed56eb

Arguments.of("org/springframework/statemachine/uml/simple-localtransition",

// add some parameters to make the diagram more readable

new PlantUmlWriterParameters<String>()

.arrow("S22", UP, "S2", 2)

.arrow("S21", UP, "S2", 2)

.note("S1", "This is the\nS1 State")

.note("S2", "This is the\nS2 State")

),

And https://github.com/spring-projects/spring-statemachine/blob/3b29592cb1b5cb383ede8530c919474d6d9cd10d/spring-statemachine-uml/src/test/resources/org/springframework/statemachine/uml/simple-localtransition.png?raw=true

Pascal Dal Farra added 6 commits March 4, 2024 16:35

test: add testStateMachineVsStateMachineModelConsistency()

5f7a0e9

test: testStateMachineVsStateMachineModelConsistency() add png image …

79eb82a

…to illustrate the issue

test: testStateMachineVsStateMachineModelConsistency() update png

2d07152

test: testStateMachineVsStateMachineModelConsistency() update javadoc…

3a496b4

… image

Merge branch 'main' of https://github.com/pdalfarr/spring-statemachine

b7d2387

feat: add PlantUml rendering feature

1381468

pdalfarr changed the title ~~PlantUML visualization~~ New Feature - PlantUML visualization Jul 5, 2024

feat: illustrate use of hiddenTransitions

238be9c

pdalfarr commented Jul 5, 2024

View reviewed changes

Pascal Dal Farra added 6 commits July 9, 2024 15:48

fix: fix NPE

1fca598

fix: Fix TransitionComparator

5f1a4f4

fix: Fix TransitionComparator

a7b2add

chore: code cleaning

961f5ce

feat: add global diagram settings + update arrow colors + update unit…

59df160

… tests resources accordingly

chore: Add Apache license header

935fa33

pdalfarr commented Jul 12, 2024

View reviewed changes

Pascal Dal Farra added 2 commits July 17, 2024 16:00

chore: make attributes private

bbab08e

feat: improve NameGetter (AopProxyUtils) + add 'ignoredTransitions' +…

ceecb4e

… make 'Connection' cComparable

feat: add arrow length parameter

42ccaa4

Pascal Dal Farra and others added 3 commits November 7, 2024 08:49

chore: keep hiddenTransitions sorted + fix getArrowLength

7245eba

feat: add PlantUmlWriterParameters.note()

b77ee89

Merge branch 'spring-projects:main' into main

9ed56eb

pdalfarr commented Mar 4, 2025

View reviewed changes

feat: add PlantUmlWriterParameters.note() - update png

3b29592

pdalfarr changed the title ~~New Feature - PlantUML visualization~~ 🥳 New Feature 🥳 PlantUML visualization Mar 5, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

🥳 New Feature 🥳 PlantUML visualization #1158

🥳 New Feature 🥳 PlantUML visualization #1158

pdalfarr commented Jul 5, 2024 •

edited

Loading

pivotal-cla commented Jul 5, 2024

libinbin880521 commented Jul 5, 2024 via email

pivotal-cla commented Jul 5, 2024

pdalfarr Jul 5, 2024

pdalfarr Jul 5, 2024

pdalfarr Jul 5, 2024

pdalfarr commented Jul 12, 2024

bclozel commented Jul 12, 2024

pdalfarr Jul 12, 2024

pdalfarr commented Jul 12, 2024

bclozel commented Jul 12, 2024

pdalfarr commented Jul 12, 2024

pdalfarr commented Oct 21, 2024

pdalfarr Mar 4, 2025 •

edited

Loading

	public String getArrowColor(boolean isCurrentTransaction) {
	return isCurrentTransaction ? "[#FF0000]" : "";
	}

		// It seems Spring statemachine does not support org.eclipse.uml2.uml.ConnectionPointReference !
		// Arguments.of("org/springframework/statemachine/uml/simple-connectionpointref", null),

		// It seems Spring statemachine UML parser creates duplicated transitions!
		// Arguments.of("org/springframework/statemachine/uml/simple-root-regions", null),

	private static <S, E> String actionToName(Function<StateContext<S, E>, Mono<Void>> action) {
	return ObjectUtils.getDisplayString(action);
	}

	private static <S, E> String actionFunctionToName(Function<StateContext<S, E>, Mono<Void>> action) {
	return ObjectUtils.getDisplayString(action);
	}

	Arguments.of("org/springframework/statemachine/uml/simple-localtransition",
	// add some parameters to make the diagram more readable
	new PlantUmlWriterParameters<String>()
	.arrow("S22", UP, "S2", 2)
	.arrow("S21", UP, "S2", 2)
	.note("S1", "This is the\nS1 State")
	.note("S2", "This is the\nS2 State")
	),

🥳 New Feature 🥳 PlantUML visualization #1158

Are you sure you want to change the base?

🥳 New Feature 🥳 PlantUML visualization #1158

Conversation

pdalfarr commented Jul 5, 2024 • edited Loading

pivotal-cla commented Jul 5, 2024

libinbin880521 commented Jul 5, 2024 via email

pivotal-cla commented Jul 5, 2024

pdalfarr Jul 5, 2024

Choose a reason for hiding this comment

pdalfarr Jul 5, 2024

Choose a reason for hiding this comment

pdalfarr Jul 5, 2024

Choose a reason for hiding this comment

pdalfarr commented Jul 12, 2024

bclozel commented Jul 12, 2024

pdalfarr Jul 12, 2024

Choose a reason for hiding this comment

pdalfarr commented Jul 12, 2024

bclozel commented Jul 12, 2024

pdalfarr commented Jul 12, 2024

pdalfarr commented Oct 21, 2024

pdalfarr Mar 4, 2025 • edited Loading

Choose a reason for hiding this comment

pdalfarr commented Jul 5, 2024 •

edited

Loading

pdalfarr Mar 4, 2025 •

edited

Loading